React Native integration

In plain English: this page is a collection of how-tos for the Amply React Native SDK beyond "just get it running." It covers peer dependencies, the iOS pod install step, Android autolinking, using the useAmplySystemEvents hook, cleaning up listeners so you don't leak memory, and handling re-initialization when the JS bundle reloads. A PM can skim the headings; an engineer copies the TypeScript snippets.

Use this when the React Native SDK is installed and you need to wire a specific flow. Don't use this when you haven't finished the Quickstart yet — start there.

Before you start

• React Native 0.79+, Expo SDK 54+ (or bare RN 0.79+) — see Installation for the full requirements matrix.

• New Architecture enabled (the SDK uses the new native module system).

• Node 18+.

Peer dependencies and install

The SDK requires react >=18.2.0, react-native >=0.79.0, and expo >=54.0.0 as peer dependencies — make sure your app has them, then install:

npm install @amplytools/react-native-amply-sdk

iOS: run pod install

After installing the npm package, refresh the iOS native project. This links the native iOS SDK into your app.

cd ios
pod install
cd ..

Run this every time you change the installed npm version of the SDK.

Android: autolinking is automatic

On Android there is no manual Gradle edit. The SDK ships a react-native.config.js entry that React Native's autolinking picks up on the next build. Just rebuild:

npx react-native run-android

If you use Expo with expo prebuild, the SDK's config plugin registers the native package for you during prebuild.

Initialize once, early

Call initialize once, as close to app start as possible. The function returns a Promise that resolves when the native SDK is ready.

Signature:

Amply.initialize(config: AmplyInitializationConfig): Promise<void>

type AmplyInitializationConfig = {
  appId: string;
  apiKeyPublic: string;
  apiKeySecret?: string | null;
  endpoint?: string | null;
  defaultConfig?: string | null;
  debug?: boolean | null;
  logLevel?: LogLevel | null;
};

// App.tsx
import {useEffect} from 'react';
import Amply from '@amplytools/react-native-amply-sdk';

export default function App() {
  useEffect(() => {
    Amply.initialize({
      appId: 'com.example.app',
      apiKeyPublic: 'pk_...',
      apiKeySecret: 'sk_...',
      logLevel: 'warn',
    }).catch(err => console.warn('[Amply] init failed', err));
  }, []);

  return <RootNavigator />;
}

Amply.isInitialized() returns true synchronously once initialize has resolved.

Custom property value types

RN custom properties accept string | number | boolean only. The iOS and Android native SDKs accept more types — stick to primitives on React Native.

Re-init on Fast Refresh / JS reload

Pressing R in Metro re-runs your JS bundle but the native side stays alive. The native SDK remains initialized across JS reloads. Guarding your init is optional but keeps logs clean:

if (!Amply.isInitialized()) await Amply.initialize(config);

On a cold launch, both JS and native start fresh — always call initialize on mount.

Listening to system events

System events are SDK lifecycle signals: config loaded, session started, campaign evaluated. Two APIs are available.

Option 1: the hook (good for debug UI)

Signature:

useAmplySystemEvents(options?: {
  maxEntries?: number;       // default 50
  dedupe?: boolean;          // default true
  onEvent?: (event: EventRecord) => void;
}): {events: EventRecord[]; reset: () => void};

import {useAmplySystemEvents} from '@amplytools/react-native-amply-sdk';

function DebugPanel() {
  const {events, reset} = useAmplySystemEvents({maxEntries: 20});
  return (
    <View>
      {events.map(e => <Text key={e.id}>{e.name} @ {e.timestamp}</Text>)}
      <Button title="Clear" onPress={reset} />
    </View>
  );
}

Option 2: the raw listener (good for production)

Returns a Promise that resolves to an unsubscribe function.

Signature:

Amply.addSystemEventListener(
  listener: (event: EventRecord) => void
): Promise<() => void>;
// Alias: Amply.systemEvents.addListener(listener)

useEffect(() => {
  let unsubscribe: (() => void) | undefined;
  let cancelled = false;

  Amply.systemEvents.addListener(event => {
    console.log('[Amply]', event.name, event.properties);
  }).then(unsub => {
    if (cancelled) unsub();           // component unmounted before subscribe landed
    else unsubscribe = unsub;
  });

  return () => {
    cancelled = true;
    unsubscribe?.();                  // always call the unsubscribe
  };
}, []);

Always call the returned unsubscribe in cleanup. Subscriptions that outlive the component that created them will keep the listener running on stale state and can leak memory across navigations.

Receiving campaign deeplinks

Same Promise-returns-unsubscribe shape.

Signature:

Amply.addDeepLinkListener(
  listener: (event: DeepLinkEvent) => void
): Promise<() => void>;

type DeepLinkEvent = {url: string; info: JsonMap; consumed: boolean};

useEffect(() => {
  let unsubscribe: (() => void) | undefined;
  let cancelled = false;
  Amply.addDeepLinkListener(event => {
    navigation.navigate('Route', {url: event.url});
  }).then(unsub => { if (cancelled) unsub(); else unsubscribe = unsub; });
  return () => { cancelled = true; unsubscribe?.(); };
}, [navigation]);

Declare your URL scheme in Info.plist and AndroidManifest.xml — see iOS integration and Android integration.

Tracking events and identifying the user

Amply.track({name: 'ScreenViewed', properties: {screen: 'Home'}});

Amply.setUserId('user_42');
Amply.setCustomProperties({plan: 'premium', seats: 3, trial: false});
await Amply.getCustomProperty('plan');   // 'premium'
Amply.setUserId(null);                   // clear

See Tracking events and User attributes for payload rules.

Tearing down all listeners

For hard resets (user logs out, tests):

Amply.removeAllListeners();

This clears every deeplink subscription the SDK is currently tracking. It does not uninitialize the SDK.

Log level

Amply.setLogLevel('debug');   // 'none' | 'error' | 'warn' | 'info' | 'debug'
Amply.getLogLevel();

Debug logging is forwarded to console automatically when the level is not 'none'.

Related

• React Native quickstart — initial setup, not covered here.

• Tracking events — payload shapes and common patterns.

• Handling deeplinks — cross-platform deeplink routing patterns.

• iOS integration — platform-specific flows that still apply under RN.

• Android integration — platform-specific flows that still apply under RN.

• SDK reference: React Native — full method list.