Skip to main content
The MagicFeedback Popup SDK supports two execution modes: server mode and client mode. Each mode determines how popup definitions are loaded and managed. Server mode is the recommended setup for production integrations. Popup definitions are managed remotely via the Deepdots API and fetched at runtime.
In server mode, the SDK automatically waits for popup definitions to load from the API before activating triggers when you call autoLaunch().

​
Configuration

import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

const popups = new DeepdotsPopups();

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

popups.on('popup_shown', (event) => {
  console.log('Popup shown', event);
});

popups.on('survey_completed', (event) => {
  console.log('Survey completed', event);
});

popups.autoLaunch();

​
Environment Configuration

The nodeEnv parameter determines which API endpoint the SDK connects to:
  • nodeEnv: 'production' → https://api.deepdots.com
  • nodeEnv: 'development' → https://api-dev.deepdots.com

​
Key Features

  • Remote Management: Update popup definitions without redeploying your application
  • User Targeting: Pass userId to fetch user-specific popup configurations
  • Automatic Loading: SDK handles fetching and caching popup definitions
  • Real-time Updates: Changes to popup definitions take effect immediately
The userId parameter is optional but recommended when popups are targeted to specific users or user segments.

​
Client Mode

Client mode allows you to preload popup definitions directly in your code. This is useful for local development, QA testing, hardcoded fallback flows, and integration testing without API calls.

​
Configuration

import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

const popupDefinitions = [
  {
    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: 'Open survey',
        surveyId: 'survey-home-001',
      },
    },
    surveyId: 'survey-home-001',
    productId: 'product-main',
    segments: {
      path: ['/', '/pricing', '/#/home'],
    },
  },
];

const popups = new DeepdotsPopups();

popups.init({
  mode: 'client',
  debug: true,
  popups: popupDefinitions,
});

popups.autoLaunch();

​
Key Features

  • No API Dependency: Works without network requests or API keys
  • Predictable Behavior: Popup definitions are fully controlled in code
  • Fast Testing: Quickly validate trigger behavior and UI flows
  • Offline Support: Functions completely offline
In client mode, the property name is triggers (not trigger), and time_on_page values are defined in seconds.

​
When To Use Each Mode

Use server mode for:
  • Production integrations where popup definitions are managed by your marketing or product team
  • Dynamic targeting based on user segments or behavior
  • A/B testing and experimentation workflows
  • Frequent updates to popup content without redeploying
  • Multi-environment setups (development, staging, production)

​
Configuration Fields

Both modes support the following configuration options:
FieldTypeRequiredDescription
mode'server' | 'client'NoExecution mode (defaults to 'client')
apiKeystringServer mode onlyYour public API key for authentication
nodeEnv'development' | 'production'Server mode onlyDetermines API endpoint
userIdstringNoUser identifier for targeted popups
debugbooleanNoEnable debug logging to console
popupsPopupDefinition[]Client mode onlyArray of popup definitions

​
Behavior Differences

Server Mode:
  1. Call init() with API key
  2. SDK fetches popup definitions from API
  3. Call autoLaunch() (deferred until definitions load)
  4. Triggers activate automatically
Client Mode:
  1. Call init() with popup definitions
  2. Call autoLaunch()
  3. Triggers activate immediately
Server Mode: If the API request fails, the SDK logs an error and continues with an empty popup list. No popups will be shown.Client Mode: Errors only occur if popup definitions have invalid structure. Use debug: true to see validation warnings.

Build docs developers (and LLMs) love

Get started for freeTalk to us