Installation

Choose Integration Mode

Use one integration mode per client shell:

CDN mode (<script>): fastest rollout, minimal code changes, global API on window.Selwise.
npm mode (@selwise/widget): framework-controlled lifecycle, explicit init() and destroy().
React Native mode (@selwise/react-native): headless mobile SDK with API-key auth.

Prerequisites

Active siteKey from Selwise dashboard.
Correct API base URL ending with /api/v1.
Domain verification for web or mobile public API key (x-selwise-api-key) for RN.

Install

CDN
npm
React Native

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

Notes:

data-api-url is optional.
API URL resolution order: NEXT_PUBLIC_API_URL -> data-api-url -> https://api.selwise.com/api/v1.
CDN mode auto-initializes and exposes window.Selwise.

npm install @selwise/widget

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,
});

npm install @selwise/react-native @react-native-async-storage/async-storage

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.2',
});

Notes:

apiKey is required and must be created from dashboard mobile key management.
RN SDK automatically sends x-selwise-api-key, x-selwise-client-platform, and x-selwise-client-version headers.

First Runtime Check

Web

console.log(window.Selwise);
console.log(window.Selwise?.siteKey);
console.log(window.Selwise?.apiUrl);
console.log(window.Selwise?.getVisitorId?.());

React Native

console.log(sdk.getVisitorId());
console.log(sdk.getSessionId());
console.log(sdk.getJourneyId());

Environment Variables

NEXT_PUBLIC_SELWISE_SITE_KEY="sk_xxx"
NEXT_PUBLIC_SELWISE_API_URL="https://api.selwise.com/api/v1"
NEXT_PUBLIC_SELWISE_WIDGET_URL="https://widget.selwise.com/client.js"

Common Installation Problems

window.Selwise is undefined.

CDN: wrong script URL or missing data-site-key.
npm: exposeGlobal is false by default.

Mobile requests return auth errors.

missing or revoked x-selwise-api-key
missing mobile_read/mobile_write scope

Events are not reaching backend.

consent state blocks event family
payload shape invalid for canonical event