Skip to main content

​
What is MagicFeedback Popup SDK?

The MagicFeedback Popup SDK (@magicfeedback/popup-sdk) is a TypeScript SDK that enables you to seamlessly integrate survey popups into your web applications. It provides a flexible system for triggering popups based on user behavior, managing survey lifecycle events, and tracking user engagement.

​
Key Features

Multiple Trigger Types

Show popups based on time on page, scroll depth, click events, route exits, or custom business events

Server & Client Modes

Fetch popup definitions from the Deepdots API or use inline definitions for local testing

Route Targeting

Target specific pages or routes using segments.path with support for full URLs, path fragments, and hash routes

Lifecycle Events

Track popup activity with events like popup_shown, popup_clicked, and survey_completed

Smart Conditions

Control popup frequency with conditions like answered state and cooldown periods

SSR Compatible

Falls back to a no-op renderer outside the browser environment

​
Architecture Overview

The SDK is built with a modular architecture consisting of several key components:

​
Core Components

  • DeepdotsPopups: Main class that manages popup lifecycle, triggers, and events
  • Trigger System: Handles different trigger types (time, scroll, exit, click, event)
  • Renderer: Platform-specific rendering engine (browser or React Native)
  • Event Emitter: Publishes lifecycle events to the host application

​
Execution Modes

The SDK operates in two modes: Server Mode (Recommended for Production) 
// Popup definitions are fetched from the Deepdots API
// and managed remotely
popups.init({
  mode: 'server',
  apiKey: 'YOUR_PUBLIC_API_KEY',
  nodeEnv: 'production'
});
Client Mode (Development & Testing) 
// Popup definitions are provided inline
// for local demos and testing
popups.init({
  mode: 'client',
  popups: popupDefinitions
});

​
When to Use This SDK

The MagicFeedback Popup SDK is ideal for:
Gather user feedback at strategic moments during the user journey, such as after completing a task or spending time on a feature page.
Trigger surveys based on user behavior patterns to understand how users interact with your application.
Show targeted surveys after users interact with specific features or complete certain actions.
Capture feedback from users as they navigate away from key pages to understand drop-off reasons.
Trigger surveys based on custom business events like search behavior, purchase completion, or error occurrences.

​
Supported Trigger Types

The SDK supports five types of triggers:
Trigger TypeDescriptionExample Use Case
time_on_pageShows after N seconds on the pageWelcome surveys after 5 seconds
scrollShows after reaching a scroll percentageEngagement surveys at 75% scroll
clickShows after clicking an element with a specific DOM IDFeature feedback after button click
exitShows after leaving a route and waiting N seconds on the destinationExit intent surveys after navigation
eventShows when the host app calls triggerEvent(name)Custom business logic triggers
Exit triggers are queued in sessionStorage when users leave a matching route and rendered after the configured delay on the destination route.

​
Event System

The SDK emits three types of events that you can listen to: 
interface DeepdotsEvent {
  type: 'popup_shown' | 'popup_clicked' | 'survey_completed';
  surveyId: string;
  timestamp: number;
  data?: Record<string, unknown>;
}
  • popup_shown: Emitted when a popup is displayed to the user
  • popup_clicked: Emitted on user interactions (start survey, complete, close, etc.)
  • survey_completed: Emitted when a user completes a survey
The popup_clicked event includes a data.action field that can contain values like loaded, start_survey, manual_send, back, complete, or close_icon.

​
Browser Compatibility

The SDK is designed for modern browsers and requires:
  • ES2015+ JavaScript support
  • Fetch API
  • SessionStorage (for exit popup queue)
  • DOM manipulation APIs
For server-side rendering (SSR) frameworks like Next.js, the SDK automatically falls back to a no-op renderer when window or document are undefined.

​
Next Steps

Installation

Install the SDK and configure your development environment

Quickstart

Get started with your first popup in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us