API

These are the public methods of the DeepdotsPopups class. They cover everything a host application needs to mount the SDK, react to popups, and fire business events.

init(config)

Initializes the SDK and fetches the popup definitions from Deepdots.

popups.init({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  userId: 'customer-123', // optional
});

Field	Required	Description
apiKey	yes	Your Deepdots public API key.
userId	no	Identifier sent with every popup event.
contactAttributes	no	Internal user attributes to send to the Contact (requires userId). See setContactAttributes.

autoLaunch()

Starts the triggers derived from the definitions loaded during init(). Call once after init().

popups.autoLaunch();

triggerEvent(eventName)

Fires a custom business event. Any popup in Deepdots configured with an event trigger that matches eventName will be shown (subject to cooldowns and targeting).

popups.triggerEvent('checkout_completed');

See Triggers → event for details.

show({ surveyId, productId })

Shows a popup directly, bypassing triggers. Cooldowns and route targeting are still respected.

popups.show({
  surveyId: 'survey-home-001',
  productId: 'product-main',
});

showByPopupId(popupId)

Same as show(), but you address the popup by its Deepdots id instead of its survey/product pair.

popups.showByPopupId('popup-home-5s');

on(event, listener) / off(event, listener)

Subscribe to the SDK events: popup_shown, popup_clicked, survey_completed.

const onShown = (event) => analytics.track('popup_shown', event);

popups.on('popup_shown', onShown);
popups.off('popup_shown', onShown);

See Events for the full payload shape.

setContactAttributes(attributes)

Sends internal user attributes that only your application knows — language, age, plan, segment, etc. — to the user’s Contact in Deepdots, so they can be used for popup targeting and segmentation.

Requires a userId in init(): the attributes are tied to that identity (the same id from your own system). Attribute values must be string, number, or boolean.

const sent = await popups.setContactAttributes({
  language: 'es',
  age: 34,
  plan: 'premium',
});

The SDK only sends when the attributes changed since the last send — it keeps a diff in persistent storage — so you can call this on every user identification without generating extra requests. The returned promise resolves to:

• true — the attributes were sent to the backend.
• false — nothing changed since the last send (or tracking is disabled, or there is no userId).

Under the hood it performs POST /sdk/popups/contact with the body { publicKey, userId, userAttributes }. The Contact is created automatically on the first popup fetch, so no ordering is required.

You can also provide the initial attributes directly in init() via contactAttributes (equivalent to calling setContactAttributes right after init):

popups.init({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  userId: 'customer-123',
  contactAttributes: { language: 'es', plan: 'premium' },
});