AppEventsLogger

Log events and track user actions in your app

The AppEventsLogger module allows you to log app events for analytics, track purchases, and manage user data for Facebook’s event tracking system.

Import

import { AppEventsLogger } from 'react-native-fbsdk-next';

Methods

logEvent

Logs a custom app event with optional parameters and value.

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

eventName · string · required

The name of the event to log. Use predefined events from AppEventsLogger.AppEvents or custom event names.

valueToSum · number

Optional numeric value to associate with the event for aggregation.

parameters · Params

Optional key-value pairs containing additional event data. Use predefined parameter keys from AppEventsLogger.AppEventParams.

Usage Examples:

// Simple event
AppEventsLogger.logEvent('Clicked Button');

// Event with value
AppEventsLogger.logEvent('Viewed Item', 99.99);

// Event with parameters
AppEventsLogger.logEvent('Viewed Content', {
  [AppEventsLogger.AppEventParams.ContentType]: 'product',
  [AppEventsLogger.AppEventParams.ContentID]: 'SKU123',
});

// Event with value and parameters
AppEventsLogger.logEvent('Added to Cart', 49.99, {
  [AppEventsLogger.AppEventParams.Currency]: 'USD',
  [AppEventsLogger.AppEventParams.NumItems]: 1,
});

logPurchase

Logs a purchase event with amount and currency.

AppEventsLogger.logPurchase(
  purchaseAmount: number,
  currencyCode: string,
  parameters?: Params
): void

purchaseAmount · number · required

The amount of the purchase.

currencyCode · string · required

The ISO 4217 currency code (e.g., “USD”, “EUR”, “GBP”).

parameters · Params

Optional additional parameters for the purchase event.

Example:

AppEventsLogger.logPurchase(29.99, 'USD', {
  [AppEventsLogger.AppEventParams.NumItems]: 2,
  [AppEventsLogger.AppEventParams.ContentType]: 'product',
});

logPushNotificationOpen

Logs that the app was opened via a push notification.

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

payload · Record<string, string | number>

Optional payload data from the push notification.

Example:

AppEventsLogger.logPushNotificationOpen({
  campaign: 'summer_sale',
  source: 'firebase',
});

logProductItem

Uploads a product catalog item as an app event.

AppEventsLogger.logProductItem(
  itemID: string,
  availability: ProductAvailability,
  condition: ProductCondition,
  description: string,
  imageLink: string,
  link: string,
  title: string,
  priceAmount: number,
  currency: string,
  gtin?: string,
  mpn?: string,
  brand?: string,
  parameters?: Params
): void

itemID · string · required

Unique identifier for the product. Maximum 100 characters.

availability · ProductAvailability · required

Product availability: 'in_stock', 'out_of_stock', 'preorder', 'avaliable_for_order', or 'discontinued'.

condition · ProductCondition · required

Product condition: 'new', 'refurbished', or 'used'.

description · string · required

Product description. Maximum 5000 characters.

imageLink · string · required

URL to the product image.

link · string · required

URL to the product page on your website.

title · string · required

Product title.

priceAmount · number · required

Product price (rounded to thousandths place).

currency · string · required

ISO 4217 currency code.

gtin · string

Global Trade Item Number (UPC, EAN, JAN, ISBN).

mpn · string

Manufacturer Part Number.

brand · string

Brand name.

parameters · Params

Additional parameters for deep linking.

At least one of gtin, mpn, or brand must be provided.

Example:

AppEventsLogger.logProductItem(
  'SKU-12345',
  'in_stock',
  'new',
  'Premium Wireless Headphones with Noise Cancellation',
  'https://example.com/images/headphones.jpg',
  'https://example.com/products/headphones',
  'Premium Headphones',
  149.99,
  'USD',
  undefined,
  undefined,
  'AudioBrand'
);

setUserID

Sets a custom user ID to associate with all app events.

AppEventsLogger.setUserID(userID: string | null): void

userID · string | null · required

The user ID to set, or null to clear the current user ID.

Example:

// Set user ID
AppEventsLogger.setUserID('user_12345');

// Clear user ID
AppEventsLogger.setUserID(null);

getUserID

Returns the currently set user ID.

AppEventsLogger.getUserID(): Promise<string | null>

Example:

const userID = await AppEventsLogger.getUserID();
console.log('Current user ID:', userID);

getAnonymousID

Returns the anonymous ID for the current app installation.

