Skip to main content

API Reference

All functions are named exports of expo-facebook-analytics.

Initialization & runtime configuration​

initialize(): void​

Initializes the Facebook SDK from JavaScript. Required when isAutoInitEnabled is false: nothing else starts the SDK then. (On iOS there has been no auto-init since SDK 9, so the plugin's AppDelegate wiring is the only other path.) Safe to call once; call it before logging events.

setAutoInitEnabled(enabled: boolean): void​

Turns the native SDK's auto-init flag on or off at runtime. initialize() switches it on and Android persists it, so a consent-gated app should call setAutoInitEnabled(false) when consent is withdrawn — otherwise the next launch initializes the SDK before JavaScript runs. No-op on iOS.

setAutoLogAppEventsEnabled(enabled: boolean): void​

Enables or disables automatic app-event logging at runtime.

setAdvertiserIDCollectionEnabled(enabled: boolean): void​

Enables or disables advertiser-ID (IDFA / AAID) collection at runtime.

setAppID(appID: string): void​

Sets the Facebook App ID at runtime. Call before initialize().

setClientToken(clientToken: string): void​

Sets the Facebook Client Token at runtime. Call before initialize().

setLoggingEnabled(enabled: boolean): void​

Enables verbose Facebook SDK logging (app events, network requests, developer errors). Output is printed to the native console — view it with xcrun simctl spawn booted log stream (iOS) or adb logcat (Android). The example app exposes bun run logs:ios / bun run logs:android for this. Development only.

Event logging​

activateApp(): void​

Logs an app activation: publishes the install event (with the Google Play install referrer on Android) the first time it runs on a device, then the launch event. The SDK only does this on its own when automatic event logging is on, so call it once per launch after initialize() whenever autoLogAppEventsEnabled is false — without it Meta cannot attribute installs to your ads.

logEvent(eventName: string, ...args: Array<number | Params>): void​

Logs a custom or predefined event. The variadic args accept an optional numeric valueToSum and/or a Params object, in any order.

logEvent("level_complete");
logEvent("level_complete", 5);
logEvent("level_complete", 5, { level: "3" });

logPurchase(amount: number, currency: string, params?: Params): void​

Logs a purchase with an amount and ISO currency code.

logPushNotificationOpen(payload?: Record<string, string | number>): void​

Logs that the app was opened from a push notification.

User identity​

setUserID(userID: string | null): void​

Sets the user ID associated with events. Passing null clears it.

clearUserID(): void​

Clears the current user ID.

getUserID(): string | undefined​

Returns the current user ID, if set.

setUserData(data: UserData): void​

Sets hashed user data for advanced matching. See UserData.

Device identifiers​

getAnonymousID(): Promise<string | undefined>​

Resolves with the anonymous device GUID.

getAdvertiserID(): Promise<string | undefined>​

Resolves with the advertiser ID — IDFA on iOS, AAID on Android. Returns undefined when unavailable (e.g. limit-ad-tracking enabled). Runs off the JS thread.

Configuration​

setFlushBehavior(behavior: AppEventsFlushBehavior): void​

Sets event-flush behavior: 'auto' (default) or 'explicit_only'.

flush(): void​

Flushes all queued events to Facebook immediately.

setPushNotificationsDeviceToken(token: string): void​

Sets the APNs device token (iOS). Pass the token as a hex string.

setPushNotificationsRegistrationId(registrationId: string): void​

Sets the FCM registration ID (Android).

Types​

Params​

type Params = { [key: string]: string | number };

UserData​

type UserData = Readonly<{
email?: string;
firstName?: string;
lastName?: string;
phone?: string;
dateOfBirth?: string;
gender?: "m" | "f";
city?: string;
state?: string;
zip?: string;
country?: string;
}>;

AppEventsFlushBehavior​

type AppEventsFlushBehavior = "auto" | "explicit_only";