npm package: @selwise/react-native
Description: Selwise headless React Native SDK
Latest version: 0.1.5

# @selwise/react-native

Headless React Native SDK for Selwise tracking, identity, search, and recommendations.

## Install

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

Compatible with Expo and Bare React Native.

## Quick Start

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

## Config Reference

| Field | Required | Default | Description |
| --- | --- | --- | --- |
| `siteKey` | Yes | - | Selwise site key. |
| `apiKey` | Yes | - | Scoped mobile API key. |
| `apiUrl` | No | `https://api.selwise.com/api/v1` | API base URL. |
| `sdkPlatform` | No | `react-native` | Header value for client platform. |
| `sdkVersion` | No | `0.1.0` | Header value for SDK version. |
| `flushIntervalMs` | No | `15000` | Periodic flush interval. |
| `batchSize` | No | `25` | Max events per flush batch. |
| `maxRetries` | No | `5` | Retry attempts per failed event. |
| `maxQueueSize` | No | `500` | Max queued events. |
| `journeyTtlMs` | No | `1800000` | Journey expiration window. |
| `storagePrefix` | No | `selwise_rn` | Storage key prefix. |
| `storage` | No | AsyncStorage if available, otherwise in-memory | Custom storage adapter. |

## Method Availability

| Method Group | Available | Notes |
| --- | --- | --- |
| Lifecycle (`init`, `destroy`) | Yes | `init` required before other calls. |
| Tracking (`track`, `flush`) | Yes | `flush` forces immediate network send. |
| Orders (`trackOrder`) | Yes | Sends to public order endpoint. |
| Identity (`identify`, `setTraits`) | Yes | Links and updates user profile state. |
| Session/Journey getters | Yes | Returns runtime IDs and journey state. |
| Data layer (`pushDataLayer`, `getDataLayer`) | Yes | Local state snapshot, not a network sender by itself. |
| Consent (`getConsentState`, `grantConsent`, `revokeConsent`) | Yes | Uses public consent endpoints with scoped auth. |
| Headless data APIs (`search`, recommendation, config methods) | Yes | You render UI in app code. |
| `window.Selwise` / DOM rendering | No | v1 is headless only. |

## Track vs Data Layer

```ts
sdk.track('product_view', {
  entityType: 'product',
  entityId: 'sku-123',
  metadata: { productItemCode: 'sku-123' },
});

await sdk.flush();
```

```ts
sdk.pushDataLayer({
  event: 'product_view',
  product: { sku: 'sku-123', title: 'Runner Pro' },
});

console.log(sdk.getDataLayer());
```

- `track` is for canonical network event ingestion.
- `pushDataLayer` is for local structured state mirroring.

## Auth Scope Quick Reference

| HTTP Method | Required Scope |
| --- | --- |
| `GET` | `mobile_read` |
| `POST`, `PUT`, `PATCH`, `DELETE` | `mobile_write` |

Headers sent automatically:

- `x-selwise-api-key`
- `x-selwise-client-platform`
- `x-selwise-client-version`

## Troubleshooting

1. `403 Invalid API key or insufficient scope`.
- Check key status and method scope.

2. Events are queued but not ingested.
- Call `await sdk.flush()` and verify network/retry window.

3. Search/recommendation responses arrive but nothing renders.
- SDK is headless; render data with your own RN components.

## Documentation

- [React Native Integration](https://docs.selwise.com/getting-started/react-native-integration/)
- [Platform Playbooks](https://docs.selwise.com/getting-started/platform-playbooks/)
- [Public API](https://docs.selwise.com/client-api/public-api/)
- [Event Cookbook](https://docs.selwise.com/client-api/event-cookbook/)
- [Mobile Auth](https://docs.selwise.com/client-api/mobile-auth/)
- [Verification](https://docs.selwise.com/getting-started/verification/)
- [Troubleshooting](https://docs.selwise.com/getting-started/integration-troubleshooting/)

## License

MIT, see [LICENSE](./LICENSE).