AppEventsLogger.getAnonymousID(): Promise<string | null>

Example:

const anonymousID = await AppEventsLogger.getAnonymousID();

getAdvertiserID

Returns the advertiser ID (IDFA on iOS, Advertising ID on Android).

AppEventsLogger.getAdvertiserID(): Promise<string | null>

Example:

const advertiserID = await AppEventsLogger.getAdvertiserID();

getAttributionID

Returns the attribution ID. Android only.

AppEventsLogger.getAttributionID(): Promise<string | null>

This method returns null on iOS.

Example:

if (Platform.OS === 'android') {
  const attributionID = await AppEventsLogger.getAttributionID();
}

setUserData

Sets additional user data to improve ad targeting and measurement.

AppEventsLogger.setUserData(userData: UserData): void

userData · UserData · required

User information for advanced matching. See Advanced Matching for field format details.

Example:

AppEventsLogger.setUserData({
  email: '[e-mail]',
  firstName: 'John',
  lastName: 'Doe',
  phone: '[phone]',
  city: 'San Francisco',
  state: 'CA',
  zip: '94103',
  country: 'US',
});

setFlushBehavior

Controls when events are sent to Facebook servers.

AppEventsLogger.setFlushBehavior(flushBehavior: AppEventsFlushBehavior): void

flushBehavior · AppEventsFlushBehavior · required

Either 'auto' (default: flush every 15 seconds or 100 events) or 'explicit_only' (only flush when flush() is called).

Example:

// Explicit flushing only
AppEventsLogger.setFlushBehavior('explicit_only');

flush

Manually triggers sending queued events to Facebook servers.

AppEventsLogger.flush(): void

Example:

AppEventsLogger.flush();

setPushNotificationsDeviceToken

Registers the device token for push notifications. iOS only.

AppEventsLogger.setPushNotificationsDeviceToken(deviceToken: string): void

deviceToken · string · required

The APNs device token.

Example:

if (Platform.OS === 'ios') {
  AppEventsLogger.setPushNotificationsDeviceToken(deviceToken);
}

setPushNotificationsRegistrationId

Registers the registration ID for push notifications. Android only.

AppEventsLogger.setPushNotificationsRegistrationId(registrationId: string): void

registrationId · string · required

The FCM registration ID.

Example:

if (Platform.OS === 'android') {
  AppEventsLogger.setPushNotificationsRegistrationId(registrationId);
}

clearUserID

Deprecated. Use setUserID(null) instead.

Clears the currently set user ID.

AppEventsLogger.clearUserID(): void

Constants

AppEvents

Predefined event names for common app actions:

const AppEvents: {
  AchievedLevel: string;
  AdClick: string;
  AdImpression: string;
  AddedPaymentInfo: string;
  AddedToCart: string;
  AddedToWishlist: string;
  CompletedRegistration: string;
  CompletedTutorial: string;
  Contact: string;
  CustomizeProduct: string;
  Donate: string;
  FindLocation: string;
  InitiatedCheckout: string;
  Purchased: string;
  Rated: string;
  Searched: string;
  SpentCredits: string;
  Schedule: string;
  StartTrial: string;
  SubmitApplication: string;
  Subscribe: string;
  UnlockedAchievement: string;
  ViewedContent: string;
}

Example:

AppEventsLogger.logEvent(AppEventsLogger.AppEvents.CompletedRegistration);

AppEventParams

Predefined parameter keys for event data:

const AppEventParams: {
  AddType: string;
  Content: string;
  ContentID: string;
  ContentType: string;
  Currency: string;
  Description: string;
  Level: string;
  NumItems: string;
  MaxRatingValue: string;
  OrderId: string;
  PaymentInfoAvailable: string;
  RegistrationMethod: string;
  SearchString: string;
  Success: string;
  ValueNo: string;
  ValueYes: string;
}

Example:

AppEventsLogger.logEvent(AppEventsLogger.AppEvents.ViewedContent, {
  [AppEventsLogger.AppEventParams.ContentType]: 'product',
  [AppEventsLogger.AppEventParams.ContentID]: 'SKU123',
  [AppEventsLogger.AppEventParams.Currency]: 'USD',
});

TypeScript 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';

ProductAvailability

type ProductAvailability =
  | 'in_stock'
  | 'out_of_stock'
  | 'preorder'
  | 'avaliable_for_order'
  | 'discontinued';

ProductCondition

type ProductCondition = 'new' | 'refurbished' | 'used';