Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MagicFeedback/deepdots-popup-sdk/llms.txt

Use this file to discover all available pages before exploring further.

Server mode is the recommended setup for production integrations. Popup definitions are managed remotely through the Deepdots API, allowing you to update surveys and targeting rules without deploying code changes.

​
When to Use Server Mode

Use server mode when:
  • You want to manage popup definitions through the Deepdots dashboard
  • You need to update surveys without redeploying your application
  • You’re building a production integration
  • You want centralized control over popup targeting and content
For local demos, QA environments, or integration testing without API calls, consider using client mode instead.

​
Installation

1

Install the SDK

Install the package via npm:
npm install @magicfeedback/popup-sdk
2

Import and initialize

Import the SDK and create a new instance:
import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

const popups = new DeepdotsPopups();
3

Configure with your API key

Initialize the SDK with your public API key:
popups.init({
  mode: 'server',
  nodeEnv: 'production',
  apiKey: 'YOUR_PUBLIC_API_KEY',
  userId: 'customer-123',
  debug: false,
});
4

Enable auto-launch

Start the SDK to begin evaluating triggers:
popups.autoLaunch();
In server mode, autoLaunch() waits until remote popups are loaded before starting triggers. You can call it immediately after init().

​
Configuration Options

​
Required Parameters

​
mode
string
required
Must be set to 'server' to fetch popup definitions from the Deepdots API.
​
apiKey
string
required
Your public API key from the Deepdots dashboard. This identifies your project and determines which popups to load.

​
Optional Parameters

​
nodeEnv
'production' | 'development'
default:"production"
Determines which API environment to use:
  • 'production' → https://api.deepdots.com
  • 'development' → https://api-dev.deepdots.com
​
userId
string
Optional user identifier. Recommended when popups are targeted per user. The SDK will filter popups based on this ID.
​
debug
boolean
default:"false"
Enables verbose logging to the console for debugging purposes.

​
Environment Setup

​
Production Environment

For production deployments, use the production API endpoint: 
popups.init({
  mode: 'server',
  nodeEnv: 'production',
  apiKey: 'YOUR_PRODUCTION_API_KEY',
  userId: user.id,
  debug: false,
});

​
Development Environment

For development and staging, use the development API endpoint: 
popups.init({
  mode: 'server',
  nodeEnv: 'development',
  apiKey: 'YOUR_DEV_API_KEY',
  userId: 'test-user-123',
  debug: true,
});
Make sure to use different API keys for production and development environments to keep your data separated.

​
Listening to Events

Subscribe to SDK events to track popup activity in your application: 
popups.on('popup_shown', (event) => {
  console.log('Popup shown:', event);
  // Track in your analytics
});

popups.on('popup_clicked', (event) => {
  console.log('Popup clicked:', event);
});

popups.on('survey_completed', (event) => {
  console.log('Survey completed:', event);
  // Update user state, trigger rewards, etc.
});

​
Complete Example

Here’s a complete server mode setup with event tracking: 
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();

​
How It Works

When you call init() with mode: 'server', the SDK:
  1. Fetches popup definitions from the Deepdots API using your API key
  2. Filters by userId (if provided) to only load relevant popups
  3. Configures triggers automatically based on the fetched definitions
  4. Waits for definitions to load before starting triggers when you call autoLaunch()
The API endpoint used depends on your nodeEnv setting: 
// Production endpoint
GET https://api.deepdots.com/sdk/{apiKey}/popups

// Development endpoint  
GET https://api-dev.deepdots.com/sdk/{apiKey}/popups

// With userId filter
GET https://api.deepdots.com/sdk/{apiKey}/popups?filter={"where":{"userId":"customer-123"}}

​
Next Steps

Event Triggers

Learn how to trigger popups from business events

Route Targeting

Target popups to specific pages and routes

Exit Popups

Show feedback popups when users navigate away

Client Mode

Use inline popup definitions for testing

Build docs developers (and LLMs) love

Get started for freeTalk to us