Skip to main content

​
Initialization Methods

​
init()

Initializes the SDK with configuration options. Must be called before any other methods. 
init(config: DeepdotsInitParams): void
​
config
DeepdotsInitParams
required
Configuration object for SDK initialization
Example: 
popups.init({
  mode: 'server',
  apiKey: 'YOUR_PUBLIC_API_KEY',
  userId: 'customer-123',
  nodeEnv: 'production',
  debug: false,
});
If init() is called when the SDK is already initialized, it will log a warning and return without re-initializing.
Source: deepdots-popups.ts:44-89

​
autoLaunch()

Enables auto-launch functionality with configured triggers. Starts all triggers derived from popup definitions. 
autoLaunch(): void
Behavior:
  • In client mode: Starts triggers immediately
  • In server mode: Waits for popup definitions to be fetched, then starts triggers
  • Throws error if SDK is not initialized
Example: 
popups.init({ mode: 'server', apiKey: 'YOUR_API_KEY' });
popups.autoLaunch(); // Triggers will start after popups are loaded
You must call init() before calling autoLaunch(), or an error will be thrown.
Source: deepdots-popups.ts:92-102

​
Display Methods

​
show()

Shows a popup immediately without waiting for a trigger. Supports both legacy options and popup definitions. 
show(options: PopupDefinition | { surveyId: string; productId: string; data?: Record<string, unknown> }): void
​
options
PopupDefinition | ShowOptions
required
Either a complete PopupDefinition object or legacy ShowOptions
Examples: 
popups.show({
  surveyId: 'survey-home-001',
  productId: 'product-main',
});
Source: deepdots-popups.ts:111-129

​
showByPopupId()

Shows a popup by its definition ID. Useful when multiple popups reuse the same surveyId. 
showByPopupId(popupId: string): void
​
popupId
string
required
The unique identifier of the popup definition to show
Example: 
popups.showByPopupId('popup-home-5s');
If no popup definition is found with the given ID, the method logs a debug message and returns without showing anything.
Source: deepdots-popups.ts:132-139

​
Event Methods

​
triggerEvent()

Triggers popups configured with trigger.type = 'event' and matching event name. Shows the first eligible popup that matches conditions and segments. 
triggerEvent(eventName: string): void
​
eventName
string
required
The event name to trigger. Must match the value field in popup definitions with triggers.type = 'event'
Example: 
// In your application code
popups.triggerEvent('search');
popups.triggerEvent('checkout_complete');
Behavior:
  • Normalizes and trims the event name
  • Finds all popup definitions with matching event triggers
  • Evaluates conditions (answered state, cooldown, segments)
  • Shows the first matching popup that passes all checks
  • Logs debug messages if no popups match or conditions block display
Empty or whitespace-only event names are ignored and logged in debug mode.
Source: deepdots-popups.ts:202-230

​
on()

Registers an event listener for SDK events. 
on(eventType: DeepdotsEventType, listener: EventListener): void
​
eventType
DeepdotsEventType
required
The type of event to listen for:
  • 'popup_shown': When a popup is displayed
  • 'popup_clicked': When a popup is interacted with
  • 'survey_completed': When a survey is completed
​
listener
EventListener
required
Callback function that receives the event object
type EventListener = (event: DeepdotsEvent) => void

interface DeepdotsEvent {
  type: DeepdotsEventType;
  surveyId: string;
  timestamp: number;
  data?: Record<string, unknown>;
}
Example: 
const onPopupShown = (event) => {
  console.log('Popup shown:', event.surveyId);
  console.log('Timestamp:', event.timestamp);
  console.log('Additional data:', event.data);
};

popups.on('popup_shown', onPopupShown);
popups.on('survey_completed', (event) => {
  // Track completion in analytics
  analytics.track('Survey Completed', {
    surveyId: event.surveyId,
    popupId: event.data?.popupId,
  });
});
Event Data Fields:
  • popup_shown: May include popupId, userId
  • popup_clicked: May include popupId, action, userId
  • survey_completed: May include popupId, userId
Source: deepdots-popups.ts:507-512

​
off()

Removes an event listener. 
off(eventType: DeepdotsEventType, listener: EventListener): void
​
eventType
DeepdotsEventType
required
The type of event to stop listening for
​
listener
EventListener
required
The exact listener function that was registered with on()
Example: 
const onShown = (event) => console.log(event);

popups.on('popup_shown', onShown);
// Later...
popups.off('popup_shown', onShown);
You must pass the exact same function reference that was used in on(). Anonymous functions cannot be removed.
Source: deepdots-popups.ts:515-520

​
Configuration Methods

​
configureTriggers()

Manually configures triggers for auto-launching popups. Normally triggers are derived automatically from popup definitions, but this method allows manual override. 
configueTriggers(triggers: TriggerConfig[]): void
​
triggers
TriggerConfig[]
required
Array of trigger configurations
Example: 
popups.configureTriggers([
  {
    type: 'time',
    value: 5000, // 5 seconds in milliseconds
    surveyId: 'survey-home-001',
  },
  {
    type: 'scroll',
    value: 50, // 50% scroll
    surveyId: 'survey-engagement-001',
  },
  {
    type: 'click',
    value: 'feedback-button',
    surveyId: 'survey-feedback-001',
  },
]);
This method is typically not needed. Triggers are automatically derived from popup definitions when using autoLaunch().
Source: deepdots-popups.ts:142-148

​
setRenderer()

Sets a custom renderer for popups. Allows platform-specific or custom UI implementations. 
setRenderer(renderer: PopupRenderer): void
​
renderer
PopupRenderer
required
Custom renderer implementation
interface PopupRenderer {
  init?(): void;
  show(
    surveyId: string,
    productId: string,
    actions?: PopupActions,
    emitEvent: (type: DeepdotsEventType, id: string, payload?: Record<string, unknown>) => void,
    hidePopup: () => void,
    env: 'production' | 'development'
  ): void;
  hide(): void;
}
Example: 
const customRenderer = {
  init() {
    console.log('Custom renderer initialized');
  },
  show(surveyId, productId, actions, emitEvent, hidePopup, env) {
    // Custom rendering logic
    const modal = document.createElement('div');
    modal.innerHTML = `<h1>Survey ${surveyId}</h1>`;
    document.body.appendChild(modal);
    
    emitEvent('popup_shown', surveyId, { popupId: 'custom' });
  },
  hide() {
    // Custom hide logic
  },
};

popups.setRenderer(customRenderer);
If init() is implemented, it will be called automatically if the SDK is already initialized when setRenderer() is called.
Source: deepdots-popups.ts:622-627

​
State Management Methods

​
markSurveyAnswered()

Manually marks a survey as answered. Prevents popups with condition: [{ answered: false }] from showing for this survey. 
markSurveyAnswered(surveyId: string): void
​
surveyId
string
required
The survey ID to mark as answered
Example: 
// Mark survey as answered externally
popups.markSurveyAnswered('survey-home-001');

// Now popups with this condition won't show for this survey
const definition = {
  surveyId: 'survey-home-001',
  triggers: {
    type: 'time_on_page',
    value: 5,
    condition: [{ answered: false, cooldownDays: 0 }]
  },
  // ... other fields
};
This method is called automatically when a survey_completed event is emitted. You typically only need to call it manually if tracking survey completion through an external system.
Source: deepdots-popups.ts:303-305

Configuration

Learn about all configuration options and type definitions

DeepdotsPopups Class

Return to the main class overview

Build docs developers (and LLMs) love

Get started for freeTalk to us