React Native API reference

Every public export of the react-native-appstack-sdk package. For installation and integration guidance, see the React Native SDK guide. Current stable release: 3.5.0, published 16 September 2026. See the changelog for everything that changed.

AppstackSDK

The default export is a ready-made singleton, so import it directly. Every method returns a promise.

import AppstackSDK, { EventType } from 'react-native-appstack-sdk';

A promise resolving does not mean the event reached Appstack. It means the call reached native. The native SDKs still drop events when disabled, offline, or buffering.

configure()

configure(apiKey: string, options?: AppstackConfigureOptions | null): Promise<boolean>

Starts the SDK. Call once, as early in app startup as possible. A repeat call is a no-op, and its customerUserId is ignored, so it cannot change the ID later. Use setCustomerUserId() for that.

string

required

Your app’s Appstack API key, from the dashboard under app settings.

AppstackConfigureOptions | null

default:"null"

Optional logLevel and customerUserId. See AppstackConfigureOptions.

Promise<boolean>

Resolves once configuration succeeds.

// Minimum
await AppstackSDK.configure('your_api_key');

// With options
await AppstackSDK.configure('your_api_key', {
  logLevel: 1,                  // 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR
  customerUserId: 'user_123',
});

setCustomerUserId()

setCustomerUserId(customerUserId?: string | null): Promise<void>

Sets your identifier for the signed-in user, after configure().

string

required

Your identifier for the signed-in user. Set it as soon as it is known, and at least one event has to follow for it to take effect.

Promise<void>

Resolves once native has stored the ID.

await AppstackSDK.setCustomerUserId('user_123');  // once login reveals it

sendEvent()

sendEvent(event: EventType | string, parameters?: AppstackEventParameters | null): Promise<void>

Sends a standard or custom event.

EventType | string

required

A standard EventType, whose string name also works case-insensitively, or any other string to send a custom event by that name.

AppstackEventParameters | null

default:"null"

Event properties. Keys valued null or undefined are stripped before the call reaches native, so both platforms observe the same map. For revenue events send revenue and currency. Matching parameters (email, name, phone_number, date_of_birth, gender) are encrypted before being used for attribution matching — on device on iOS 17+ and Android, and server-side on iOS 15–16. Names that must stay readable, such as currency and revenue, are excluded. See enhanced app campaigns.

Promise<void>

Resolves once the call reaches native. See the note above: this is not delivery confirmation.

// Standard event
await AppstackSDK.sendEvent(EventType.LOGIN);

// Revenue event
await AppstackSDK.sendEvent(EventType.PURCHASE, {
  revenue: 29.99,
  currency: 'USD',
});

// Custom event, pass any string as the name
await AppstackSDK.sendEvent('onboarding_finished', { variant: 'b' });

EventType.INSTALL is dropped by the wrapper before it reaches native. The SDK tracks installs itself; sending it by hand would double-count.

getAppstackId()

getAppstackId(): Promise<string>

Returns the stable local Appstack identity for this install.

Promise<string>

The install’s Appstack ID.

const appstackId = await AppstackSDK.getAppstackId();

isSdkDisabled()

isSdkDisabled(): Promise<boolean>

Whether the SDK is currently disabled and sending nothing.

Promise<boolean>

true when the SDK is disabled.

getAttributionParams()

getAttributionParams(): Promise<Record<string, any>>

Waits for the initial attribution match to finish, then resolves with the parameters. The match runs at most once per install, at configure time. Prefer this over a fixed delay after startup.

Promise<Record<string, any>>

Attribution parameters, always carrying the reserved appstack_match_status key.

`appstack_match_status`	Meaning
`matched`	The install is attributed and parameters are present.
`matched_no_params`	A click matched, but the link carried no recognised tracking parameters.
`organic`	Confirmed no attribution.
`skipped`	No match was attempted for this launch. Terminal for the life of the install.
`failed`	Attempted but unresolved (offline, timeout, or a server error). Retried in-session and next launch, so re-read rather than assuming organic.
`not_configured`	Read before `configure()` completed, or the SDK is disabled.

const params = await AppstackSDK.getAttributionParams();
if (params.appstack_match_status === 'matched') {
  // …
}

handleUniversalLink()

handleUniversalLink(url: string, options?: AppstackLinkOptions | null): Promise<AppstackLinkResult | null>

Parses an Appstack standard Universal Link or App Link delivered by React Native’s Linking API. No network round trip, because the URL carries everything.

string

required

The tapped link, as handed to you by Linking.getInitialURL() or the Linking 'url' event.

AppstackLinkOptions | null

default:"null"

Optional host filtering. See AppstackLinkOptions.

Promise<AppstackLinkResult | null>

The parsed link, or null when the URL is not a recognised Appstack link.

import { Linking } from 'react-native';

useEffect(() => {
  const handle = async (url: string) => {
    const link = await AppstackSDK.handleUniversalLink(url);
    if (link) navigate(link.deeplinkId, link.queryParams);
  };

  Linking.getInitialURL().then((url) => url && handle(url));
  const sub = Linking.addEventListener('url', ({ url }) => handle(url));
  return () => sub.remove();
}, []);

