Configuration

Initialization Interfaces

DeepdotsInitParams

Configuration object passed to the init() method to initialize the SDK.

interface DeepdotsInitParams {
  apiKey?: string;
  nodeEnv?: 'development' | 'production';
  mode?: 'server' | 'client';
  debug?: boolean;
  popups?: PopupDefinition[];
  userId?: string;
}

apiKey

string

API key for authentication. Required when using mode: 'server' to fetch popup definitions from the Deepdots API.

nodeEnv

'development' | 'production'

default:"'production'"

Environment setting that determines the API endpoint:

'production': Uses https://api.deepdots.com
'development': Uses https://api-dev.deepdots.com

mode

'server' | 'client'

default:"'client'"

Execution mode:

'server': Fetches popup definitions from the Deepdots API at runtime
'client': Uses popup definitions provided in the popups parameter

debug

boolean

default:"false"

When true, enables debug logging to the console with [DeepdotsPopups] prefix.

popups

PopupDefinition[]

Array of popup definitions. Required when using mode: 'client'. Ignored in mode: 'server'.

userId

string

Optional user identifier. Used for:

Sending with popup events to the API
User-specific popup targeting (when supported)

Example:

popups.init({
  mode: 'server',
  apiKey: 'YOUR_PUBLIC_API_KEY',
  userId: 'customer-123',
  nodeEnv: 'production',
  debug: false,
});

Source: types/index.ts:5-19

DeepdotsConfig

Internal configuration interface used after initialization. Similar to DeepdotsInitParams but excludes nodeEnv (which is resolved internally).

interface DeepdotsConfig {
  apiKey?: string;
  mode?: 'server' | 'client';
  debug?: boolean;
  popups?: PopupDefinition[];
  userId?: string;
}

This interface is used internally by the SDK. You don’t need to use it directly - use DeepdotsInitParams when calling init().

Source: types/index.ts:20-31

PopupDefinition

Complete definition of a popup, including content, triggers, actions, and targeting.

interface PopupDefinition {
  id: string;
  title: string;
  message: string;
  triggers: PopupTrigger;
  actions?: PopupActions;
  surveyId: string;
  productId: string;
  style?: PopupStyle;
  segments?: PopupSegments;
}

string

required

Unique identifier for this popup definition. Used with showByPopupId() and for internal tracking.

title

string

required

Title text for the popup. Part of the definition contract but may not be rendered by all renderers.

message

string

required

Message content for the popup. Supports HTML. Should be sanitized before use.

triggers

PopupTrigger

required

Trigger configuration that determines when the popup should be shown. See PopupTrigger.

actions

PopupActions

Available actions for the popup (accept, decline, complete, etc.). See PopupActions.

surveyId

string

required

ID of the survey to display when the popup is shown.

productId

string

required

ID of the product associated with this popup.

style

PopupStyle

Visual styling options for the popup. See PopupStyle.

segments

PopupSegments

Targeting and segmentation rules. See PopupSegments.

Example:

const definition: PopupDefinition = {
  id: 'popup-home-5s',
  title: 'Help us improve',
  message: '<p>Thanks for visiting our homepage.</p>',
  triggers: {
    type: 'time_on_page',
    value: 5,
    condition: [{ answered: false, cooldownDays: 7 }],
  },
  actions: {
    accept: {
      label: 'Take Survey',
      surveyId: 'survey-home-001',
    },
    decline: {
      label: 'Maybe Later',
      cooldownDays: 3,
    },
  },
  surveyId: 'survey-home-001',
  productId: 'product-main',
  style: {
    theme: 'light',
    position: 'bottom-right',
    imageUrl: null,
  },
  segments: {
    path: ['/', '/home', '/pricing'],
  },
};

Source: types/index.ts:148-158

PopupTrigger

Defines when and how a popup should be triggered.

interface PopupTrigger {
  type: PopupTriggerType;
  value: number | string;
  condition?: PopupTriggerCondition[];
}

type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';

type

PopupTriggerType

required

The type of trigger:

'time_on_page': Show after user has been on page for N seconds
'scroll': Show after user scrolls to N% of page
'exit': Show after user leaves the page (with delay)
'click': Show after user clicks element with specific ID
'event': Show when triggerEvent(name) is called with matching name

value

number | string

required

Value for the trigger, interpretation depends on type:

