Unified SDK for React Native reference

This reference documents every public export of @amplitude/unified-react-native and every option you can pass to init(), verified against version 1.0.0-beta.11. That version bundles @amplitude/analytics-react-native 1.13.0, @amplitude/plugin-experiment-react-native 1.0.0-beta.12, and @amplitude/plugin-session-replay-react-native 0.5.12. For changes between versions, go to the @amplitude/unified-react-native changelog.

import * as amplitude from "@amplitude/unified-react-native";

The top-level functions act on a default client. Each client from createInstance() has the same methods.

Exports

Unified SDK exports

Export	Description
`init`	Initializes every product.
`experiment`	Returns the Feature Experiment client.
`sessionReplay`	Returns the Session Replay plugin.
`createInstance`	Creates another client.
`AmpMaskView`	Component that masks, unmasks, or blocks its children in Session Replay.

React Native SDK exports

These work as in the React Native SDK reference: add, extendSession, flush, getDeviceId, getSessionId, getUserId, groupIdentify, identify, logEvent, remove, reset, revenue, setDeviceId, setGroup, setOptOut, setSessionId, setUserId, track, trackScreenView, trackScreenViewOnNavigationStateChange, createNetworkRequestEvent, Identify, Revenue, and Types.

The package doesn't export ampCapture. Import it from @amplitude/analytics-react-native. For details, go to Track element interactions.

Type-only exports

UnifiedClient, UnifiedOptions, and UnifiedSharedOptions are TypeScript types, with no runtime value.

Setup

init

Initializes Analytics, then Feature Experiment, Session Replay, and Guides and Surveys. Call it once.

init(apiKey: string, options?: UnifiedOptions): Promise<void>

Parameter	Type	Description
`apiKey`	`string`	Your Amplitude project API key.
`options`	`UnifiedOptions`	Optional. Go to UnifiedOptions.

init() returns a plain Promise, not { promise } like the analytics methods. It resolves after every product finishes, and never rejects. Later calls return the first call's promise without changing anything. Failures go to the analytics logger as Failed to initialize <product>.

await amplitude.init("AMPLITUDE_API_KEY", {
  serverZone: "EU",
  sessionReplay: { sampleRate: 0.1 },
});

experiment

Returns the Feature Experiment client, or undefined before init() finishes.

experiment(): IExperimentClient | undefined

const variant = amplitude.experiment()?.variant("checkout-redesign");

For the client's methods, such as fetch(), variant(), all(), and exposure(), go to the Experiment React Native SDK.

sessionReplay

Returns the Session Replay plugin, or undefined before init() finishes or when Session Replay failed to install.

sessionReplay(): SessionReplayPlugin | undefined

Method	Description
`start()`	Starts recording. Use it with `autoStart: false`.
`stop()`	Stops recording.
`getSessionReplayProperties()`	Resolves to the Session Replay properties for the current session, or `{}` if Session Replay isn't initialized.

await amplitude.sessionReplay()?.stop();

createInstance

Creates another client with its own analytics instance.

createInstance(): UnifiedClient

Clients share one Guides and Surveys plugin: the first client to initialize sets its API key and engagement options.

const secondary = amplitude.createInstance();
await secondary.init("OTHER_API_KEY", { instanceName: "secondary" });

UnifiedClient

The type of the default client and of each createInstance() client. It has every React Native SDK client method except init, plus:

Member	Description
`init(apiKey, options?)`	Go to init.
`experiment()`	Go to experiment.
`sessionReplay()`	Go to sessionReplay.

UnifiedOptions

Shared options

Top-level options apply to several products. A value in a product block overrides the top-level value for that product.

Option	Type	Default	Passed to
`serverZone`	`"US"` \| `"EU"`	`"US"`	Analytics, Feature Experiment, Guides and Surveys
`instanceName`	`string`	`$default_instance`	Analytics, Feature Experiment
`logLevel`	`Types.LogLevel`	`LogLevel.Warn`	Analytics, Session Replay, Guides and Surveys

Guides and Surveys receives logLevel as a lowercase string, such as "warn".

Product options

Option	Type	Description
`analytics`	`ReactNativeOptions`	Go to React Native SDK configuration options. Pass `userId` here to start with a user ID.
`experiment`	`ExperimentPluginConfig`	Experiment client options, plus `deploymentKey`. Go to experiment options.
`sessionReplay`	`SessionReplayConfig`	Go to sessionReplay options.
`engagement`	Guides and Surveys options	Go to the Guides and Surveys React Native configuration options.

experiment options

Option	Type	Default	Description
`deploymentKey`	`string`	The analytics API key	Client deployment key for Feature Experiment.
Other options	—	—	Every Experiment React Native option. `serverZone` and `instanceName` default to the analytics values.

sessionReplay options

Option	Type	Default	Description
`sampleRate`	`number`	`0`	Share of sessions to record, from `0` to `1`. `0` records nothing.
`autoStart`	`boolean`	`true`	Start recording during `init()`. Set to `false` to call `start()` yourself.
`enableRemoteConfig`	`boolean`	`true`	Fetch Session Replay settings from Amplitude.
`privacyConfig.maskLevel`	`"light"` \| `"medium"` \| `"conservative"`	`"medium"`	Default masking level.
`logLevel`	`Types.LogLevel`	`LogLevel.Warn`	Session Replay log level.

For masking behavior, go to the Session Replay React Native plugin.

AmpMaskView

A view that sets Session Replay masking for its children.

Prop	Type	Description
`mask`	`"amp-mask"` \| `"amp-unmask"` \| `"amp-block"`	Masks text, shows it unmasked, or blocks the whole view.

AmpMaskView accepts every React Native View prop.

Was this helpful?