enableAppleAdsAttribution()

enableAppleAdsAttribution(): Promise<boolean>

Starts Apple Search Ads attribution. iOS 15.0+ only; a no-op on Android. Call it after the App Tracking Transparency prompt resolves.

Promise<boolean>

Resolves once configuration succeeds.

import { Platform } from 'react-native';

if (Platform.OS === 'ios') {
  await AppstackSDK.enableAppleAdsAttribution();
}

deleteUserData()

deleteUserData(): Promise<void>

Permanently deletes this install’s Appstack data, for GDPR and privacy requests.

Promise<void>

Resolves when deletion completes.

AppstackSDK.getInstance()

static getInstance(): AppstackSDK

Returns the singleton. The default export is already that instance, so you rarely need this. It exists for advanced use where the class itself is imported.

import { AppstackSDK } from 'react-native-appstack-sdk';

const sdk = AppstackSDK.getInstance();

Types

AppstackConfigureOptions

export interface AppstackConfigureOptions {
  logLevel?: number;
  customerUserId?: string | null;
}

number

default:"1"

Console verbosity, descending: 0 DEBUG, 1 INFO, 2 WARN, 3 ERROR. iOS has no dedicated WARN tier, so 2 folds to the same level as 3 there.

string | null

Your identifier for the signed-in user, when known at startup.

This numbering is the inverse of the native Swift LogLevel enum, where 0 is .off and higher means more verbose. The wrapper translates, so use the JS numbering above in React Native and ignore the native values.

AppstackLinkOptions

export interface AppstackLinkOptions {
  allowedHosts?: readonly string[];
}

readonly string[]

Exact branded hostnames to accept. When omitted, any non-shared branded host is accepted. Passing an empty array throws, because it matches no host and would turn every link into null. Omit the option instead.

AppstackLinkResult

export interface AppstackLinkResult {
  deeplinkId: string;
  queryParams: Record<string, string>;
  url: string;
}

string

The Appstack deep link ID.

Record<string, string>

Query parameters parsed off the tapped URL.

string

The URL that was handled.

EventType

export declare enum EventType

Standard attribution events. Values follow the SNAKE_CASE convention used by mobile measurement partners, and the value sent over the wire is the name itself, so EventType.ADD_TO_CART is "ADD_TO_CART". Where two names are synonymous, both are provided for compatibility with existing integrations.

Group	Cases
Lifecycle	`INSTALL`
Auth	`LOGIN`, `SIGN_UP`, `REGISTER`
Monetization	`PURCHASE`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `INITIATE_CHECKOUT`, `START_TRIAL`, `SUBSCRIBE`
Games	`LEVEL_START`, `LEVEL_COMPLETE`
Engagement	`TUTORIAL_COMPLETE`, `SEARCH`, `VIEW_ITEM`, `VIEW_CONTENT`, `SHARE`

There is no CUSTOM case. Pass any string to sendEvent() to send a custom event by that name.

AppstackEventParameters

export type AppstackEventParameters = Record<string, JsonValue | undefined>;

Parameters accepted by sendEvent(). Keys valued null or undefined are stripped before the call reaches native, so both platforms observe the same map.

JsonValue

export type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };

Any value that survives the React Native bridge intact. Event parameters are serialised to JSON on the way to native, so anything outside this set (a Date, a class instance, a function, an undefined nested inside an array) either arrives mangled or is dropped silently. Typing against JsonValue catches that at compile time.

AppstackSDKInterface

export interface AppstackSDKInterface

The interface AppstackSDK implements. Exported so you can type a mock or a wrapper of your own against the same surface.

Mobile SDKs

HTTP API

React Native API reference

AppstackSDK

configure()

setCustomerUserId()

sendEvent()

getAppstackId()

isSdkDisabled()

getAttributionParams()

handleUniversalLink()

enableAppleAdsAttribution()

deleteUserData()

AppstackSDK.getInstance()

Types

AppstackConfigureOptions

AppstackLinkOptions

AppstackLinkResult

EventType

AppstackEventParameters

JsonValue

AppstackSDKInterface

​AppstackSDK

​configure()

​setCustomerUserId()

​sendEvent()

​getAppstackId()

​isSdkDisabled()

​getAttributionParams()

​handleUniversalLink()

​enableAppleAdsAttribution()

​deleteUserData()

​AppstackSDK.getInstance()

​Types

​AppstackConfigureOptions

​AppstackLinkOptions

​AppstackLinkResult

​EventType

​AppstackEventParameters

​JsonValue

​AppstackSDKInterface

AppstackSDK

configure()

setCustomerUserId()

sendEvent()

getAppstackId()

isSdkDisabled()

getAttributionParams()

handleUniversalLink()

enableAppleAdsAttribution()

deleteUserData()

AppstackSDK.getInstance()

Types

AppstackConfigureOptions

AppstackLinkOptions

AppstackLinkResult

EventType

AppstackEventParameters

JsonValue

AppstackSDKInterface