@engageapp/inapp-web

Full-screen in-app takeover SDK for web apps. When you run an EngageApp campaign through an in-app channel, this SDK fetches the pending takeover when your app foregrounds and renders it natively (no iframe/webview).

Install

npm install @engageapp/inapp-web

Usage

import { EngageInApp } from '@engageapp/inapp-web';

// 1. Initialise with your PUBLISHABLE key (safe to ship in client code).
EngageInApp.init({
  publishableKey: 'pk_xxx',
  apiBaseUrl: 'https://api.engageapp.xyz'
});

// 2. Identify the signed-in user by your own external id.
await EngageInApp.identify('user-123', { firstName: 'Ada', email: '[email protected]' });

// 3. Handle button taps (deep links / URLs) in your app.
EngageInApp.setHandlers({
  onButtonTap: (action) => {
    if (action.type === 'deeplink') router.go(action.value!);
    if (action.type === 'url') window.location.assign(action.value!);
  }
});

// 4. Call on every app foreground / route into the app. Fetches + renders
//    the next pending takeover, if any.
await EngageInApp.onAppForeground();

Delivery is pull-based: a takeover is shown the next time the app foregrounds after the campaign sends it. Impressions, clicks and dismissals are reported back automatically and surface in EngageApp analytics.

Identity verification (optional, anti-spoofing)

If you enable in-app identity verification for your workspace (Settings → In-app identity verification), pass the HMAC your backend computes so the SDK can prove the user's identity:

// On your server: hmacSha256Hex(secret, externalId)
await EngageInApp.identify('user-123', { identityHash: '<hex digest from your backend>' });

The SDK sends it as X-Identity-Hash; requests with a missing/invalid hash are rejected when verification is required.

Development

npm install
npm test          # vitest unit tests (happy-dom)
npm run test:e2e  # Playwright browser e2e (mocked API)
npm run build     # tsc -> dist/