Cleeng Hosted Widgets: Global Communication Methods

📘

Widgets have been introduced as a Beta feature, meaning it’s ready for real-world use while we gather user feedback to enhance its functionality and address any minor issues.

The Cleeng script exposes a global window.cleeng object to provide communication with your website. These methods are available regardless of the widget used.

1. Example of usage

🚧

Important

1. Remember that the Cleeng script should be added once to your application, in the head section.
2. Methods should be called only once in the entire application, typically in a general component such as App.js.

How it works: Add an event listener to the window object to listen for messages. For security, always verify the event.origin. When you receive a message with the type of CLEENG_SDK_LOADED, you can then safely call methods like window.cleeng.onAuthTokensUpdate.

Here is an example of an event listener:

const handleCleengMessage = (event) => {
  if (event.data?.type === 'CLEENG_SDK_LOADED') {
    // Now it's safe to interact with the window.cleeng object
    window.cleeng.onAuthTokensUpdate(({jwt, refreshToken}) => {
			if (jwt && refreshToken) {
    		// User is logged in - store tokens in your app
    		console.log('User authenticated');
  		} else {
    		// User is logged out
    		console.log('User logged out');
  		}
    });
  }
};

window.addEventListener('message', handleCleengMessage);

// Remember to remove the event listener when the component unmounts
// e.g., return () => window.removeEventListener('message', handleCleengMessage);

2. Supported Methods

onAuthTokensUpdate(callback)

Use this method to keep your application's authentication state synchronized with the Cleeng widgets. This is useful when you need to:

• Know when a user logs in or out,
• Get updated tokens for making API calls,
• Check if a user is currently authenticated.

Usage:

window.cleeng.onAuthTokensUpdate(({ jwt, refreshToken }) => {
  // Update your app's authentication state
  if (jwt && refreshToken) {
    // User is logged in - store tokens in your app
    console.log('User authenticated');
  } else {
    // User is logged out
    console.log('User logged out');
  }
});

Key Features:

• Immediate callback: Returns current token values right away when first called.
• Automatic updates: Triggers whenever tokens change (login, logout, refresh).
• Logout detection: Both tokens become null when user logs out.

Best Practice: Call this method once at the top level of your application (e.g., in your main app component) to ensure the listener persists across page navigation or other actions.

Before using: Always check that window.cleeng is available before calling its methods.

🚧

Note: Both tokens will have their value set to null when the end user has been logged out.

logout()

To ensure a consistent and secure user experience, when a user logs out from your main application, you should also programmatically log them out from the Cleeng widgets.

How it works: Call the window.cleeng.logout method. This function instructs the widgets to clear any session-related data they store. Then, the widgets respond by calling the callback function passed to window.cleeng.onAuthTokensUpdate, with null as the tokens’ values.

window.cleeng.logout();

setAuthTokens()

If your application uses an external identity provider, you can integrate Single Sign-On (SSO) with Cleeng’s widgets by programmatically passing authentication tokens.

After a user successfully logs in or registers through your external system, and you've generated the necessary jwt and refreshToken using Cleeng's SSO Login API endpoint, use the window.cleeng.setAuthTokens() method to authenticate the user in the widget.

This function sends the tokens to the widget and ensures that:

• The user's session is recognized across Cleeng widgets.
• The authenticated state remains synchronized when tokens are refreshed or reissued.

Call this method whenever the user's authentication state changes – the user logs in, logs out, or their tokens change. This keeps the frontend session in sync across your application and the Cleeng widgets.

Example:

// Set authentication tokens for all widgets
await window.cleeng.setAuthTokens({
  jwt: 'your-jwt-token',
  refreshToken: 'your-refresh-token'
});

As setAuthTokens method returns a Promise object, be sure to await its resolution. This way, you ensure that setting the authentication tokens will not be disrupted, and the application will proceed further only after this operation has finished.

onWidgetEvent(callback)

It is sent in various parts of the application (see the table of available UI events below).

You can subscribe to it via window.cleeng.onWidgetEvent() to respond to specific events — for example, to integrate with an analytics tool. This method returns the name and data property as below.

window.cleeng.onWidgetEvent(({ name, data }) => {
	console.log("Widget event arrived: ", {
		name,
		data,
	});
});