Integration Troubleshooting
How To Use This Page
Find your symptom, confirm the platform column, then apply the exact fix.
Runtime Initialization
| Symptom | Platform | Probable Cause | Exact Fix |
|---|---|---|---|
window.Selwise is undefined | CDN | Script URL/path or data-site-key is wrong | Use https://widget.selwise.com/client.js and verify data-site-key. |
window.Selwise is undefined | npm | exposeGlobal is false or init() never ran in browser | Enable exposeGlobal: true if global API is required and run init on client. |
sdk methods return empty/defaults | React Native | init() failed or not awaited | await sdk.init(...) before invoking tracking/identity methods. |
Auth and Access
| Symptom | Platform | Probable Cause | Exact Fix |
|---|---|---|---|
| 403 origin validation failed | CDN / npm | Domain not verified or request origin mismatch | Verify site domain in dashboard and ensure request originates from approved domain. |
| 403 invalid API key or insufficient scope | React Native | Missing/invalid x-selwise-api-key or wrong scope | Rotate key if needed; include proper scope (GET -> mobile_read, write methods -> mobile_write). |
| 401/403 on private APIs | All | Wrong token model | Use public site endpoints for client runtime, private endpoints only with Bearer auth. |
Event and Order Delivery
| Symptom | Platform | Probable Cause | Exact Fix |
|---|---|---|---|
| Event visible locally but missing in backend | All | Non-canonical event name or missing required payload fields | Use Event Cookbook canonical payload templates. |
| Duplicate events | CDN / npm | Multiple runtime instances in app shell | Keep one singleton runtime instance and clean up on unmount. |
| Duplicate orders / conflict | All | Retried same order without idempotency guard | Deduplicate by orderId; retry only transient failures. |
| Event queue not draining | React Native | Offline state or retry backoff window active | Reconnect network, call await sdk.flush(), and verify retry delay has elapsed. |
Search and Recommendations
| Symptom | Platform | Probable Cause | Exact Fix |
|---|---|---|---|
| Search endpoint returns data but UI not updated | React Native | SDK is headless, no default rendering | Render response with your own RN components. |
| Recommendation products empty | All | Missing widget ID/context or no eligible products | Validate widget ID and optional context (currentProductId, visitorId). |
| Search analytics incomplete | All | Only query event emitted, interaction events missing | Emit filter/sort/page/click events as part of flow instrumentation. |
Consent and Privacy
| Symptom | Platform | Probable Cause | Exact Fix |
|---|---|---|---|
| Consent granted but analytics still absent | All | Incorrect event payload or site mismatch | Validate canonical payload, siteKey, and API URL environment. |
| Consent resets unexpectedly | All | Storage cleared or environment switched | Recheck storage persistence and environment-specific site keys. |
| Withdraw consent call fails | React Native | Using read-only scoped key | Ensure mobile_write scope for consent write endpoints. |
Rate Limits and Reliability
| Symptom | Platform | Probable Cause | Exact Fix |
|---|---|---|---|
| Frequent 429 responses | All | Burst traffic without backoff | Respect Retry-After, add exponential backoff and jitter. |
| High latency in event visibility | React Native | Large flush interval/batch settings | Tune flushIntervalMs and batchSize conservatively. |
| Random data loss during app close | React Native | App terminated before queue flush | Flush on lifecycle transitions and keep periodic flush enabled. |
Escalation Checklist
Before escalating to support, collect:
- Integration model (
CDN,npm,React Native) and SDK/package version. siteKey(masked) and environment (staging/production).- Failing endpoint + HTTP status + response body (masked).
- Representative payload sample (masked PII).
- Confirmation that Verification probes were run.