Skip to main content

​
Overview

This guide shows you how to integrate the MagicFeedback Popup SDK into a standard website. We’ll use the real example from examples/demo-sdk.js and examples/index.html to demonstrate a production-ready setup.

​
What You’ll Build

A website integration that:
  • Loads popup definitions from the Deepdots API
  • Automatically triggers popups based on user behavior
  • Logs all popup events for tracking and analytics
  • Works with time-based, scroll, click, and exit triggers

​
Installation

1

Install the SDK

Install via npm or use a CDN:
npm install @magicfeedback/popup-sdk
2

Import and Initialize

Create your SDK initialization file:
demo-sdk.js
import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

function formatLogLine(event) {
  const time = new Date(event.timestamp).toLocaleTimeString();
  const action = event?.data?.action ? ` (${event.data.action})` : '';
  return `[${time}] ${event.type} - survey:${event.surveyId}${action}`;
}

export function initDemoSdk({ modeLabelEl, eventLogEl } = {}) {
  const mode = 'server';

  const sdk = new DeepdotsPopups();
  sdk.init({
    mode,
    nodeEnv: 'production',
    debug: true,
    apiKey: 'YOUR_PUBLIC_API_KEY'
  });

  if (modeLabelEl) {
    modeLabelEl.textContent = mode;
  }

  if (eventLogEl) {
    const log = (ev) => {
      const line = document.createElement('div');
      line.className = 'event';
      line.textContent = formatLogLine(ev);
      eventLogEl.appendChild(line);
      eventLogEl.scrollTop = eventLogEl.scrollHeight;
    };
    sdk.on('popup_shown', log);
    sdk.on('popup_clicked', log);
    sdk.on('survey_completed', log);
  }

  return { sdk };
}
3

Use in Your HTML

Import and launch the SDK in your page:
index.html
<script type="module">
  import { initDemoSdk } from './demo-sdk.js';

  const modePill = document.getElementById('mode-pill');
  const eventLog = document.getElementById('event-log');
  const { sdk } = initDemoSdk({ 
    modeLabelEl: modePill, 
    eventLogEl: eventLog 
  });

  // Enable AutoLaunch to start showing popups
  sdk.autoLaunch();
</script>

​
Configuration Options

In server mode, popup definitions are fetched from the Deepdots API: 
sdk.init({
  mode: 'server',
  nodeEnv: 'production',  // or 'development'
  apiKey: 'YOUR_PUBLIC_API_KEY',
  userId: 'customer-123',  // optional, for user-specific popups
  debug: false
});
ParameterTypeDescription
mode'server' | 'client'Use server for production
nodeEnv'production' | 'development'API environment
apiKeystringYour public API key
userIdstringOptional user identifier
debugbooleanEnable console logging
Environment URLs:
  • production: https://api.deepdots.com
  • development: https://api-dev.deepdots.com

​
Event Tracking

The SDK emits three main events: 
sdk.on('popup_shown', (event) => {
  console.log('Popup displayed', event);
  // Track in your analytics
});

sdk.on('popup_clicked', (event) => {
  console.log('User interacted', event);
  // event.data.action contains: 'start_survey', 'complete', 'close_icon', etc.
});

sdk.on('survey_completed', (event) => {
  console.log('Survey finished', event);
  // User completed the survey
});

​
Event Payload

All events follow this structure: 
interface DeepdotsEvent {
  type: 'popup_shown' | 'popup_clicked' | 'survey_completed';
  surveyId: string;
  timestamp: number;
  data?: {
    popupId?: string;
    action?: string;
    userId?: string;
    [key: string]: unknown;
  };
}

​
AutoLaunch Behavior

Calling sdk.autoLaunch() activates all configured triggers:
  • Time on page: Shows popup after N seconds
  • Scroll depth: Triggers when user scrolls to a percentage
  • Click: Activates when specific DOM element is clicked
  • Exit intent: Queues popup when user leaves a route
In server mode, autoLaunch() waits for remote popup definitions to load before starting triggers.

​
Complete Example

Here’s a minimal HTML page with the SDK: 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
  <script type="importmap">
    {
      "imports": {
        "@magicfeedback/popup-sdk": "https://cdn.jsdelivr.net/npm/@magicfeedback/[email protected]/dist/index.mjs"
      }
    }
  </script>
</head>
<body>
  <h1>Welcome to my site</h1>
  <p>Popups will show based on your configured triggers.</p>

  <script type="module">
    import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

    const sdk = new DeepdotsPopups();
    sdk.init({
      mode: 'server',
      nodeEnv: 'production',
      apiKey: 'YOUR_PUBLIC_API_KEY',
      debug: false
    });

    sdk.on('survey_completed', (event) => {
      console.log('Thank you for your feedback!');
    });

    sdk.autoLaunch();
  </script>
</body>
</html>

​
Next Steps

Business Events

Trigger popups from your application logic

Route Navigation

Show exit popups after navigation

Build docs developers (and LLMs) love

Get started for freeTalk to us