diff --git a/docs/sources/react-native-tracker/index.md b/docs/sources/react-native-tracker/index.md index 32e879765..de612c1b3 100644 --- a/docs/sources/react-native-tracker/index.md +++ b/docs/sources/react-native-tracker/index.md @@ -240,6 +240,40 @@ You can also get back session data from the tracker at runtime, that may be usef You can find out more on how to use the tracker's methods to get session data at runtime in the corresponding [session tracking documentation](/docs/sources/react-native-tracker/tracking-events/session-tracking/index.md#getting-session-data-from-the-tracker). +## Using with react-native-web + +The React Native tracker supports browser SPA deployments via react-native-web, which polyfills the React Native APIs the tracker relies on. Screen view tracking, the screen context entity, and screen_end events all work correctly in a browser SPA environment once the following prerequisites are met. + +### Prerequisites + +The event store requires configuration on web. By default, the tracker uses `@react-native-async-storage/async-storage` for persistent event storage. On web, you must either configure the AsyncStorage web adapter or disable persistent storage by setting `useAsyncStorageForEventStore: false`: + +```typescript +const tracker = await newTracker({ + namespace: 'appTracker', + endpoint: COLLECTOR_URL, + useAsyncStorageForEventStore: false, // use in-memory event store on web +}); +``` + +If the AsyncStorage web adapter is absent and `useAsyncStorageForEventStore` is not set to `false`, `newTracker()` rejects silently and no events are sent. + +You must also `await newTracker()` before calling any tracking method. Calling tracking methods before the initialization Promise resolves results in missing entities and events, including the screen context entity and screen_end events: + +```typescript +// correct: await initialization before tracking +const tracker = await newTracker({ ... }); +tracker.trackScreenViewEvent({ name: 'home' }); +``` + +### Known limitations + +When `Platform.OS === 'web'`, the following limitations apply compared to iOS and Android builds. + +The `platformContext` entity is not tracked. All four required properties (`osType`, `osVersion`, `deviceManufacturer`, `deviceModel`) are unavailable in a browser environment, so the platform context entity is absent from all events. + +When `lifecycleAutotracking` is enabled, foreground and background events fire based on the browser tab's visibility state rather than native app state transitions. + ## Removing a tracker The React Native Tracker API also provides functions to remove a tracker or remove all trackers at runtime. You can find out how in the [Removing trackers at runtime](/docs/sources/react-native-tracker/advanced-usage/index.md) documentation. diff --git a/docs/sources/react-native-tracker/tracking-events/screen-tracking/index.md b/docs/sources/react-native-tracker/tracking-events/screen-tracking/index.md index cc35c886a..f8868b882 100644 --- a/docs/sources/react-native-tracker/tracking-events/screen-tracking/index.md +++ b/docs/sources/react-native-tracker/tracking-events/screen-tracking/index.md @@ -31,6 +31,25 @@ The steps are explained [in the documentation for React Navigation](https://reac When using the [React Native Navigation](https://wix.github.io/react-native-navigation/docs/before-you-start/) library for navigation in your app, you can automatically track screen views by registering a listener when your component appears on screen. Use the `Navigation.events().registerComponentDidAppearListener` callback to subscribe the listener and track screen views as [documented here](https://wix.github.io/react-native-navigation/api/events/#componentdidappear). +## Using screen tracking in a browser SPA + +When you deploy the React Native tracker in a browser SPA via react-native-web, screen view tracking works without a navigation library integration. Calling `trackScreenViewEvent` directly triggers screen transitions, and the screen context entity and screen_end events are produced as they are on iOS and Android. + +For these events and entities to appear, you must `await newTracker()` before the first `trackScreenViewEvent` call: + +```typescript +const tracker = await newTracker({ + namespace: 'appTracker', + endpoint: COLLECTOR_URL, +}); + +tracker.trackScreenViewEvent({ name: 'home' }); +// screen_end fires automatically before the next screen view +tracker.trackScreenViewEvent({ name: 'product' }); +``` + +If `newTracker()` rejects silently (commonly caused by a missing AsyncStorage web adapter), no events are sent and neither the screen context entity nor screen_end will appear. See [Using with react-native-web](/docs/sources/react-native-tracker/index.md#using-with-react-native-web) for the full setup requirements. + ## Screen context entity ```typescript