> For the complete documentation index, see [llms.txt](https://docs.amply.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amply.tools/developer-guide/quickstart-react-native.md).

# 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](/developer-guide/installation.md) 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](/developer-guide/installation.md) 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.

{% code title="App.tsx" %}

```typescript
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>
  );
}
```

{% endcode %}

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.

{% hint style="info" %}
`Amply.isInitialized()` is synchronous and returns `true` after the promise resolves. Use it from screens that mount before init completes.
{% endhint %}

## 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.

```typescript
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:

```typescript
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](/developer-guide/react-native-integration.md) — deep link listeners, system events, snapshots, hooks
* [Concepts → Sessions and events](/concepts/sessions-and-events.md) — how events, properties, and datasets fit together
* [Recipes — entry-based onboarding routing](/recipes/entry-based-onboarding-routing.md) — ready-made pattern for signup and onboarding flows

## Related

* [Installation](/developer-guide/installation.md) — npm package, Expo plugin, version requirements
* [iOS Quickstart](/developer-guide/quickstart-ios.md) — native Swift flow
* [Android Quickstart](/developer-guide/quickstart-android.md) — native Kotlin flow


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amply.tools/developer-guide/quickstart-react-native.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.