Back to Docs

Widget Documentation

Everything you need to integrate and customize the Engage Plus authentication widget

Widget Integration Guide

Complete guide to integrating the Engage Plus authentication widget into your application. Learn all available methods, events, and best practices.

Quick Start
Get up and running in under 5 minutes
<!-- 1. Add the widget script to your HTML -->
<script src="https://yourdomain.com/widget.js"></script>

<!-- 2. Add a container for the widget -->
<div id="engage-plus-widget"></div>

<!-- 3. Initialize the widget -->
<script>
  EngagePlus.init({
    clientId: 'your-client-id',
    redirectUri: window.location.origin + '/callback',
    issuer: 'https://yourdomain.com'
  });
</script>
Widget API Reference
All available methods and properties

EngagePlus.init(config)

Initialize the widget with your configuration. Must be called before using other methods.

clientIdrequired

Your unique client ID from the dashboard

redirectUrirequired

OAuth callback URL (must match dashboard config)

issuerrequired

Your Engage Plus domain

onLoginoptional

Callback function when user logs in

onLogoutoptional

Callback function when user logs out

onErroroptional

Callback function when authentication error occurs

authModeoptional

'redirect' or 'popup' (default: redirect)

stylesoptional

Custom styling options (see the Customization tab above)

EngagePlus.logout()

Log out the current user and clear all authentication data.

What this function does:

  • Clears session storage (user data, tokens, state)
  • Clears local storage (persisted user data)
  • Removes access_token, id_token, and refresh_token
  • Triggers the logout event
  • Calls the onLogout callback
  • Re-renders the login buttons
// Logout the current user
EngagePlus.logout();

// The logout() function will:
// 1. Clear all session and localStorage data
// 2. Remove user tokens and authentication state
// 3. Trigger the 'logout' event
// 4. Call the onLogout callback (if provided)
// 5. Re-render the login buttons

// Example with callback
EngagePlus.init({
  clientId: 'your-client-id',
  onLogout: function(user) {
    console.log('User logged out:', user.email);
    // Clear your app's state
    localStorage.removeItem('my-app-data');
    // Redirect to home page
    window.location.href = '/';
  }
});

// Later, when user clicks logout button
document.getElementById('logout-btn').addEventListener('click', function() {
  EngagePlus.logout();
});

EngagePlus.getUser()

Get the current authenticated user's data. Returns null if not authenticated.

Returns object with:

  • id - Unique user identifier
  • email - User's email address
  • firstName - First name (from given_name)
  • lastName - Last name (from family_name)
  • fullName - Full name
  • picture - Profile picture URL
  • emailVerified - Boolean, email verification status
// Check if user is authenticated
if (EngagePlus.isAuthenticated()) {
  // Get current user data
  const user = EngagePlus.getUser();
  
  console.log('User ID:', user.id);
  console.log('Email:', user.email);
  console.log('First Name:', user.firstName);
  console.log('Last Name:', user.lastName);
  console.log('Full Name:', user.fullName);
  console.log('Picture:', user.picture);
  console.log('Email Verified:', user.emailVerified);
  
  // Update your UI
  document.getElementById('user-name').textContent = user.fullName;
  document.getElementById('user-email').textContent = user.email;
} else {
  console.log('No user authenticated');
}

EngagePlus.isAuthenticated()

Check if a user is currently authenticated. Returns true or false.

if (EngagePlus.isAuthenticated()) {
  console.log('User is logged in');
  const user = EngagePlus.getUser();
} else {
  console.log('User is not logged in');
}

EngagePlus.on(event, callback)

Register an event listener. Events: login, logout, error

// Register event listeners BEFORE init()
EngagePlus.on('login', function(event) {
  const user = event.user;
  const provider = event.provider; // e.g., 'Google', 'GitHub'
  
  console.log(`User ${user.email} logged in via ${provider}`);
});

EngagePlus.on('logout', function(event) {
  const user = event.user;
  console.log(`User ${user.email} logged out`);
});

EngagePlus.on('error', function(error) {
  console.error('Auth error:', error);
});

// Initialize after registering listeners
EngagePlus.init({ /* config */ });

// You can also remove listeners
function myLoginHandler(event) {
  console.log('Login:', event.user.email);
}

EngagePlus.on('login', myLoginHandler);
// Later...
EngagePlus.off('login', myLoginHandler);

EngagePlus.off(event, callback)

Unregister an event listener. See example above for usage.

Event Handling
Three ways to handle authentication events

Recommended for most use cases. Pass callback functions directly in the init config.

