Widget Setup

This guide covers the technical integration of the Keep'em widget into your application.

1. Add the Script

Include the Keep'em widget script on any page where you want the video to appear. Configure it with data-* attributes directly on the script tag:

<script
  src="https://cdn.keepem.io/assets/embed.min.js"
  data-event="evt_YOUR_EVENT_ID"
  data-key="pk_live_YOUR_PUBLISHABLE_KEY"
></script>

data-event and data-key are required. You'll find both in your Keep'em dashboard under the event settings.

2. Identify the Viewer

Once the script is loaded, call Keepem.identify() with the current user's identity:

<script>
  Keepem.identify({
    viewerId: 'your-internal-user-id',
    email: 'user@example.com',  // optional
    name: 'Jane Doe'            // optional
  });
</script>

When identify is called, the widget checks the viewer's status with the Keep'em API. If they haven't completed the onboarding video, a modal appears with the video player. If they've already completed it, nothing happens.

3. Done

That's it. The widget handles everything else — registration, video playback, AI chat, progress tracking, and dismissal.

Script Attributes

All widget configuration is done via data-* attributes on the <script> tag.

Size Presets

All sizes are capped at 95vw / 95vh so the modal never overflows the viewport.

Full Example

<script
  src="https://cdn.keepem.io/assets/embed.min.js"
  data-event="evt_abc123"
  data-key="pk_live_xyz789"
  data-size="lg"
></script>

<script>
  // Listen for events before identifying
  Keepem.on('show', () => console.log('Widget shown'));
  Keepem.on('dismiss', () => console.log('Widget dismissed'));
  Keepem.on('complete', () => console.log('Onboarding complete'));

  // Identify the current user
  Keepem.identify({
    viewerId: currentUser.id,
    email: currentUser.email,
    name: currentUser.name
  });
</script>

JavaScript API

The script exposes window.Keepem with three methods:

Keepem.identify(viewer)

Identifies the current viewer and shows the video modal if they haven't completed onboarding. Returns a Promise<void>.

await Keepem.identify({
  viewerId: 'user_123',
  email: 'jane@example.com',
  name: 'Jane Doe'
});

If the viewer has already completed the video, the promise resolves and nothing is rendered.

Keepem.close()

Programmatically dismiss the modal. This fires the dismiss event and notifies the API.

Keepem.close();

Keepem.on(event, callback)

Subscribe to widget lifecycle events. Register listeners before calling identify to catch all events.

Keepem.on('show', () => {
  // e.g. pause background music, track analytics
});

Keepem.on('dismiss', () => {
  // e.g. resume app flow
});

Keepem.on('complete', () => {
  // e.g. show a success message, unlock a feature
});

Widget Behavior

• Backdrop click dismisses the modal
• Escape key dismisses the modal
• A loading spinner is shown while the player loads
• The modal uses the highest possible z-index (2147483647) so it appears above all other content

Backend Pre-Registration (Recommended)

For the most reliable integration, register viewers from your backend when they sign up, so they're already known to Keep'em before the widget loads:

curl -X POST https://api.keepem.com/v1/events/{eventId}/registrations \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "viewer@example.com",
    "name": "Jane Doe",
    "externalId": "your_internal_user_id"
  }'

This ensures the viewer is registered before the widget ever loads. The widget's identify call then simply looks up the existing registration.

Just-in-Time Registration

Alternatively, the widget handles registration automatically when identify is called. If no registration exists for the provided viewerId, one is created on the fly. This is simpler to implement but means registration happens client-side.