API Tutorials
HELP CENTERINTEGRATIONSSTATUS PAGELOGINGET STARTED FREE
Start typing to search…

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.

📘

Hosted customer flows are currently in Early Access. This means they're ready for real-world use while we gather user feedback to enhance their 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 customer flows, 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: no setup required for the default configuration.

    📘

    Note: Payments start processing only after your account is verified (see Go-Live Checklist, step 6).

    Optional: Sandbox

    If you test the widget in Sandbox, you must enable Merchant manually.

    1. Go to Admin & Tools > Integration Hub.
    2. Under Cleeng Configurations, open Merchant.
    3. Click Connect and complete the setup.

     

    Note:
    • Sandbox settings do not affect your production account.
    • You don’t need to complete account verification to test payments on Sandbox.

Code Integration

To embed a Cleeng widget, follow these steps:

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

🚧

Note:

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

  • 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.

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 in the <head> section of the document.

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

Optional: Sandbox

If you test the widget in Sandbox, the URL for the script will be different:

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

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"
	data-cleeng-language="en-US"
/>

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).
  • data-cleeng-language: The language displayed to the end user. Supported values: en-US English, nl-NL Dutch, de-DE German, fr-FR French, pt-BR Portuguese (Brazil), pt-PT Portuguese (Europe), es-ES Spanish. If you omit this attribute, the widget defaults to English en-US.

(Optional) Sync widget language with your site

If your website lets users switch languages (for example, through a dropdown), you can update the widget language at the same time. This keeps your page and the widget aligned without reloading the page.

Below is an example of how you can do it. In this example, the id attribute is used to identify the widget container because it is the simplest approach. However, you can select the element in any way that fits your setup.

<div
  id="cleeng—widget"
  data-cleeng-widget="account"
  data-cleeng-publisher-id="123"
  data-cleeng-offer-id="S123_US"
  data-cleeng-language="en-US"
/>
const widgetWrapper = document.getElementById("cleeng-widget")
widgetWrapper.dataset.cleengLanguage = "de-DE" // use any supported language

When the data-cleeng-language value changes, the widget automatically re-renders in the new language. There is no need to refresh the page or reinitialize the widget.

📘

Note:

  • This option is helpful only if your site already offers a language selector.
  • Ensure that the value you set is one of the supported locales.
📘

If the user is not authenticated when the Account widget is opened, the widget automatically displays the authentication flow (login or registration) first. After successful authentication, the Account view is displayed.

(Optional) Load a specific section

Once the Account widget is embedded, the left-hand menu with three tabs is displayed by default, with the planDetails section active.

To load a specific section without the menu, add the relevant query parameter to the page URL where the widget is embedded.

For example, to open the payment information view, add a query param cleengSection=paymentInfo, eg, https://publisher-website.com/account?cleengSection=paymentInfo

Available values: widget account: planDetails (default), paymentInfo, updateProfile

🚧

Important Configuration for External SSO

If you use an external Single Sign-On (SSO) provider, you must prevent users from editing their profiles or passwords within the Cleeng Account widget. This ensures your identity provider remains the single source of truth and avoids data conflicts.

To do this, use the cleengSection query parameter to force the widget to load only the parts of the widget you want to show. Allowed values: planDetails or paymentInfo.

Do NOT use updateProfile as a value for cleengSection when using an external SSO.

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.

Updated 17 days ago