EngagePlus.init({
  clientId: 'your-client-id',
  
  // Called when user successfully logs in
  onLogin: function(user) {
    console.log('User logged in!');
    console.log('Email:', user.email);
    console.log('Name:', user.firstName + ' ' + user.lastName);
    
    // Send to your backend
    fetch('/api/save-user', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(user)
    });
    
    // Update UI
    showWelcomeMessage(user);
  },
  
  // Called when user logs out
  onLogout: function(user) {
    console.log('User logged out:', user.email);
    
    // Clear your app's state
    localStorage.removeItem('my-app-data');
    sessionStorage.clear();
    
    // Redirect to home
    window.location.href = '/';
  },
  
  // Called when authentication error occurs
  onError: function(error) {
    console.error('Auth error:', error.error, error.description);
    
    // Show error message to user
    alert('Authentication failed: ' + error.description);
  }
});
Complete Integration Example
A full working example showing all major features
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App with Engage Plus</title>
</head>
<body>
  <!-- Widget Container -->
  <div id="engage-plus-widget"></div>
  
  <!-- User Info (hidden by default) -->
  <div id="user-info" style="display: none;">
    <h2>Welcome, <span id="user-name"></span>!</h2>
    <p>Email: <span id="user-email"></span></p>
    <button id="logout-btn">Logout</button>
  </div>

  <!-- Load Widget Script -->
  <script src="https://yourdomain.com/widget.js"></script>
  
  <script>
    // Initialize widget
    EngagePlus.init({
      clientId: 'your-client-id',
      redirectUri: window.location.origin + '/callback.html',
      issuer: 'https://yourdomain.com',
      
      // Handle login
      onLogin: function(user) {
        // Hide widget, show user info
        document.getElementById('engage-plus-widget').style.display = 'none';
        document.getElementById('user-info').style.display = 'block';
        
        // Update UI
        document.getElementById('user-name').textContent = user.fullName || user.email;
        document.getElementById('user-email').textContent = user.email;
        
        // Save to your backend
        fetch('/api/auth/login', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(user)
        });
      },
      
      // Handle logout
      onLogout: function(user) {
        // Show widget, hide user info
        document.getElementById('engage-plus-widget').style.display = 'block';
        document.getElementById('user-info').style.display = 'none';
        
        // Clear backend session
        fetch('/api/auth/logout', { method: 'POST' });
      },
      
      // Handle errors
      onError: function(error) {
        alert('Authentication failed: ' + error.description);
      }
    });
    
    // Check if user is already logged in
    if (EngagePlus.isAuthenticated()) {
      const user = EngagePlus.getUser();
      // Trigger the same UI updates
      document.getElementById('engage-plus-widget').style.display = 'none';
      document.getElementById('user-info').style.display = 'block';
      document.getElementById('user-name').textContent = user.fullName || user.email;
      document.getElementById('user-email').textContent = user.email;
    }
    
    // Setup logout button
    document.getElementById('logout-btn').addEventListener('click', function() {
      EngagePlus.logout();
    });
  </script>
</body>
</html>
OAuth Callback Page Setup
Create a callback.html page to handle the OAuth redirect
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Authentication Callback</title>
</head>
<body>
  <p>Completing authentication...</p>
  
  <!-- Load Widget Script -->
  <script src="https://yourdomain.com/widget.js"></script>
  
  <script>
    // Initialize with same config as main page
    EngagePlus.init({
      clientId: 'your-client-id',
      redirectUri: window.location.origin + '/callback.html',
      issuer: 'https://yourdomain.com'
    });
    
    // Widget will automatically handle the OAuth callback
    // and redirect back to your main page
  </script>
</body>
</html>
Best Practices
  • ✓Always call EngagePlus.logout() when implementing your own logout button to ensure all session data is properly cleared.
  • ✓Check isAuthenticated() on page load to detect existing sessions and update your UI accordingly.
  • ✓Use onLogin callback to sync user data with your backend immediately after authentication.
  • ✓Handle errors gracefully using the onError callback to provide good user experience.
  • ✓Test both redirect and popup modes to choose what works best for your application.
  • !Never expose sensitive data in client-side code. Always validate authentication on your backend.
  • !Don't rely solely on client-side state. Use the tokens to verify the user's session with your backend API.
Related Documentation
Widget Customization
Style the widget to match your brand (see Customization tab)
Webhook Integration
Receive real-time authentication events
Database Integrations
Sync users to your database automatically
Widget Configuration
Configure providers and settings

Ready to integrate?

Get your client ID and start adding authentication to your app today.