time_on_page: Number of seconds (e.g., 5 for 5 seconds)
scroll: Percentage as number (e.g., 50 for 50%)
exit: Number of seconds to delay after exit (e.g., 2)
click: DOM element ID as string (e.g., 'feedback-button')
event: Event name as string (e.g., 'search')

condition

PopupTriggerCondition[]

Array of conditions that must all be met for the popup to show. See PopupTriggerCondition.

Examples:

{
  type: 'time_on_page',
  value: 5, // Show after 5 seconds
  condition: [{ answered: false, cooldownDays: 7 }]
}

Source: types/index.ts:83-96

PopupTriggerCondition

Defines additional conditions that must be met before a popup can be shown.

interface PopupTriggerCondition {
  answered: boolean;
  cooldownDays: number;
}

answered

boolean

required

If false, the popup will only show if the survey has NOT been answered. If true, shows regardless of answer status.

cooldownDays

number

required

Number of days that must pass after the popup was last shown before it can be shown again. Set to 0 for no cooldown.

Examples:

// Only show to users who haven't answered, wait 7 days between shows
{ answered: false, cooldownDays: 7 }

// Show regardless of answer status, no cooldown
{ answered: true, cooldownDays: 0 }

// Only show to users who haven't answered, wait 30 days
{ answered: false, cooldownDays: 30 }

Multiple conditions in the condition array are evaluated with AND logic - all must be true for the popup to show.

Source: types/index.ts:86-89

PopupActions

Defines the available actions (buttons) for a popup.

interface PopupActions {
  accept?: PopupActionAccept;
  decline?: PopupActionDecline;
  complete?: PopupActionComplete;
  start?: PopupActionStart;
  back?: PopupActionDecline;
}

PopupActionAccept

Primary action to open the survey.

interface PopupActionAccept {
  label: string;
  surveyId: string;
}

decline

PopupActionDecline

Action to dismiss the popup, optionally with cooldown.

interface PopupActionDecline {
  label: string;
  cooldownDays?: number;
}

The current browser renderer does not render a dedicated decline button. This is accepted in the definition but not actively used.

complete

PopupActionComplete

Action to auto-complete the survey with predefined parameters.

interface PopupActionComplete {
  label: string;
  surveyId: string;
  autoCompleteParams: Record<string, unknown>;
  cooldownDays?: number;
}

start

PopupActionStart

Action to start the survey flow.

interface PopupActionStart {
  label: string;
}

back

PopupActionDecline

Back action, same structure as decline.

Example:

const actions: PopupActions = {
  accept: {
    label: 'Take Survey',
    surveyId: 'survey-001',
  },
  decline: {
    label: 'Maybe Later',
    cooldownDays: 7,
  },
  start: {
    label: 'Get Started',
  },
};

Source: types/index.ts:98-131

PopupStyle

Visual styling configuration for the popup.

interface PopupStyle {
  theme: 'light' | 'dark';
  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'center';
  imageUrl: string | null;
}

theme

'light' | 'dark'

required

Color theme for the popup.

position

string

required

Screen position where the popup should appear:

'bottom-right'
'bottom-left'
'top-right'
'top-left'
'center'

imageUrl

string | null

required

Optional image URL to display in the popup. Set to null for no image.

Example:

const style: PopupStyle = {
  theme: 'light',
  position: 'bottom-right',
  imageUrl: 'https://example.com/popup-image.png',
};

The current browser renderer focuses on the embedded form and may not render all style fields. These are part of the definition contract for future renderer implementations.

Source: types/index.ts:134-138

PopupSegments

Targeting and segmentation rules for showing popups.

interface PopupSegments {
  lang?: string[];
  path?: string[];
  [key: string]: unknown;
}

lang

string[]

Array of language codes. Currently defined but not actively evaluated by the SDK runtime.

path

string[]

Array of URL paths where the popup should be shown. Supports:

Full URLs: 'https://example.com/home'
Path fragments: '/pricing', '/home'
Hash routes: '/#/dashboard'

The popup will only show if the current URL matches at least one path in the array.

[key: string]

unknown

Additional custom segmentation fields for future extensions.

Examples:

{
  path: ['/', '/home', '/pricing']
}

segments.path is currently the only segment actively evaluated by the SDK runtime. Language and custom segments are accepted but not enforced.

Source: types/index.ts:141-145

Trigger Interfaces

TriggerConfig

Internal trigger configuration used by the SDK. Automatically derived from PopupDefinition.triggers but can also be set manually via configureTriggers().

