Popup Definition Types

These types are used internally by the SDK. While they are not directly exported from the package, they are documented here for reference when configuring popups in client mode or understanding the SDK’s behavior.

PopupDefinition

Complete definition of a popup including trigger, actions, style, and targeting.

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

Parameters

string

required

Unique identifier for the popup

title

string

required

Title text displayed in the popup

message

string

required

Message content (HTML string - should be sanitized before use)

triggers

PopupTrigger

required

Trigger configuration that determines when the popup appears

actions

PopupActions

Available actions (accept, decline, complete, start, back)

surveyId

string

required

Survey ID to associate with this popup

productId

string

required

Product ID associated with the survey

style

PopupStyle

Visual styling configuration for the popup

segments

PopupSegments

Targeting configuration to control when/where popup appears

PopupTrigger

Trigger associated with the popup definition.

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

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

Show PopupTrigger Properties

type

PopupTriggerType

required

Type of trigger: 'time_on_page', 'scroll', 'exit', 'click', or 'event'

value

number | string

required

Value for the trigger:

time_on_page: seconds on page
scroll: scroll percentage (0-100)
exit: route exit delay in seconds
click: element id to click
event: custom event name

condition

PopupTriggerCondition[]

List of additional conditions for triggering the popup

PopupTriggerCondition

Additional condition for popup activation.

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

Show PopupTriggerCondition Properties

answered

boolean

required

Whether the user has already answered the survey

cooldownDays

number

required

Number of days to wait before showing the popup again

PopupActions

Set of available actions in the popup.

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

Show PopupActions Properties

PopupActionAccept

Action to accept and open the survey

decline

PopupActionDecline

Action to decline the popup

complete

PopupActionComplete

Action to accept and auto-complete the survey

start

PopupActionStart

Action to start the survey

back

PopupActionDecline

Action to go back (uses same interface as decline)

Action Interfaces

Show PopupActionAccept

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

label

string

required

Button label text

surveyId

string

required

ID of the survey to launch

Show PopupActionDecline

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

label

string

required

Button label text

cooldownDays

number

Optional: do not show the popup for X days after declining

Show PopupActionStart

export interface PopupActionStart {
    label: string;
}

label

string

required

Button label text

Show PopupActionComplete

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

label

string

required

Button label text

surveyId

string

required

ID of the survey to launch

autoCompleteParams

Record<string, unknown>

required

Parameters for auto-completing the survey (requires survey to support auto-complete via parameters)

cooldownDays

number

Number of days to wait before showing again

PopupStyle

Configurable styles for the popup appearance.

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

Show PopupStyle Properties

theme

'light' | 'dark'

required

Visual theme for the popup

position

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

required

Screen position where the popup will appear

imageUrl

string | null

required

Optional image URL to display in the popup

PopupSegments

Targeting configuration to control when and where popups appear.

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

Show PopupSegments Properties

lang

string[]

Array of allowed language codes

path

string[]

Array of app routes where the popup should be shown

[key: string]

unknown

Extension point for future targeting options

Example Usage

const popup: PopupDefinition = {
  id: 'welcome-popup',
  title: 'Welcome to our app!',
  message: 'We'd love to hear your feedback',
  surveyId: 'survey-123',
  productId: 'product-456',
  triggers: {
    type: 'time_on_page',
    value: 10
  }
};

Core API

Type Definitions

Advanced