> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> Methods, options, automatic events and limits of the Appeeky Analytics React Native SDK

The React Native and Expo SDK records installs, sessions, screens and your own events, and links each install to the RevenueCat customer. Events are queued on the device and sent in batches. They survive offline periods and app restarts.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Appeeky from "@appeeky/analytics-react-native";
```

***

## Install

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx expo install @react-native-async-storage/async-storage expo-application expo-device
npm install @appeeky/analytics-react-native
```

| Package | Required | Why |
| - | - | - |
| `@react-native-async-storage/async-storage` | Yes | Stores the install id and the event queue |
| `expo-application` | No | Adds the app version and build number |
| `expo-device` | No | Adds the exact device model |

### Config plugin

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "expo": {
    "plugins": ["@appeeky/analytics-react-native"]
  }
}
```

The plugin adds `NSAdvertisingAttributionReportEndpoint` and `AdAttributionKit › AttributionCopyEndpoint` to Info.plist, so iOS sends copies of winning SKAdNetwork and AdAttributionKit postbacks to Appeeky.

| Plugin option | Effect |
| - | - |
| none | Sets both keys to `https://appeeky.com` (hosted) |
| `{ "attributionEndpoint": "https://example.com" }` | Sets both keys to your own registrable domain (self-hosted) |
| `{ "attributionEndpoint": false }` | Leaves Info.plist alone, for example when another provider already receives the copies |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "expo": {
    "plugins": [["@appeeky/analytics-react-native", { "attributionEndpoint": false }]]
  }
}
```

An app can name only one endpoint. See [SKAdNetwork](https://docs.appeeky.com/docs/analytics-skadnetwork.md).

### Native module

The package includes a native module (Expo Modules). It needs a development build or a release build.

| Platform | What the native module adds |
| - | - |
| iOS | Apple Search Ads token (AdServices), SKAdNetwork / AdAttributionKit conversion value updates |
| Android | Google Play Install Referrer |

Without the native module (Expo Go, or a plain React Native app without Expo Modules) the SDK still runs in JavaScript. Events, screens, sessions, `identify` and campaign links keep working. Apple Search Ads attribution, the Play referrer and conversion values turn off, unless you pass `getAdServicesToken` and `getInstallReferrer` yourself (see [Options](#options)).

***

## Methods

### `init(options)`

Starts the SDK. Call it once, as early as possible.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
Appeeky.init({ key: "apk_pub_..." });
```

A second call returns the existing instance and ignores the new options. Other methods called before `init` are ignored (with a warning in development).

### `identify(userId)`

Links the install to a RevenueCat app user id, so purchases get the install's source.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
Appeeky.identify(await Purchases.getAppUserID());

// After Purchases.logIn(newId):
Appeeky.identify(newId);

// On logout:
Appeeky.identify(null);
```

The id is sent with every batch from then on, and the SDK sends a batch soon after `identify` so the install is linked before the first purchase. Ids are cut to 256 characters.

### `screen(name, props?)`

Records a screen view.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
Appeeky.screen("Paywall");
Appeeky.screen("Paywall", { placement: "onboarding" });
```

