Auth Hosted Widget

The Auth Hosted Widget enables you to embed Cleeng’s authentication flow directly into your web application. It manages user login, registration, and password reset, streamlining user access while ensuring secure handling of identity data. By leveraging the widget, you can provide your customers with a seamless authentication experience without building custom login forms or managing sensitive credentials.

📘

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.

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.

   • Enabled by default: Card, Google Pay, Apple Pay (Apple Pay requires domain verification before it can be used in production. See 4. Apple Pay production environment setup)
   • To add PayPal: Contact Support to activate PayPal

   📘

   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

🚧

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:

<script type="module" src="https://widgets.prod.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="auth"
  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).

(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="auth"
  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.

(Optional) Open another view when the widget loads

Once the Auth widget is embedded, the login view is displayed by default.

To open another view (for example, registration) when the widget loads, add the relevant query parameter to the page URL where the widget is embedded.

For example, to open registration, add a query param cleengSection=register, eg, https://publisher-website.com/register?cleengSection=register

Available values: widget auth: login (default), register, passwordReset

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
   • Test user login and registration by the Auth widget. You can retrieve the tokens from the widget by using onAuthTokensUpdate() method.

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.

FAQs

How should I handle users who register on my website instead of through the Cleeng widget?

If a user creates an account directly on your website (outside the Cleeng widget), you need to register this user in Cleeng using the Register API.

After registration, you will receive the JWT and refresh token that are needed to authenticate the user in the widgets. To do so, use the setAuthTokens (see Cleeng Hosted Widgets: Global Communication Methods) method.

After that, you can open theCheckout widgetto allow the user to complete the purchase.

Can I check if a user is registered and get their details?

Yes. You can retrieve a user’s registration status and other account details using the available widget methods. For more information, see Hosted Widgets: Retrieving Customer Details.