Skip to main content

Initialization

Initialization Objectives

  1. Initialize runtime exactly once per app shell.
  2. Keep one active instance per client context.
  3. Avoid duplicate renders/events in SPA/mobile navigation.
  4. Ensure consent/tracking methods are reachable.

Mode A: CDN Auto-Initialization

<script
  src="https://widget.selwise.com/client.js"
  data-site-key="YOUR_SITE_KEY"
  data-api-url="https://api.selwise.com/api/v1"
></script>

Behavior:

  • runtime auto-initializes from script tag
  • active instance is bound to window.Selwise

Mode B: npm Controlled Initialization

import Selwise from '@selwise/widget';

const widget = new Selwise();
await widget.init({
  siteKey: 'YOUR_SITE_KEY',
  apiUrl: 'https://api.selwise.com/api/v1',
  exposeGlobal: true,
});

Mode C: React Native Headless Initialization

import Selwise from '@selwise/react-native';

const sdk = new Selwise();
await sdk.init({
  siteKey: 'YOUR_SITE_KEY',
  apiUrl: 'https://api.selwise.com/api/v1',
  apiKey: 'YOUR_MOBILE_API_KEY',
  sdkVersion: '0.1.0',
});

sdk.setScreenContext({ name: 'Home', path: '/home' });

Behavior:

  • no DOM/widget rendering
  • tracking/identity/search/recommendation API access is headless
  • auth is handled via scoped API key headers

Single-Instance Pattern

import Selwise from '@selwise/react-native';

let selwise: Selwise | null = null;

export async function startSelwiseMobile(siteKey: string, apiKey: string, apiUrl: string) {
  if (selwise) return selwise;

  selwise = new Selwise();
  await selwise.init({ siteKey, apiUrl, apiKey });
  return selwise;
}

export function stopSelwiseMobile() {
  selwise?.destroy();
  selwise = null;
}

Runtime Fetch Flow

Primary:

  • GET /api/v1/public/sites/:siteKey/config

Tracking/identity:

  • POST /api/v1/public/sites/:siteKey/events/batch
  • POST /api/v1/public/sites/:siteKey/users/identify
  • POST /api/v1/public/sites/:siteKey/users/traits
  • POST /api/v1/public/sites/:siteKey/orders

Anti-Patterns

  • initializing runtime per screen mount
  • using an API key without proper mobile scopes
  • creating multiple active SDK instances

Next