Quickstart

Overview

This guide will walk you through setting up the MagicFeedback Popup SDK from scratch and displaying your first survey popup. You’ll learn how to use both server and client modes, configure triggers, and listen for events.

Prerequisites

Before starting, make sure you have:

Installed the SDK (see Installation)
A MagicFeedback API key (for server mode)
A survey ID and product ID from your MagicFeedback dashboard

Server Mode Setup (Recommended)

Server mode is the recommended approach for production applications. Popup definitions are managed remotely and fetched at runtime.

Import and Initialize

Create a new instance of DeepdotsPopups and initialize it with your 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', // Optional: for user-specific targeting
  debug: false // Set to true during development
});

mode: 'server' fetches popup definitions from the Deepdots API
nodeEnv: 'production' uses https://api.deepdots.com
nodeEnv: 'development' uses https://api-dev.deepdots.com
userId is optional but recommended for user-specific popup targeting

Set Up Event Listeners

Listen for popup lifecycle events to track user interactions:

// Track when a popup is shown
popups.on('popup_shown', (event) => {
  console.log('Popup shown:', event);
  // Send analytics event to your tracking system
  analytics.track('Survey Shown', {
    surveyId: event.surveyId,
    timestamp: event.timestamp
  });
});

// Track when a user interacts with the popup
popups.on('popup_clicked', (event) => {
  console.log('Popup clicked:', event);
  // event.data.action contains: 'loaded', 'start_survey', 'complete', 'close_icon', etc.
});

// Track when a survey is completed
popups.on('survey_completed', (event) => {
  console.log('Survey completed:', event);
  // Update user profile or trigger follow-up actions
});

Set up event listeners before calling autoLaunch() to ensure you don’t miss any events.

Enable Auto-Launch

Start the trigger system to automatically show popups based on their configured triggers:

popups.autoLaunch();

In server mode, autoLaunch() waits until popup definitions are loaded from the API before activating triggers. You can call it immediately after init().

Complete Server Mode Example

Complete Example

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

// Initialize the SDK
const popups = new DeepdotsPopups();

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

// Listen for events
popups.on('popup_shown', (event) => {
  console.log('Popup shown:', event);
});

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

// Start the triggers
popups.autoLaunch();

Client Mode Setup (Local Development)

Client mode is perfect for local demos, QA testing, and integration testing without API calls. You provide popup definitions inline.

Define Popup Configuration

Create popup definitions with triggers, actions, and targeting:

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, // Show after 5 seconds
      condition: [
        {
          answered: false, // Only show if not answered
          cooldownDays: 7  // Wait 7 days before showing again
        }
      ]
    },
    actions: {
      accept: {
        label: 'Open survey',
        surveyId: 'survey-home-001'
      }
    },
    surveyId: 'survey-home-001',
    productId: 'product-main',
    segments: {
      path: ['/', '/pricing', '/#/home'] // Show on these routes
    }
  }
];

The property name is triggers (not trigger)
time_on_page values are in seconds (not milliseconds)
segments.path can contain full URLs, path fragments like /pricing, or hash routes like /#/home

Initialize with Popup Definitions

Pass your popup definitions to the SDK:

const popups = new DeepdotsPopups();

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

popups.autoLaunch();

Complete Client Mode Example

Complete Example

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();

Advanced Examples

Use event-based triggers for custom business logic:

Event Trigger Example

// 1. Define a popup with an event trigger
const eventPopup = {
  id: 'popup-search-feedback',
  title: 'Found what you need?',
  message: '<p>Help us improve search results.</p>',
  triggers: {
    type: 'event',
    value: 'search', // Event name to listen for
    condition: [{ answered: false, cooldownDays: 30 }]
  },
  actions: {
    accept: {
      label: 'Give feedback',
      surveyId: 'survey-search-001'
    }
  },
  surveyId: 'survey-search-001',
  productId: 'product-main'
};

// 2. Initialize SDK with the event popup
popups.init({
  mode: 'client',
  popups: [eventPopup]
});

popups.autoLaunch();

// 3. Trigger the popup when user performs a search
function handleSearch(query) {
  // Your search logic...
  performSearch(query);
  
  // Trigger the feedback popup
  popups.triggerEvent('search');
}

