Documentation

SDKappsprint-react-native

React Native / Expo

Installation, configuration, event tracking, and full API reference for the React Native / Expo SDK.

Requirements

React Native 0.71+
React 18+
Node 20+

1. Install

GitHub package

npm install github:app-sprint/appsprint-react-native

# iOS only
cd ios && pod install

For Expo managed workflow, run npx expo prebuild after installing.

2. Configure

import { AppSprint } from 'appsprint-react-native';

// Call as early as possible — App.tsx, root layout, or _layout.tsx
await AppSprint.configure({
  apiKey: 'as_live_xxxxx',
});

The SDK auto-tracks the install on first launch, registers an AppState listener to flush events when backgrounding, and retries any queued events.

Configuration options

Option	Type	Default	Description
apiKey	string	—	Your live API key (starts with as_live_).
apiUrl	string	https://api.appsprint.app	Override the API base URL for testing.
enableAppleAdsAttribution	boolean	true	Fetch the AdServices attribution token on iOS. No effect on Android.
isDebug	boolean	false	Enable debug logging (sets logLevel to 0).
logLevel	0 \| 1 \| 2 \| 3	2 (WARN)	0 = DEBUG, 1 = INFO, 2 = WARN, 3 = ERROR.
customerUserId	string \| null	null	Set a customer user ID at initialization time.

3. Track events

// Standard event
await AppSprint.sendEvent('login');

// Revenue event
await AppSprint.sendEvent('purchase', null, {
  revenue: 9.99,
  currency: 'USD',
});

// Custom event with parameters
await AppSprint.sendEvent('custom', 'level_complete', {
  level: 5,
  score: 1200,
});

Supported event types

loginsign_upregisterpurchasesubscribestart_trialadd_to_cartadd_to_wishlistinitiate_checkoutview_contentview_itemsearchsharetutorial_completelevel_startlevel_completecustom

Use custom with a name parameter for any event not in this list.

4. Read attribution

After configure() completes, the SDK caches the attribution result from the install response. Access it synchronously:

const attr = AppSprint.getAttribution();
console.log(attr?.source);       // "apple_ads", "fingerprint", or "organic"
console.log(attr?.confidence);   // 0.0–1.0
console.log(attr?.campaignName); // Campaign name if available

Field	Description
source	"apple_ads", "fingerprint", or "organic"
confidence	Match confidence from 0.0 to 1.0
campaignName	Campaign name (if attributed to an ad)
utmSource	UTM source from the tracking link
utmMedium	UTM medium from the tracking link
utmCampaign	UTM campaign from the tracking link

API reference

configure(config)

→ Promise<void>

Initialize the SDK. Auto-tracks install on first launch. Registers AppState listener for background flush.

await AppSprint.configure({ apiKey: '…' })

sendEvent(type, name?, params?)

→ Promise<void>

Send an event. Queued automatically if offline or before install completes.

await AppSprint.sendEvent('purchase', null, { revenue: 9.99 })

type is a string literal — see event types below.

flush()

→ Promise<void>

Retry all queued events immediately. Safe to call multiple times.

await AppSprint.flush()

clearData()

→ Promise<void>

Clear all cached state (ID, attribution, queue, disabled flag). Removes AppState listener.

await AppSprint.clearData()

getAppSprintId()

→ string | null

Returns the install ID synchronously, or null before install tracking completes.

const id = AppSprint.getAppSprintId()

getAttribution()

→ AttributionResult | null

Returns cached attribution data from the install response.

const attr = AppSprint.getAttribution()

isInitialized()

→ boolean

True once configure() has completed. Does not guarantee appsprintId is available.

AppSprint.isInitialized()

isSdkDisabled()

→ Promise<boolean>

True if the API key was rejected (401/403). SDK drops all events when disabled.

await AppSprint.isSdkDisabled()

sendTestEvent()

→ Promise<{ success, message }>

Send a diagnostic event. Use to verify connectivity during development.

const result = await AppSprint.sendTestEvent()

setCustomerUserId(id)

→ Promise<void>

Attach your own user ID. Sent immediately if install is tracked, otherwise queued.

await AppSprint.setCustomerUserId('user-123')

enableAppleAdsAttribution()

→ Promise<void>

Re-enable Apple Ads attribution at runtime (if disabled in config).

await AppSprint.enableAppleAdsAttribution()

destroy()

Remove the AppState listener. Call on unmount if needed.

AppSprint.destroy()

Offline behavior

Events that fail to send are automatically queued in native storage (up to 100 events).
The queue persists across app restarts.
Queued events are retried automatically when configure() completes, when the app moves to the background, or when you call flush().
If a queued event receives a 401/403, the SDK disables itself and clears the queue.

Platform notes

On iOS, the SDK calls AdServices.AAAttribution.attributionToken() (iOS 14.3+) to detect Apple Search Ads installs. Falls back to iAd on older versions.
IDFA is only collected on iOS when the user grants ATT permission. Use NativeAppSprint.requestTrackingAuthorization() to prompt.
On Android, IDFA/IDFV are not available. Device fingerprinting uses model, screen, locale, timezone, and OS version.
Events are persisted to native storage (UserDefaults on iOS, SharedPreferences on Android) and survive app restarts. Max queue size is 100 events.
The AppState listener flushes the queue when the app moves to the background.

Integrations

Once the SDK is configured, connect revenue and ad-network integrations:

RevenueCat

Attribute subscriptions and purchases

Superwall

Attribute paywall conversions

Apple Search Ads

Campaign and keyword attribution

Troubleshooting

getAppSprintId() returns null

configure() is async — await it before reading the ID. The install network call must complete first.

Events not appearing in dashboard

Verify you are using a live API key (as_live_*), not a test key. Call sendTestEvent() and check the returned message.

SDK disabled (isSdkDisabled returns true)

The API returned 401 or 403, meaning your key is invalid. Call clearData(), then re-configure with a valid key.

Apple Ads attribution not detected

AdServices only works on real devices, not the simulator. Ensure enableAppleAdsAttribution is true (default).

pod install fails after adding the package

Delete ios/Podfile.lock and ios/Pods, then run pod install --repo-update.

Events sent offline never appear

Events queue to native storage and flush on next app launch or backgrounding. Verify the queue by calling flush() manually after reconnecting.

Connectivity test

const result = await AppSprint.sendTestEvent();
console.log(result.success, result.message);

Verification checklist

Create a blank Expo or bare React Native app and install the package.
Call configure() as early as possible in App.tsx or your root layout.
Verify getAppSprintId() returns a value after first launch.
Send login, purchase, and custom events — confirm in the dashboard.
Send an event offline, background the app, restore connectivity, relaunch — verify the event appears.
Call sendTestEvent() and confirm { success: true }.