Account Hosted Widget

The Account Hosted Widget enables you to embed Cleeng’s account management flow directly into your web application. It allows users to update their account details and manage their subscriptions, ensuring secure handling of personal and billing information.

📘

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.

A refreshed design of the account widget will be launched soon.

If you want to learn more about Hosted Widgets, review the currently supported features, and see how they compare to other integration methods, see our overview of available frontend integration options and their benefits.

Prerequisites

Before you begin, make sure you have:

1. Cleeng account: Create one here.
2. At least one offer created in the Cleeng dashboard: Learn more about Cleeng offers.
3. Payment methods enabled for your account (if not already enabled, contact Cleeng Support).

   📘

   To ensure you have any Adyen payment method enabled, call Fetch payment method ids.

Code Integration

To embed a Cleeng widget, follow these steps:

1. Include the Cleeng-hosted script in your HTML file

🚧

If your application already uses another Cleeng widget and has included the cleeng.js script, skip this step.

In the index.html, or any HTML file of your app that will be loaded before using a Cleeng widget, include a Cleeng-hosted script.

🚧

The script must be loaded from Cleeng’s domain to ensure it is always up to date.

Do not attempt to self-host cleeng.js script, as it carries a risk of incompatibility in case of any product updates and security enhancements.

<script type="module" src="https://widgets.sandbox.cleeng.com/cleeng.js"></script>

For the production environment, the URL for the script will be different:

2. Create a container for the widget

Create an empty HTML container, e.g., <div /> element, with required data as data-* attributes, as in the example below:

<div
  data-cleeng-widget="account"
  data-cleeng-publisher-id="123"
/>

Where:

• data-cleeng-widget: the specific Cleeng widget you would like to render. Supported values: auth, checkout, account.
• data-cleeng-publisher-id: Your unique Cleeng publisher ID (found in the Cleeng Dashboard under Admin & Tools > API Keys).

📘

To use Account widget customer needs to be authenticated. Either use the Auth widget first, or use the setAuthTokens method.

3. (Optional) Integrate with the widgets methods

Widgets provide a simple way to communicate with your application, which is especially useful in the case of:

• External identity provider (SSO) or
• Making additional requests to the Mediastore API.

You can integrate with the available global methods by following the steps in the Global Communication Methods Developer Guide.

Configuration in the Cleeng Dashboard

After embedding the widget, configure it using the dashboard configuration instructions. The configuration page lets you adjust widget behavior and branding without redeploying your code. All changes you make in the dashboard are applied automatically to the deployed widgets.

Testing

Before deploying, ensure proper functionality through testing:

1. Embed and load the Widget
   • Verify the widget appears correctly in your app
2. User Authentication
   • If you use the default Cleeng identity management: Test user login and registration by the Auth widget.
   • If you use an external identity management: First, test your backend connection to Cleeng by ensuring that your system can successfully generate and retrieve JWT and refresh tokens via the SSO Login endpoint. Then, provide these tokens to the widgets (by setAuthTokens() method) and verify that authentication works correctly.
3. Account
   • Go through the account functionality, e.g., cancel subscription, downgrade plan, change payment method, update customer details

By following these steps, you can ensure a smooth and error-free integration before going live.

What’s next

Once implemented, an iframe containing the Cleeng widget will be embedded into your application. The widget will automatically apply settings configured in the dashboard and react to changes in the data-* attributes.

To use a different widget, update the data-cleeng-widget attribute with the desired widget name.