Screen names are cut to 128 characters. Screens are used by the screen, entry screen and exit screen breakdowns, by funnel steps like `screen:Paywall`, and by the purchase journey in [sale alerts](https://docs.appeeky.com/docs/analytics-alerts.md).

### `track(name, props?, value?)`

Records a custom event, with optional properties and an optional number.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
Appeeky.track("onboarding_completed", { step: 3 });
Appeeky.track("export", { format: "pdf" }, 1);
```

* Event names may use letters, digits, `_`, `.`, `:` and `-`, up to 64 characters.
* Property values are strings (up to 512 characters), numbers, booleans or `null`. All properties of one event together must stay under 4 KB.

Custom events can be funnel steps. Revenue does not come from `track`: use RevenueCat for purchases and `adRevenue` for ads.

### `adRevenue(valueUsd, details?)`

Records ad revenue from one paid impression, in USD. It counts as revenue for the install's source, next to RevenueCat purchases.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
rewarded.addAdEventListener(AdEventType.PAID, (event) => {
  if (event.currency === "USD") {
    Appeeky.adRevenue(event.value, { network: "admob", adUnit: "rewarded_home", format: "rewarded" });
  }
});
```

| Field | Description |
| - | - |
| `valueUsd` | Revenue in USD. Negative or non-numeric values are ignored. |
| `details.network` | Ad network, for example `admob` |
| `details.adUnit` | Ad unit name |
| `details.format` | Ad format, for example `rewarded` |

> [!WARNING]
>
> The value must already be in USD. The SDK does not convert currencies. Skip impressions reported in another currency, as in the example.

### `getDeferredDeepLink()`

Returns the in-app destination of the smart link that brought this install, once, on the first launch. Returns `null` afterwards, or when there is none.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const destination = await Appeeky.getDeferredDeepLink();
if (destination) Linking.openURL(destination);
```

On Android, the destination comes from the Play install referrer, so it works after a fresh install from Google Play. On iOS, it is only set when a smart link opened the already-installed app on its first launch. See [Smart Links](https://docs.appeeky.com/docs/analytics-smart-links.md).

### `trialStarted()`

Raises the SKAdNetwork / AdAttributionKit conversion value to "trial started". Call it when a trial starts.

### `purchased(valueUsd)`

Raises the conversion value to the purchase bucket for this amount in USD. Call it after a purchase succeeds.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
Appeeky.purchased(29.99);
```

`trialStarted` and `purchased` only update the conversion value on iOS. Revenue itself comes from RevenueCat, so nothing is counted twice. See [SKAdNetwork](https://docs.appeeky.com/docs/analytics-skadnetwork.md) for the value schema.

### `flush()`

Sends queued events now. Returns a promise.

### `shutdown()`

Stops timers and app state listeners. Use it in tests, or before calling `init` again with a different key.

***

## Options

| Option | Default | Description |
| - | - | - |
| `key` | required | Publishable key (`apk_pub_…`) |
| `endpoint` | `https://ingest.appeeky.com/v1/ingest` | A self-hosted server's ingest URL, ending in `/v1/ingest` |
| `resolveAdServicesOnDevice` | `true` | Exchange the AdServices token with Apple from the device. The token is sent too, so the server can still try. |
| `getAdServicesToken` | native module | iOS: a function that returns the AdServices attribution token |
| `getInstallReferrer` | native module | Android: a function that returns the Play Install Referrer string |
| `flushIntervalMs` | `10000` | How often queued events are sent while the app is open |
| `flushAt` | `20` | Send as soon as this many events are queued |
| `maxQueueSize` | `1000` | The oldest events are dropped beyond this |
| `sessionTimeoutMs` | `1800000` (30 min) | Time in the background before a new session starts |
| `context` | | Override or fill in device context fields: `platform`, `appVersion`, `build`, `osVersion`, `deviceModel`, `locale` |
| `disabled` | `false` | Collect and send nothing, for example after the user opts out |
| `debug` | `false` | Log rejected batches and network errors |

Without the native module, you can supply the attribution callbacks yourself:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
Appeeky.init({
  key: "apk_pub_...",
  getAdServicesToken: Platform.OS === "ios" ? () => AdServices.getAttributionToken() : undefined,
  getInstallReferrer: Platform.OS === "android" ? getPlayInstallReferrer : undefined,
});
```

Attribution is collected once, on the first launch. Each callback has 3 seconds to answer.

***

## Automatic Events

| Event | When |
| - | - |
| `first_open` | First launch after install |
| `session_start` | Launch, or returning after `sessionTimeoutMs` in the background |
| `app_background` | Going to the background, with `foreground_ms`: time in the foreground since the app came to the foreground. Session time is the sum per session. |
| `identify` / `reset` | `identify(id)` / `identify(null)` |
| `screen` | Each `screen(name)` call |
| `ad_revenue` | Each `adRevenue(valueUsd, details)` call |

Sale events (`trial_started`, `purchase`, `trial_converted`, `renewal`, `refund`) do not come from the SDK. They come from RevenueCat. See [Revenue](https://docs.appeeky.com/docs/analytics-revenue.md).

The first time the app is opened, the SDK also reads the URL it was opened with (`Linking.getInitialURL()`) to detect [campaign links](https://docs.appeeky.com/docs/analytics-attribution.md).

***

## Sending and Retries

* Events are queued in AsyncStorage and sent in batches of up to 100.
* A batch is sent every `flushIntervalMs`, when `flushAt` events are queued, and when the app goes to the background.
* If the server is busy or the device is offline, the SDK keeps the batch and retries later. Each event has an id, so a retried batch is never counted twice.
* The server drops events older than 30 days, more than 10 minutes in the future (a wrong device clock or a very old offline queue), or with properties over 4 KB. The rest of the batch is kept.

***

## Related Docs

* [Quickstart](https://docs.appeeky.com/docs/analytics-quickstart.md)
* [Attribution](https://docs.appeeky.com/docs/analytics-attribution.md)
* [Privacy](https://docs.appeeky.com/docs/analytics-privacy.md)
* [Analytics API](https://docs.appeeky.com/docs/analytics-api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.