The Claspo JavaScript API lets your website interact with Claspo widgets through two independent methods:
showWidget displays a specific widget when your website decides it should appear.
onWidgetEvents lets your website respond after a visitor submits contact data through a widget.
You can use either method separately or use both in the same flow. The onWidgetEvents method works regardless of how the widget was displayed.
Before you begin
Both methods require the widget’s formVariantId. To find it:
In your Claspo dashboard, select the widget you want to work with and open Triggering.
Scroll down to Call with JavaScript API.
Copy the code or the formVariantId value from it.
The value follows the f(form ID)v(variant ID) format. For example: ‘f244v244’.
Display a widget directly from your website code
Use showWidget when the display logic already exists in your website code. If your website only needs to pass a value or event while the display conditions remain configured in Claspo, you can use a JS variable or Data Layer instead.
Note
You can use this method alongside the widget’s rule-based display settings. Calling a widget through showWidget does not disable or replace them. The same widget can therefore appear automatically when its configured rules are met and also be displayed directly through your website code.
For example, you can use showWidget when:
A logged-in customer opens their account, and the store detects an unused loyalty reward and displays a widget with the offer.
A visitor completes an internal flow, such as calculating a price or configuring a service, and the website displays the relevant widget immediately afterward.
Specify which widget to display
Call the widget using the following method:
claspo('showWidget', {
formVariantId: 'f244v244'
});
Replace ‘f244v244’ with the value copied from the Call with JavaScript API section in your widget settings.
The formVariantId identifies the specific widget and its variant:
Parameter | Description |
formVariantId | The form ID and variant ID of the widget in the f(form ID)v(variant ID) format. |
Respond to contact data submissions
Use the onWidgetEvents method when your website needs to run custom logic after a visitor submits contact data through a widget.
This method does not display the widget. It listens for supported widget events and works regardless of whether the widget was shown through rule-based settings or called through showWidget.
Currently, the method supports one event: CONTACT_DATA_SUBMIT.
claspo(
'onWidgetEvents',
{
formVariantId: 'f244v244'
},
({ type }) => {
if (type === 'CONTACT_DATA_SUBMIT') {
console.log('Contact data submitted');
}
}
);
Parameter or event | Description |
formVariantId | The form ID and variant ID of the widget in the f(form ID)v(variant ID) format. |
CONTACT_DATA_SUBMIT | Fires when a visitor submits contact data through the widget. |
In this example, the code writes a message to the browser console after the visitor submits contact data. You can replace console.log() with any custom logic required by your website.
For example, after a submission, your website can:
Continue an internal flow by opening a calculator result, providing access to a report, or moving the visitor to the next step of a web application.
Send the conversion to an analytics platform, Data Layer, or internal system together with context available only on your website, such as an account ID, customer tier, calculation result, or experiment variant.
Choose the method that best fits where your website logic lives — in Claspo or directly in your code. For other ways to control widget display, see our guides on display rules.