Quickstart — React Native

Install the Amply React Native SDK, initialize it with your API keys, and send your first event. You'll end with a tracked event visible in the Amply dashboard.

This tutorial takes about ten minutes. It uses TypeScript and works the same way for bare React Native and Expo projects. The SDK runs on the native side — Amply.initialize() is async because it hands off to iOS and Android at startup.

Prerequisites

• React Native 0.79+ with the New Architecture enabled (or Expo SDK 54+) — see Installation for the full requirements matrix

• Node 18+ and either npm or yarn

• An Amply dashboard account with appId, apiKeyPublic, and apiKeySecret (Settings → API Keys)

You'll end with

• The SDK initialized when your app mounts

• One custom event tracked from TypeScript

• That event showing up in the Amply dashboard's event log

1. Add the SDK

Follow Installation → React Native to add @amplytools/react-native-amply-sdk. For Expo apps, make sure you've added the config plugin and run npx expo prebuild. For bare RN, run pod install in ios/.

Come back here once import Amply from '@amplytools/react-native-amply-sdk' resolves.

2. Initialize on app start

Initialize Amply once, as early as possible — typically in your root App component, inside a useEffect that runs on mount. initialize() is async and returns a Promise<void>; await it (or chain .then) before calling any other SDK method.

App.tsx

import React, {useEffect, useState} from 'react';
import {Text, View} from 'react-native';
import Amply from '@amplytools/react-native-amply-sdk';

export default function App(): React.JSX.Element {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    Amply.initialize({
      appId: 'com.acme.app',
      apiKeyPublic: 'YOUR_PUBLIC_KEY',
      apiKeySecret: 'YOUR_SECRET_KEY',
      logLevel: 'debug',
    })
      .then(() => setReady(true))
      .catch(error => console.error('Amply init failed', error));
  }, []);

  return (
    <View>
      <Text>{ready ? 'Amply ready' : 'Initializing…'}</Text>
    </View>
  );
}

The AmplyInitializationConfig fields you'll use here:

Field	Type	Required	Notes
appId	string	yes	Your app identifier
apiKeyPublic	string	yes	Public key from the dashboard
apiKeySecret	string	no	Secret key from the dashboard
endpoint	string	no	Override the API host (development only)
logLevel	'none' | 'error' | 'warn' | 'info' | 'debug'	no	Print SDK activity to Metro console

logLevel: 'debug' is the quickest way to see what the SDK is doing in Metro. Switch to 'warn' or 'none' before shipping.

Amply.isInitialized() is synchronous and returns true after the promise resolves. Use it from screens that mount before init completes.

3. Track your first event

Call Amply.track() from any component, hook, or handler. It takes a payload object with a name and an optional properties map.

import Amply from '@amplytools/react-native-amply-sdk';

async function onSignupPress() {
  await Amply.track({
    name: 'Signup',
    properties: {plan: 'pro'},
  });
}

track() returns a Promise<void>. You can await it when you want to be sure the event was handed to the native side (e.g., before navigating), or fire-and-forget for UI events.

Property values must be strings, numbers, or booleans. Keep event names short and consistent — the dashboard segments by event name, so a typo becomes a different event.

4. Identify the user (optional but recommended)

Once you know who the user is — after signup, login, or restoring a session — tell Amply:

Amply.setUserId('user-123');
Amply.setCustomProperties({plan: 'pro', onboarded: true});

setUserId() is fire-and-forget (no promise). Pass null to clear the user ID on sign-out. setCustomProperties() accepts a Record<string, string | number | boolean> and merges into whatever is already stored.

5. Verify in the dashboard

1. Run the app on an iOS simulator, Android emulator, or real device (yarn ios / yarn android, or npx expo run:ios / run:android).

2. Trigger the code path that calls Amply.track({name: 'Signup', ...}).

3. Open the Amply dashboard and go to Events.

4. Watch for a signup entry with plan: pro — it should arrive within a few seconds.

If you don't see it:

• Check the Metro console for [Amply] log lines (visible when logLevel: 'debug' is set)

• Confirm appId / apiKeyPublic / apiKeySecret match the dashboard Settings → API Keys page exactly

• Confirm the device has network connectivity — the first event needs a successful round-trip to prove the pipeline works

• On Expo, confirm you re-ran npx expo prebuild after adding the plugin

What's next

• React Native integration — deep link listeners, system events, snapshots, hooks

• Concepts → Sessions and events — how events, properties, and datasets fit together

• Recipes — entry-based onboarding routing — ready-made pattern for signup and onboarding flows

Related

• Installation — npm package, Expo plugin, version requirements

• iOS Quickstart — native Swift flow

• Android Quickstart — native Kotlin flow