SDK Reference

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.

import Appeeky from "@appeeky/analytics-react-native";

Install

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

{
  "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

{
  "expo": {
    "plugins": [["@appeeky/analytics-react-native", { "attributionEndpoint": false }]]
  }
}

An app can name only one endpoint. See SKAdNetwork.

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

Methods

`init(options)`

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

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.

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.

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.

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

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

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.

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`

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.

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.

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

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

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. The first time the app is opened, the SDK also reads the URL it was opened with (Linking.getInitialURL()) to detect campaign links.

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.

Getting Started

Attribution

Revenue

Dashboard

Privacy

API

Install

Config plugin

Native module

Methods

`init(options)`

`identify(userId)`

`screen(name, props?)`

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

`adRevenue(valueUsd, details?)`

`getDeferredDeepLink()`

`trialStarted()`

`purchased(valueUsd)`

`flush()`

`shutdown()`

Options

Automatic Events

Sending and Retries

​Install

​Config plugin

​Native module

​Methods

​init(options)

​identify(userId)

​screen(name, props?)

​track(name, props?, value?)

​adRevenue(valueUsd, details?)

​getDeferredDeepLink()

​trialStarted()

​purchased(valueUsd)

​flush()

​shutdown()

​Options

​Automatic Events

​Sending and Retries

​Related Docs

Install

Config plugin

Native module

Methods

`init(options)`

`identify(userId)`

`screen(name, props?)`

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

`adRevenue(valueUsd, details?)`

`getDeferredDeepLink()`

`trialStarted()`

`purchased(valueUsd)`

`flush()`

`shutdown()`

Options

Automatic Events

Sending and Retries

Related Docs