Skip to main content

​
Package Installation

Install the SDK using your preferred package manager: 
npm install @magicfeedback/popup-sdk

​
System Requirements

Before installing, ensure your environment meets these requirements:

​
Runtime Requirements

  • Node.js: Version 16.x or higher (for development)
  • Browser Support: Modern browsers with ES2015+ support
  • TypeScript: Version 5.0 or higher (if using TypeScript)

​
Required Browser APIs

The SDK requires the following browser APIs:
  • Fetch API: For loading popup definitions from the server
  • SessionStorage: For managing exit popup queue
  • DOM APIs: For rendering and managing popup UI
  • History API: For detecting route changes and exit triggers
The SDK automatically falls back to a no-op renderer in non-browser environments (like SSR), so it’s safe to import in universal JavaScript applications.

​
TypeScript Configuration

The SDK is written in TypeScript and includes type definitions out of the box. No additional type packages are required.

​
tsconfig.json Setup

Ensure your tsconfig.json includes these settings for optimal compatibility:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2015",
    "module": "ESNext",
    "lib": ["ES2015", "DOM"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true
  }
}

​
Type Imports

The SDK exports all necessary types for full TypeScript support: 
import { 
  DeepdotsPopups,
  DeepdotsConfig,
  DeepdotsEvent,
  DeepdotsEventType,
  TriggerConfig,
  ShowOptions,
  EventListener
} from '@magicfeedback/popup-sdk';

​
Framework-Specific Installation

​
React / Next.js

For React applications, you can initialize the SDK in a useEffect hook:
React Example
import { useEffect } from 'react';
import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

function App() {
  useEffect(() => {
    // Only initialize in browser environment
    if (typeof window !== 'undefined') {
      const popups = new DeepdotsPopups();
      popups.init({
        mode: 'server',
        apiKey: process.env.NEXT_PUBLIC_MAGICFEEDBACK_API_KEY,
        nodeEnv: 'production',
        debug: false
      });
      popups.autoLaunch();
    }
  }, []);

  return <div>Your App</div>;
}
For Next.js SSR, always check for typeof window !== 'undefined' before initializing the SDK to prevent server-side errors.

​
Vue.js

For Vue applications, initialize in the mounted lifecycle hook:
Vue Example
import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

export default {
  data() {
    return {
      popups: null
    };
  },
  mounted() {
    this.popups = new DeepdotsPopups();
    this.popups.init({
      mode: 'server',
      apiKey: import.meta.env.VITE_MAGICFEEDBACK_API_KEY,
      nodeEnv: 'production'
    });
    this.popups.autoLaunch();
  }
};

​
Vanilla JavaScript

For plain JavaScript projects: 
import { DeepdotsPopups } from '@magicfeedback/popup-sdk';

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

​
Environment Variables

For security and flexibility, store your API key in environment variables: 
NEXT_PUBLIC_MAGICFEEDBACK_API_KEY=your_public_api_key_here
The API key is a public key that’s safe to expose in client-side code. It’s used to fetch popup definitions from the Deepdots API.

​
API Endpoints

The SDK connects to different API endpoints based on the nodeEnv configuration:
EnvironmentAPI Base URL
productionhttps://api.deepdots.com
developmenthttps://api-dev.deepdots.com
popups.init({
  mode: 'server',
  apiKey: 'YOUR_API_KEY',
  nodeEnv: 'production' // or 'development'
});

​
Verification

To verify the installation is successful, add debug mode and check the console: 
const popups = new DeepdotsPopups();
popups.init({
  mode: 'server',
  apiKey: 'YOUR_API_KEY',
  nodeEnv: 'production',
  debug: true // Enable debug logging
});
popups.autoLaunch();
You should see initialization logs in the browser console:
Console Output
[DeepdotsPopups] SDK initialized {mode: 'server', debug: true, ...}
[DeepdotsPopups] Popups loaded from server (fake) [...]
[DeepdotsPopups] Auto-launch enabled

​
Troubleshooting

Ensure the package is properly installed by running npm install @magicfeedback/popup-sdk again. Check that your node_modules folder contains the package.
Make sure your tsconfig.json includes "esModuleInterop": true and that you’re using TypeScript 5.0 or higher.
Always wrap SDK initialization in a typeof window !== 'undefined' check or use dynamic imports with { ssr: false }.
Verify your API key is correct and that you’re using the appropriate nodeEnv setting. Check browser network tab for failed requests.

​
Next Steps

Quickstart Guide

Learn how to create your first popup with a complete working example

Build docs developers (and LLMs) love

Get started for freeTalk to us