interface TriggerConfig {
  type: 'time' | 'scroll' | 'exit' | 'click' | 'event';
  value?: number | string;
  surveyId: string;
  popupId?: string;
}

type

'time' | 'scroll' | 'exit' | 'click' | 'event'

required

Trigger type. Note the difference from PopupTriggerType:

'time' instead of 'time_on_page'
Values are in milliseconds instead of seconds for time triggers

value

number | string

Trigger value:

time: milliseconds (e.g., 5000 for 5 seconds)
scroll: percentage (e.g., 50)
exit: seconds (e.g., 2)
click: element ID (e.g., 'button-id')
event: event name (e.g., 'checkout')

surveyId

string

required

Survey ID to show when the trigger fires.

Optional popup definition ID for disambiguation when multiple popups use the same surveyId.

Example:

const triggers: TriggerConfig[] = [
  {
    type: 'time',
    value: 5000, // 5 seconds in milliseconds
    surveyId: 'survey-001',
    popupId: 'popup-home',
  },
  {
    type: 'event',
    value: 'search',
    surveyId: 'survey-002',
  },
];

popups.configureTriggers(triggers);

Source: types/index.ts:36-45

Event Interfaces

DeepdotsEvent

Event object emitted by the SDK for popup lifecycle events.

interface DeepdotsEvent {
  type: DeepdotsEventType;
  surveyId: string;
  timestamp: number;
  data?: Record<string, unknown>;
}

type DeepdotsEventType = 'popup_shown' | 'popup_clicked' | 'survey_completed';

type

DeepdotsEventType

required

The type of event:

'popup_shown': Popup was displayed to the user
'popup_clicked': User interacted with the popup
'survey_completed': User completed the survey

surveyId

string

required

The survey ID associated with this event.

timestamp

number

required

Unix timestamp (milliseconds) when the event occurred.

data

Record<string, unknown>

Additional event data. Common fields:

popupId: The popup definition ID
userId: User identifier (if configured)
action: Action type for popup_clicked events (e.g., 'loaded', 'start_survey', 'close_icon')

Example:

popups.on('popup_shown', (event: DeepdotsEvent) => {
  console.log('Event type:', event.type); // 'popup_shown'
  console.log('Survey ID:', event.surveyId);
  console.log('Time:', new Date(event.timestamp));
  console.log('Popup ID:', event.data?.popupId);
});

Source: types/index.ts:62-75

EventListener

Callback function type for event listeners.

type EventListener = (event: DeepdotsEvent) => void;

See on() method documentation for usage examples. Source: types/index.ts:80

Legacy Interfaces

ShowOptions

Legacy interface for showing popups. Still supported but PopupDefinition format is preferred.

interface ShowOptions {
  surveyId: string;
  productId: string;
  data?: Record<string, unknown>;
}

surveyId

string

required

Survey ID to display.

productId

string

required

Product ID associated with the survey.

data

Record<string, unknown>

Additional data to pass with the survey.

Example:

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

Source: types/index.ts:50-57

Methods

Explore all available methods and their usage

DeepdotsPopups Class

Return to the main class overview

Core API

Type Definitions

Advanced

Initialization Interfaces

DeepdotsInitParams

DeepdotsConfig

PopupDefinition

PopupTrigger

PopupTriggerCondition

PopupActions

PopupStyle

PopupSegments

Trigger Interfaces

TriggerConfig

Event Interfaces

DeepdotsEvent

EventListener

Legacy Interfaces

ShowOptions

Methods

DeepdotsPopups Class

Build docs developers (and LLMs) love

Core API

Type Definitions

Advanced

​Initialization Interfaces

​DeepdotsInitParams

​DeepdotsConfig

​Popup Definition Interfaces

​PopupDefinition

​PopupTrigger

​PopupTriggerCondition

​PopupActions

​PopupStyle

​PopupSegments

​Trigger Interfaces

​TriggerConfig

​Event Interfaces

​DeepdotsEvent

​EventListener

​Legacy Interfaces

​ShowOptions

​Related Resources

Methods

DeepdotsPopups Class

Build docs developers (and LLMs) love

Initialization Interfaces

DeepdotsInitParams

DeepdotsConfig

Popup Definition Interfaces

PopupDefinition

PopupTrigger

PopupTriggerCondition

PopupActions

PopupStyle

PopupSegments

Trigger Interfaces

TriggerConfig

Event Interfaces

DeepdotsEvent

EventListener

Legacy Interfaces

ShowOptions

Related Resources