Skip to main content

Platform Playbooks

Why This Page Exists

Use this page to pick the right integration model and follow the correct onboarding path without mixing runtime patterns.

Platform Decision Matrix

GoalRecommended ModelWhy
Launch fastest on an existing storefrontCDN (<script>)Zero framework wiring, auto-init, global API available immediately.
Keep strict lifecycle control in SPA/SSR appnpm (@selwise/widget)Single-instance control with explicit init() and destroy().
Integrate in mobile app (Expo/Bare RN)React Native (@selwise/react-native)Headless SDK, mobile key scopes, no DOM dependencies.
Reuse global window.Selwise snippetsCDN or npm with exposeGlobal: trueMaintains global call style.
Build fully custom mobile UI for search/recommendationsReact NativeData APIs are exposed, rendering is app-owned.
  1. Complete Installation.
  2. Open the model-specific playbook:
  1. Run Verification.
  2. If any probe fails, use Integration Troubleshooting.

Migration Paths

CDN -> npm

  1. Remove CDN <script> from base layout.
  2. Install @selwise/widget.
  3. Create one shared runtime instance in your app shell.
  4. Keep exposeGlobal: true temporarily if legacy window.Selwise calls exist.
  5. Move global calls to instance calls (widget.track(...)) over time.
  6. Run full verification probes.

Web -> React Native (Headless)

  1. Keep the same siteKey.
  2. Create mobile public API keys from dashboard with mobile_read and mobile_write scopes.
  3. Initialize @selwise/react-native with apiKey.
  4. Set screen context on navigation changes.
  5. Move event calls to sdk.track(...) and flush strategically (sdk.flush()).
  6. Replace widget rendering assumptions with your own RN UI using headless APIs.

npm -> CDN (Rollback / Simplification)

  1. Re-add canonical CDN script tag.
  2. Remove app-level runtime bootstrap code.
  3. Validate that required global calls still exist.
  4. Re-run verification probes for tracking, orders, and consent.

Guardrails

  • Do not run CDN and npm runtime at the same time in the same web shell.
  • Do not initialize multiple runtime instances per app shell.
  • Do not ship mobile API keys with broader scopes than needed.
  • Do not treat React Native SDK as a widget renderer (v1 is headless).

Next