From 2bba653f89ef87637c9a7c44c4b8ec59422cdf5e Mon Sep 17 00:00:00 2001 From: forstisabella <92472883+forstisabella@users.noreply.github.com> Date: Thu, 11 Sep 2025 10:44:03 -0400 Subject: [PATCH] review --- .../libraries/mobile/react-native/index.md | 83 ++++++++++--------- 1 file changed, 45 insertions(+), 38 deletions(-) diff --git a/src/connections/sources/catalog/libraries/mobile/react-native/index.md b/src/connections/sources/catalog/libraries/mobile/react-native/index.md index 545fb13ec0..1964a1bd4a 100644 --- a/src/connections/sources/catalog/libraries/mobile/react-native/index.md +++ b/src/connections/sources/catalog/libraries/mobile/react-native/index.md @@ -16,7 +16,8 @@ All of Segment's libraries are open-source, and you can view Analytics for React > `@segment/analytics-react-native` is compatible with Expo's [Custom Dev Client](https://docs.expo.dev/development/getting-started/){:target="_blank"} and [EAS builds](https://docs.expo.dev/build/introduction/){:target="_blank"} without any additional configuration. Destination Plugins that require native modules may require custom [Expo Config Plugins](https://docs.expo.dev/guides/config-plugins/){:target="_blank"}. > > `@segment/analytics-react-native` isn't compatible with Expo Go. -## Getting Started + +## Getting started To get started with the Analytics for React Native library: @@ -45,7 +46,7 @@ To get started with the Analytics for React Native library: npm install --save @react-native-async-storage/async-storage ``` - To use your own persistence layer you can use the storePersistor option when initializing the client. Make sure you always have a persistor (either by having AsyncStorage package installed or by explicitly passing a value), else you might get unexpected side effects like multiple 'Application Installed' events + To use your own persistence layer you can use the storePersistor option when initializing the client. Make sure you always have a persistor, either by having AsyncStorage package installed or by explicitly passing a value, or you might get unexpected side effects like multiple 'Application Installed' events. 4. If you're using iOS, install native modules with: @@ -74,7 +75,7 @@ These are the options you can apply to configure the client: | Name | Default | Description | | --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `writeKey` **required** | '' | Your Segment API key. | -| `collectDeviceId` | false | Set to true to automatically collect the device Id.from the DRM API on Android devices. | +| `collectDeviceId` | false | Set to true to automatically collect the device ID from the DRM API on Android devices. | | `debug` | true\* | When set to false, it will not generate any logs. | | `logger` | undefined | Custom logger instance to expose internal Segment client logging. | | `flushAt` | 20 | How many events to accumulate before sending events to the backend. | @@ -82,17 +83,19 @@ These are the options you can apply to configure the client: | `flushPolicies` | undefined | Add more granular control for when to flush, see [Adding or removing policies](#adding-or-removing-policies) | | `maxBatchSize` | 1000 | How many events to send to the API at once | | `trackAppLifecycleEvents` | false | Enable automatic tracking for [app lifecycle events](/docs/connections/spec/mobile/#lifecycle-events): application installed, opened, updated, backgrounded | -| `trackDeepLinks` | false | Enable automatic tracking for when the user opens the app with a deep link. This requires additional setup on iOS, [see instructions](#ios-deep-link-tracking-setup) | -| `defaultSettings` | undefined | Settings that will be used if the request to get the settings from Segment fails. Type: [SegmentAPISettings](https://github.com/segmentio/analytics-react-native/blob/c0a5895c0c57375f18dd20e492b7d984393b7bc4/packages/core/src/types.ts#L293-L299) | -| `autoAddSegmentDestination` | true | Set to false to skip adding the SegmentDestination plugin | -| `storePersistor` | undefined | A custom persistor for the store that `analytics-react-native` uses. Must match [`Persistor`](https://github.com/segmentio/analytics-react-native/blob/master/packages/sovran/src/persistor/persistor.ts#L1-L18) interface exported from [sovran-react-native](https://github.com/segmentio/analytics-react-native/blob/master/packages/sovran). | +| `trackDeepLinks` | false | Enable automatic tracking for when the user opens the app with a deep link. This requires additional setup on iOS. For more information, see the [deep link tracking setup instructions](#ios-deep-link-tracking-setup) | +| `defaultSettings` | undefined | Settings that will be used if the request to get the settings from Segment fails. Type: [SegmentAPISettings](https://github.com/segmentio/analytics-react-native/blob/c0a5895c0c57375f18dd20e492b7d984393b7bc4/packages/core/src/types.ts#L293-L299){:target="_blank”} | +| `autoAddSegmentDestination` | true | Set this to false to skip adding the SegmentDestination plugin | +| `storePersistor` | undefined | A custom persistor for the store that `analytics-react-native` uses. Must match [`Persistor`](https://github.com/segmentio/analytics-react-native/blob/master/packages/sovran/src/persistor/persistor.ts#L1-L18){:target="_blank”} interface exported from [sovran-react-native](https://github.com/segmentio/analytics-react-native/blob/master/packages/sovran){:target="_blank”}. | | `proxy` | undefined | `proxy` is a batch url to post to instead of 'https://api.segment.io/v1/b'. | -| `errorHandler` | undefined | Create custom actions when errors happen, see [Handling errors](#handling-errors) | +| `errorHandler` | undefined | Create custom actions when errors happen. For more details, see the [Handling errors](#handling-errors) documentation. | | `useSegmentEndpoints` | false | Set to `true` to automatically append the Segment endpoints when using `proxy` or `cdnProxy` to send or fetch settings. Otherwise, `proxy` or `cdnProxy` will be used as is. | -## Adding Plugins to the Client +## Adding plugins to the client + +You can add a plugin at any time through the `segmentClient.add()` method. More information about plugins, including a detailed architecture overview and a guide to creating your own, can be found in the [Analytics React Native Plugin Architecture](/docs/connections/sources/catalog/libraries/mobile/react-native/react-native-plugin-architecture/) docs. -You can add a plugin at any time through the `segmentClient.add()` method. More information about plugins, including a detailed architecture overview and a guide to creating your own can be found in the [Analytics React Native Plugin Architecture](/docs/connections/sources/catalog/libraries/mobile/react-native/react-native-plugin-architecture/) docs. +Here's an example of the `segmentClient.add()` method: ```js import { createClient } from '@segment/analytics-react-native'; @@ -243,7 +246,7 @@ group('some-company', { {% endcodeexampletab %} {% endcodeexample %} -## Utility Methods +## Utility methods The Analytics React Native 2.0 utility methods help you to manage your data. They include: - Alias - Reset @@ -251,7 +254,7 @@ The Analytics React Native 2.0 utility methods help you to manage your data. The - Cleanup ### Alias -The [alias](/docs/connections/spec/alias/) method is used to merge two user identities by connecting two sets of user data as one. This method is required to manage user identities in some of Segment's destinations. +The [Alias](/docs/connections/spec/alias/) method is used to merge two user identities by connecting two sets of user data as one. This method is required to manage user identities in some of Segment's destinations. {% codeexample %} {% codeexampletab Method signature %} @@ -273,7 +276,7 @@ alias('user-123'); The reset method clears the internal state of the library for the current user and group. This is useful for apps where users can log in and out with different identities over time. > warning "" -> **Note:** Each time you call reset, a new AnonymousId is generated automatically. +> **Note:** Each time you call reset, Segment generates a new AnonymousId. {% codeexample %} {% codeexampletab Method signature %} @@ -313,7 +316,7 @@ flush(); {% endcodeexample %} ### Cleanup -In case you need to reinitialize the client, that is, you've called createClient more than once for the same client in your application lifecycle, use this method on the old client to clear any subscriptions and timers first. +If you've called createClient more than once for the same client in your application lifecycle, use this method on the old client to clear any subscriptions and timers first. ```js let client = createClient({ @@ -331,7 +334,7 @@ If you don't do this, the old client instance would still exist and retain the t Ideally, you shouldn't have to use this method, and the Segment client should be initialized only once in the application lifecycle. -## Control upload with Flush Policies +## Control upload with flush policies To granularly control when Segment uploads events you can use `FlushPolicies`. A Flush Policy defines the strategy for deciding when to flush. This can be on an interval, time of day, after receiving a certain number of events, or after receiving a particular event. This gives you more flexibility on when to send event to Segment. Set Flush Policies in the configuration of the client: @@ -346,7 +349,7 @@ const client = createClient({ }); ``` You can set several policies at a time. When a flush occurs, it triggers an upload of the events, then resets the logic after every flush. -As a result, only the first policy to reach `shouldFlush` will trigger a flush. In the example above either the event count reaches 5 or the timer reaches 500ms, whatever comes first will trigger a flush. +As a result, only the first policy to reach `shouldFlush` triggers a flush. In the example above either the event count reaches 5 or the timer reaches 500ms, whatever comes first, will trigger a flush. Segment has several standard Flush Policies: - `CountFlushPolicy` triggers when you reach a certain number of events - `TimerFlushPolicy` triggers on an interval of milliseconds @@ -406,7 +409,7 @@ export class FlushOnScreenEventsPolicy extends FlushPolicyBase { ``` ## Automatic screen tracking -As sending a screen() event with each navigation action can get tiresome, it's best to track navigation globally. The implementation is different depending on which library you use for navigation. The two main navigation libraries for React Native are [React Navigation](https://reactnavigation.org/){:target="_blank"} and [React Native Navigation](https://wix.github.io/react-native-navigation/docs/before-you-start/){:target="_blank"}. +As sending a Screen event with each navigation action can get tiresome, it's best to track navigation globally. The implementation is different depending on which library you use for navigation. The two main navigation libraries for React Native are [React Navigation](https://reactnavigation.org/){:target="_blank"} and [React Native Navigation](https://wix.github.io/react-native-navigation/docs/before-you-start/){:target="_blank"}. ### React Navigation When setting up React Navigation, you'll essentially find the root level navigation container and call `screen()` whenever the user navigates to a new screen. Segment's [example app](https://github.com/segmentio/analytics-react-native/tree/master/example){:target="_blank"} is set up with screen tracking using React Navigation, so you can use it as a guide. @@ -451,7 +454,7 @@ To set up automatic screen tracking with React Navigation: } }} > -``` + ``` ### React Native Navigation In order to set up automatic screen tracking while using [React Native Navigation](https://wix.github.io/react-native-navigation/docs/before-you-start/){:target="_blank"}: @@ -465,8 +468,8 @@ In order to set up automatic screen tracking while using [React Native Navigatio }); ``` -## Plugin Architecture -Segment's plugin architecture enables you to modify and augment how the events are processed before they're uploaded to the Segment API. In order to customize what happens after an event is created, you can create and place various Plugins along the processing pipeline that an event goes through. This pipeline is referred to as a timeline. +## Plugin architecture +Segment's plugin architecture enables you to modify and augment how the events are processed before they're uploaded to the Segment API. In order to customize what happens after an event is created,create and place various Plugins along the processing pipeline that an event goes through. This pipeline is called a timeline. ### Plugin Types @@ -476,17 +479,17 @@ Segment's plugin architecture enables you to modify and augment how the events a | `enrichment` | Executes as the first level of event processing. | | `destination` | Executes as events begin to pass off to destinations. | | `after` | Executes after all event processing is completed. You can use this to perform cleanup operations. | -| `utility` | Executes only with manual calls such as Logging. | +| `utility` | Executes only with manual calls like Logging. | > info "" -> Plugins can have their own native code (such as the iOS-only [`IdfaPlugin`](https://github.com/segmentio/analytics-react-native/blob/829fc80bc8c4f59fa99dadd25083efa422d577f0/packages/plugins/plugin-idfa/README.md){:target="_blank"} or wrap an underlying library (such as the [`FirebasePlugin`](https://www.npmjs.com/package/@segment/analytics-react-native-plugin-firebase) which uses `react-native-firebase` under the hood). +> Plugins can have their own native code (like the iOS-only [`IdfaPlugin`](https://github.com/segmentio/analytics-react-native/blob/829fc80bc8c4f59fa99dadd25083efa422d577f0/packages/plugins/plugin-idfa/README.md){:target="_blank"}) or wrap an underlying library (like the [`FirebasePlugin`](https://www.npmjs.com/package/@segment/analytics-react-native-plugin-firebase) which uses `react-native-firebase` under the hood). -### Destination Plugins +### Destination plugins Segment is an out-of-the-box `DestinationPlugin`. You can add as many other destination plugins as you like and upload events and data to them. If you don't want the Segment destination plugin, you can pass `autoAddSegmentDestination = false` in the options when setting up your client. This prevents the `SegmentDestination` plugin from being added automatically for you. -### Adding Plugins +### Adding plugins You can add a plugin at any time through the `segmentClient.add()` method. ```js @@ -506,7 +509,7 @@ segmentClient.add({ plugin: new FirebasePlugin() }); segmentClient.add({ plugin: new IdfaPlugin() }); ``` -### Writing your own Plugins +### Writing your own plugins Plugins implement as ES6 Classes. To get started, familiarize yourself with the available classes in `/packages/core/src/plugin.ts`. The available plugin classes are: @@ -548,9 +551,9 @@ segmentClient.add({ plugin: new Logger() }); As the plugin overrides the `execute()` method, this `Logger` calls `console.log` for every event going through the Timeline. -### Add a custom Destination Plugin +### Add a custom destination plugin -You can add custom plugins to Destination Plugins. For example, you could implement the following logic to send events to Braze on weekends only: +You can add custom plugins to destination plugins. For example, you could implement the following logic to send events to Braze on weekends only: ```js @@ -589,7 +592,7 @@ export class BrazeEventPlugin extends Plugin { Segment would then send events to the Braze Destination Plugin on Saturdays and Sundays, based on device time. -### Example Plugins +### Example plugins These are the example plugins you can use and alter to meet your tracking needs: | Plugin | Package | @@ -603,11 +606,12 @@ These are the example plugins you can use and alter to meet your tracking needs: | Firebase | `@segment/analytics-react-native-plugin-consent-firebase` | | IDFA | `@segment/analytics-react-native-plugin-idfa` | - -## Supported Destinations -Segment supports a large number of [Cloud-mode](/docs/connections/destinations/#connection-modes) destinations. Segment also supports the below destinations for Analytics React Native 2.0 in device-mode, with more to follow: +## Supported destinations +Segment supports a large number of [Cloud-mode](/docs/connections/destinations/#connection-modes) destinations. Segment also supports the following destinations for Analytics React Native 2.0 in device-mode: - [Adjust](https://www.npmjs.com/package/@segment/analytics-react-native-plugin-adjust){:target="_blank"} - [Amplitude Session](https://www.npmjs.com/package/@segment/analytics-react-native-plugin-amplitude-session){:target="_blank"} - [Appsflyer](https://www.npmjs.com/package/@segment/analytics-react-native-plugin-appsflyer){:target="_blank"} @@ -658,12 +662,15 @@ On Android, Segment's React Native library generates a unique ID by using the DR To collect the Android Advertising ID provided by Play Services, Segment provides a [plugin](https://github.com/segmentio/analytics-react-native/tree/master/packages/plugins/plugin-advertising-id){:target="_blank"} that can be used to collect that value. This value is set to context.device.advertisingId. For iOS, this [plugin](https://github.com/segmentio/analytics-react-native/tree/master/packages/plugins/plugin-idfa){:target="_blank"} can be used to set the IDFA context.device.advertisingId property. ## FAQs + +Find answers to common Analytics React Native questions. + ### Can I use the catalog of device-mode destinations from Segment's 1.X.X React-Native release? -No, only the plugins listed above are supported in device-mode for Analytics React Native 2.0. +No, Segment only supports the listed plugins in device-mode for Analytics React Native 2.0. ### Will I still see device-mode integrations listed as `false` in the integrations object? When you successfully package a plugin in device-mode, you won't see the integration listed as `false` in the integrations object for a Segment event. This logic is packaged in the event metadata, and isn't surfaced in the Segment debugger. ### Why are my IDs not set in UUID format? -Due to [limitations](https://github.com/segmentio/analytics-react-native/blob/master/packages/core/src/uuid.ts#L5){:target="_blank"} with the React Native bridge, Segment doesn't use UUID format for `anonymousId` and `messageId` values in local development. These IDs will be set in UUID format for your live app. +Due to limitations with the React Native bridge outlined in the Analytics React Native [GitHub repository](https://github.com/segmentio/analytics-react-native/blob/master/packages/core/src/uuid.ts#L5){:target="_blank"}, Segment doesn't use UUID format for `anonymousId` and `messageId` values in local development. These IDs will be set in UUID format for your live app. ### How do I set a distinct writeKey for iOS and android? You can set different writeKeys for iOS and Android. This is helpful if you want to send data to different destinations based on the client side platform. To set different writeKeys, you can dynamically set the writeKey when you initialize the Segment client: @@ -677,7 +684,7 @@ const segmentClient = createClient({ writeKey: segmentWriteKey }); ``` -### What is the instanceId set in context? +### What is the instanceId? The instanceId was introduced in [V 2.10.1](https://github.com/segmentio/analytics-react-native/releases/tag/%40segment%2Fanalytics-react-native-v2.10.1) and correlates events to a particular instance of the client in a scenario when you might have multiple instances on a single app. ### How do I interact with the integrations object? @@ -706,7 +713,7 @@ import { } } ``` -### How do I add to the context Object? +### How do I add to the context object? Like with the integrations object above, you'll need to use a plugin to access and modify the context object. For example, if you'd like to add `context.groupId` to every Track call, you should create a plugin like this: ```js //in AddToContextPlugin.js @@ -736,12 +743,12 @@ segmentClient.add({ plugin: new AddToContextPlugin() }); ``` ### I've upgraded to React Native 2.0, but I am still getting warnings in the Google Play Store that my app is not compliant. Why is this? -The React Native 2.0 library is compliant with Google Play Store policies. However, Segment recommends that you check to see if there are any old and inactive [tracks on the Google Play Store](https://developers.google.com/android-publisher/tracks){:target="_blank"} that are not updated to the latest build. If this is the case, we recommend updating those tracks to resolve the issue. +The React Native 2.0 library is compliant with Google Play Store policies. However, Segment recommends that you check to see if there are any old and inactive [tracks on the Google Play Store](https://developers.google.com/android-publisher/tracks){:target="_blank"} that are not updated to the latest build. If this is the case, Segment recommends updating those tracks to resolve the issue. ### Can I set inlineRequires to false in my metro.config.js file? Segment requires the `inlineRequires` value in your `metro.config.js` value to be set to `true`. To disable `inlineRequires` for certain modules, you can specify this by using a [blockList](https://facebook.github.io/metro/docs/configuration/#:~:text=If%20inlineRequires%20is%20an%20object){:target="_blank"}. -### Can I clear user traits without calling the reset() method? +### Can I clear user traits without calling the reset method? The set method on userInfo can accept a function that receives the current state and returns a modified desired state. Using this method, you can return the current traits, delete any traits you no longer wish to track, and persist the new trait set. ```js