Show a popup after users navigate away from a specific page:

Exit Trigger Example

const exitPopup = {
  id: 'popup-pricing-exit',
  title: 'Before you go...',
  message: '<p>What made you leave the pricing page?</p>',
  triggers: {
    type: 'exit',
    value: 3, // Show 3 seconds after leaving the route
    condition: [{ answered: false, cooldownDays: 14 }]
  },
  actions: {
    accept: {
      label: 'Share feedback',
      surveyId: 'survey-pricing-exit'
    }
  },
  surveyId: 'survey-pricing-exit',
  productId: 'product-main',
  segments: {
    path: ['/pricing'] // Exit from pricing page
  }
};

Exit popups are queued in sessionStorage when users leave a matching route and displayed after the configured delay on the destination route.

Show a popup when users scroll to a specific depth:

Scroll Trigger Example

const scrollPopup = {
  id: 'popup-article-scroll',
  title: 'Enjoying the article?',
  message: '<p>Get more content like this.</p>',
  triggers: {
    type: 'scroll',
    value: 75, // Show at 75% scroll depth
    condition: [{ answered: false, cooldownDays: 7 }]
  },
  actions: {
    accept: {
      label: 'Subscribe',
      surveyId: 'survey-newsletter'
    }
  },
  surveyId: 'survey-newsletter',
  productId: 'product-blog',
  segments: {
    path: ['/blog/*'] // Show on blog posts
  }
};

Show a popup immediately without waiting for automatic triggers:

Manual Trigger

// Show by survey ID and product ID
popups.show({
  surveyId: 'survey-home-001',
  productId: 'product-main'
});

// Or show by popup definition ID
popups.showByPopupId('popup-home-5s');

Mark Survey as Answered

Manually mark a survey as answered to prevent it from showing again:

popups.markSurveyAnswered('survey-home-001');

Event Listener Management

Remove event listeners when they’re no longer needed:

const onShown = (event) => {
  console.log('Popup shown:', event);
};

// Add listener
popups.on('popup_shown', onShown);

// Remove listener
popups.off('popup_shown', onShown);

Testing Your Implementation

Enable Debug Mode

Set debug: true in your initialization config to see detailed logs:

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

Check Browser Console

Look for initialization and event logs:

[DeepdotsPopups] SDK initialized
[DeepdotsPopups] Auto-launch enabled
[DeepdotsPopups] Event emitted {type: 'popup_shown', surveyId: '...'}

Verify Popup Display

For time triggers, wait the specified duration
For scroll triggers, scroll to the percentage
For event triggers, call triggerEvent() manually
Check that the popup appears with the correct survey

Next Steps

Now that you have your first popup working, explore more advanced features:

API Reference

Explore all available methods, configuration options, and type definitions

Trigger Types

Learn about all trigger types and their configuration options

Popup Definitions

Understand the complete popup definition schema

Event System

Deep dive into the event system and payload structures

Get Started

Core Concepts

Guides

Examples

Overview

Prerequisites

Server Mode Setup (Recommended)

Complete Server Mode Example

Client Mode Setup (Local Development)

Complete Client Mode Example

Advanced Examples

Mark Survey as Answered

Event Listener Management

Testing Your Implementation

Next Steps

API Reference

Trigger Types

Popup Definitions

Event System

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Examples

​Overview

​Prerequisites

​Server Mode Setup (Recommended)

​Complete Server Mode Example

​Client Mode Setup (Local Development)

​Complete Client Mode Example

​Advanced Examples

​Trigger Popup on Custom Business Event

​Route Exit Popup

​Scroll-Based Popup

​Manual Popup Trigger

​Mark Survey as Answered

​Event Listener Management

​Testing Your Implementation

​Next Steps

API Reference

Trigger Types

Popup Definitions

Event System

Build docs developers (and LLMs) love

Overview

Prerequisites

Server Mode Setup (Recommended)

Complete Server Mode Example

Client Mode Setup (Local Development)

Complete Client Mode Example

Advanced Examples

Trigger Popup on Custom Business Event

Route Exit Popup

Scroll-Based Popup

Manual Popup Trigger

Mark Survey as Answered

Event Listener Management

Testing Your Implementation

Next Steps