Analytics

Analytics: getAnalytics/logEvent, predefined log* helpers and EventParameters types, setUserId/setUserProperties, setDefaultEventParameters, consent and collection toggles, app/session IDs, screen tracking, IDFA opt-out, on-device conversion measurement, and DebugView setup.

Prerequisites

  • @react-native-firebase/app installed and native config completed per Getting Started (Android google-services.json, iOS GoogleService-Info.plist, Expo config plugin, or React Native CLI setup). From v26, New Architecture is required for packages with a native bridge.
  • Install Analytics: npm install --save @react-native-firebase/analytics or yarn add @react-native-firebase/analytics, then rebuild native apps (cd ios && pod install on iOS).
  • Enable Google Analytics for your Firebase project in the Firebase Console. Analytics supports only the default Firebase app.

Example Expo Router screen: https://github.com/invertase/react-native-firebase/blob/main/test-expo/app/analytics.tsx

Installation

This module requires that the @react-native-firebase/app module is already setup and installed. To install the "app" module, view the Getting Started documentation.

bash
# Install & setup the app module
yarn add @react-native-firebase/app

# Install the analytics module
yarn add @react-native-firebase/analytics

# If you're developing your app using iOS, run this command
cd ios/ && pod install

Platform support and New Architecture

{/* prettier-ignore */}

PlatformsAndroid, iOS (native Firebase SDK)
New ArchitectureRequired from v26. See Migrating to v26.

Platform notes: On-device conversion measurement helpers (initiateOnDeviceConversionMeasurementWithEmailAddress, initiateOnDeviceConversionMeasurementWithHashedEmailAddress, initiateOnDeviceConversionMeasurementWithPhoneNumber, initiateOnDeviceConversionMeasurementWithHashedPhoneNumber) are iOS only; on Android and web the JS layer resolves without calling native (no-op). logTransaction (verified iOS in-app purchase events) is iOS only and rejects on other platforms. getGoogleAnalyticsClientId is web-only and rejects on iOS/Android. settings is a web Google Analytics tagging helper and is a no-op on React Native. Analytics supports only the default Firebase app. React Native Firebase also exports SDK_VERSION, predefined log* convenience methods with matching *EventParameters / *Parameters types (including ScreenViewParameters), setUserProperty, getAppInstanceId, getSessionId, setSessionTimeoutDuration, and resetAnalyticsData. The package type declarations also contain a legacy Statics interface that the entry point does not export. Each export is explained in the section that uses it.

What does it do

Analytics collects usage and behavior data for your app. Its two primary concerns are:

  • Events: What is happening in your app, such as user actions, system events, or errors.
  • User properties: Attributes you define to describe segments of your user base, such as language preference or geographic location.

Analytics automatically logs some events and user properties; you don't need to add any code to enable them. However, Analytics also allows you to log custom or predefined events within your app. How you can do this will be explained below.

Usage

Analytics offers a wealth of Predefined Events to track user behavior. Analytics also offers folks the ability to log Custom Events. If you're already familiar with Google Analytics, this method is equivalent to using the event command in gtag.js.

Get an Analytics instance

getAnalytics returns the Analytics instance for the default Firebase app. initializeAnalytics(app, options) is provided for firebase-js-sdk API parity; on React Native Firebase it returns the same instance as getAnalytics(app) and ignores web-only AnalyticsSettings. isSupported() always resolves true on React Native (on web the firebase-js-sdk checks browser cookies/IndexedDB).

js
import { getApp } from '@react-native-firebase/app';
import { getAnalytics, initializeAnalytics, isSupported } from '@react-native-firebase/analytics';

async function prepareAnalytics() {
  const supported = await isSupported();
  console.log('Analytics supported:', supported);

  const analytics = getAnalytics();
  const sameInstance = initializeAnalytics(getApp());
  console.log('Default app name:', analytics.app.name);
  console.log('Same instance as getAnalytics:', sameInstance === analytics);
}

settings configures custom Google Analytics tagging function and data-layer names for web apps that load the Google tag script independently of Firebase. On the web it must be called before getAnalytics. On React Native Firebase it does nothing, so you can keep the call in code shared with web:

js
import { settings } from '@react-native-firebase/analytics';

settings({ gtagName: 'ga', dataLayerName: 'dataLayer' });

getGoogleAnalyticsClientId is web-only. On iOS and Android the returned promise rejects with an error.

js
import { getAnalytics, getGoogleAnalyticsClientId } from '@react-native-firebase/analytics';

async function readWebClientId() {
  // WARNING: getGoogleAnalyticsClientId rejects on iOS and Android (web-only).
  const clientId = await getGoogleAnalyticsClientId(getAnalytics());
  console.log('Google Analytics client id:', clientId);
}

Event Parameters

Pay close attention to the parameters you send with any event, whether custom or predefined.

WARNING The parameters you pass to logEvent are not checked by React Native Firebase. Invalid parameters can be accepted without an error and still fail to appear in the Analytics console.

The predefined helpers (logPurchase, logAddToCart, and the others listed under Predefined Events) check their parameters before logging:

  • In development builds (__DEV__) a helper throws when a parameter has the wrong type or a required parameter is missing. Most helpers also throw on a parameter they do not define; logBeginCheckout, logPurchase, logScreenView and logSetCheckoutOption accept extra parameters. Release builds skip this check.
  • The helpers that accept both value and currency (logAddPaymentInfo, logAddShippingInfo, logAddToCart, logAddToWishlist, logBeginCheckout, logGenerateLead, logPurchase, logRefund, logRemoveFromCart, logViewCart, logViewItem) throw in every build when you pass only one of the two.

Different event types require different parameters (some require no parameters, some require an array of items, most require a string or number). Check the reference for each event, and watch device logs and the Analytics console to confirm events are logged correctly.

Custom Events

logEvent logs an event by name with an optional parameters object. Primitive values and arrays of primitive values are logged to your Analytics console. Event names are case-sensitive, and you can log up to 500 distinct event types in an app. Register custom parameters as custom definitions in the Firebase console to see them in reports.

Modular logEvent returns void, as in the firebase-js-sdk, so there is nothing to await. It throws synchronously when the name is not valid (see Reserved Events).

jsx
import React from 'react';
import { View, Button } from 'react-native';
import { getAnalytics, logEvent } from '@react-native-firebase/analytics';

function App() {
  return (
    <View>
      <Button
        title="Add To Basket"
        onPress={() =>
          logEvent(getAnalytics(), 'basket', {
            id: 3745092,
            item: 'mens grey t-shirt',
            description: ['round neck', 'long sleeved'],
            size: 'L',
          })
        }
      />
    </View>
  );
}

Predefined Events

To help you get started, Analytics provides a number of event methods that are common among different types of apps, including retail and e-commerce, travel, and gaming apps. To learn more about these events and when to use them, browse the Events and properties articles in the Firebase Help Center.

React Native Firebase exports typed convenience helpers (the firebase-js-sdk modular API uses logEvent overloads instead). Each helper accepts a matching parameters interface re-exported for typed logEvent overloads and convenience methods:

  • logAddPaymentInfo / AddPaymentInfoEventParameters
  • logAddShippingInfo / AddShippingInfoParameters (also AddShippingInfoEventParameters for the parallel event-parameter naming)
  • logAddToCart / AddToCartEventParameters
  • logAddToWishlist / AddToWishlistEventParameters
  • logAppOpen (no parameters)
  • logBeginCheckout / BeginCheckoutEventParameters
  • logCampaignDetails / CampaignDetailsEventParameters
  • logEarnVirtualCurrency / EarnVirtualCurrencyEventParameters
  • logGenerateLead / GenerateLeadEventParameters
  • logJoinGroup / JoinGroupEventParameters
  • logLevelEnd / LevelEndEventParameters
  • logLevelStart / LevelStartEventParameters
  • logLevelUp / LevelUpEventParameters
  • logLogin / LoginEventParameters
  • logPostScore / PostScoreEventParameters
  • logSelectContent / SelectContentEventParameters
  • logPurchase / PurchaseEventParameters
  • logRefund / RefundEventParameters
  • logRemoveFromCart / RemoveFromCartEventParameters
  • logSearch / SearchEventParameters
  • logSelectItem / SelectItemEventParameters
  • logSetCheckoutOption / SetCheckoutOptionEventParameters
  • logSelectPromotion / SelectPromotionEventParameters
  • logShare / ShareEventParameters
  • logSignUp / SignUpEventParameters
  • logSpendVirtualCurrency / SpendVirtualCurrencyEventParameters
  • logTutorialBegin / logTutorialComplete (no parameters)
  • logUnlockAchievement / UnlockAchievementEventParameters
  • logViewCart / ViewCartEventParameters
  • logViewItem / ViewItemEventParameters
  • logViewItemList / ViewItemListEventParameters
  • logViewPromotion / ViewPromotionEventParameters
  • logViewSearchResults / ViewSearchResultsParameters
  • logScreenView / ScreenViewParameters (see Screen Tracking)
  • logTransaction (iOS 15.0 and later only; takes a transaction id string and rejects on Android/web)

Below is a sample of how to use one of the predefined methods the Analytics module provides for you:

jsx
import React from 'react';
import { View, Button } from 'react-native';
import { getAnalytics, logSelectContent } from '@react-native-firebase/analytics';

function App() {
  return (
    <View>
      <Button
        title="Press me"
        onPress={async () =>
          await logSelectContent(getAnalytics(), {
            content_type: 'clothing',
            item_id: 'abcd',
          })
        }
      />
    </View>
  );
}

Purchase events use logPurchase with PurchaseEventParameters:

js
import { getAnalytics, logPurchase } from '@react-native-firebase/analytics';

async function logShirtPurchase() {
  await logPurchase(getAnalytics(), {
    value: 19.99,
    currency: 'USD',
    items: [
      {
        item_id: 'sku-grey-tee',
        item_name: 'mens grey t-shirt',
        item_category: 'clothing',
        quantity: 1,
        price: 19.99,
      },
    ],
  });
}

logTransaction logs a verified iOS in-app purchase transaction id. It rejects on non-iOS platforms, and on iOS versions older than 15.0:

js
import { getAnalytics, logTransaction } from '@react-native-firebase/analytics';

async function logIosPurchase(transactionId) {
  // WARNING: logTransaction rejects on Android and web (iOS only).
  await logTransaction(getAnalytics(), transactionId);
}

For a full reference to predefined events and expected parameters, please check out the reference API.

Reserved Events

The Analytics package works out of the box, however a number of events are automatically reported to Firebase. These event names are called 'Reserved Events'. Calling logEvent with any of the following event names throws an error. logEvent also throws for names that start with the reserved prefixes firebase_, google_ or ga_, and for names that do not start with a letter or that contain characters other than letters, digits and underscores. A name can be 1 to 40 characters long.

{/* prettier-ignore */}

Reserved Events Names
ad_activeviewad_clickad_exposure
ad_queryad_rewardadunit_exposure
app_backgroundapp_clear_dataapp_remove
app_store_refundapp_store_subscription_cancelapp_store_subscription_convert
app_store_subscription_renewapp_updateapp_upgrade
dynamic_link_app_opendynamic_link_app_updatedynamic_link_first_open
errorfirst_openfirst_visit
in_app_purchasenotification_dismissnotification_foreground
notification_opennotification_receiveos_update
session_startsession_start_with_rolloutuser_engagement

User ID

Use setUserId to attach a stable app-scoped user id to subsequent events (for example when joining Analytics data in BigQuery across devices). Pass null to clear it. Do not use personally identifiable information as the id.

js
import { getAnalytics, setUserId } from '@react-native-firebase/analytics';

async function identifyUser(userId) {
  await setUserId(getAnalytics(), userId);
}

async function clearUserId() {
  await setUserId(getAnalytics(), null);
}

User properties

Set attributes that describe segments of your user base with setUserProperty (single key) or setUserProperties (object map). Register custom definitions in the Firebase console so the properties appear in reports. Reserved Google names such as Age, Gender, and Interest cannot be used.

js
import { getAnalytics, setUserProperty, setUserProperties } from '@react-native-firebase/analytics';

async function setFavoriteFood(food) {
  await setUserProperty(getAnalytics(), 'favorite_food', food);
}

async function setProfileProperties() {
  await setUserProperties(getAnalytics(), {
    favorite_food: 'apples',
    preferred_shop: 'downtown',
  });
}

Default event parameters

setDefaultEventParameters attaches parameters to every future event logged from the SDK (including automatic ones). A parameter you pass to an individual event overrides the default with the same name. As with custom event parameters, register default parameters as custom definitions in the Firebase console to see them in reports. The params argument is an object, null, or omitted.

js
import { getAnalytics, setDefaultEventParameters } from '@react-native-firebase/analytics';

async function attachCampaignDefaults() {
  await setDefaultEventParameters(getAnalytics(), {
    campaign: 'spring_launch',
    source: 'docs_example',
  });
}

App instance id

Below is an example showing how to retrieve the app instance id of the application. The native SDKs return null on Android if FirebaseAnalytics.ConsentType.ANALYTICS_STORAGE has been set to FirebaseAnalytics.ConsentStatus.DENIED and on iOS if ConsentType.analyticsStorage has been set to ConsentStatus.denied. In React Native Firebase, set that consent with setConsent (see Consent).

js
import { getAnalytics, getAppInstanceId } from '@react-native-firebase/analytics';

async function readAppInstanceId() {
  const appInstanceId = await getAppInstanceId(getAnalytics());
  console.log('App instance id:', appInstanceId);
}

Web / Other platform instance id

Ensure you have installed an Async Storage provider for Firebase to preserve the instance id. Failure to do so means the instance id will be reset every time the application terminates.

The main documentation for "other platform" support contains an example.

Session id and timeout

getSessionId returns the current Analytics session id as a number, or null when it is unavailable. On iOS it resolves null when the Firebase SDK reports an error or does not call back within 60 seconds.

js
import { getAnalytics, getSessionId } from '@react-native-firebase/analytics';

async function readSessionId() {
  const sessionId = await getSessionId(getAnalytics());
  console.log('Session id:', sessionId);
}

setSessionTimeoutDuration sets the duration of inactivity, in milliseconds, that ends the current session. The default is 1800000 (30 minutes). It throws unless the value is a finite number that is not negative.

js
import { getAnalytics, setSessionTimeoutDuration } from '@react-native-firebase/analytics';

async function useCustomSessionTimeout() {
  await setSessionTimeoutDuration(getAnalytics(), 1_800_000);
}

Reset analytics data

resetAnalyticsData clears Analytics data for this app on this device and resets the app instance id.

js
import { getAnalytics, resetAnalyticsData } from '@react-native-firebase/analytics';

async function wipeLocalAnalytics() {
  await resetAnalyticsData(getAnalytics());
}

Consent

setConsent updates the end-user consent state for Analytics. Pass only the keys you want to change. The native SDKs apply analytics_storage, ad_storage, ad_user_data and ad_personalization, each as a boolean (true grants, false denies). The ConsentSettings type also lists functionality_storage, personalization_storage and security_storage ('granted' or 'denied'); the Android and iOS code in React Native Firebase does not read those three keys. setConsent throws when a value has the wrong type or when the argument is not an object. Set the default consent state at build time with the analytics_default_allow_* keys described in JSON Config.

js
import { getAnalytics, setConsent } from '@react-native-firebase/analytics';

async function grantAnalyticsConsent() {
  await setConsent(getAnalytics(), {
    analytics_storage: true,
    ad_storage: true,
    ad_user_data: true,
    ad_personalization: true,
  });
}

async function denyAdConsent() {
  await setConsent(getAnalytics(), {
    ad_storage: false,
    ad_user_data: false,
    ad_personalization: false,
  });
}

Screen tracking

React Native apps usually need manual screen_view logging. Use logScreenView with ScreenViewParameters (screen_name, screen_class). See the dedicated Screen Tracking page for React Navigation and React Native Navigation wiring.

Disable Ad Id usage on iOS

Apple has a strict ban on the usage of Ad Ids ("IDFA") in Kids Category apps. They will not accept any app in the Kids category if the app accesses the IDFA iOS symbols.

Additionally, apps must implement Apples "App Tracking Transparency" (or "ATT") requirements if they access IDFA symbols. However, if an app does not use IDFA and otherwise handles data in an ATT-compatible way, it eliminates this ATT requirement.

If you need to avoid IDFA usage while still using analytics, define the following variable in your Podfile:

ruby
$RNFirebaseAnalyticsWithoutAdIdSupport = true

During pod install, using that variable links the FirebaseAnalyticsCore Swift Package Manager product instead of FirebaseAnalytics, so you may use Firebase Analytics in Kids Category apps, or Firebase Analytics without needing the App Tracking Transparency handling (assuming no other parts of your app handle data in a way that requires ATT)

Note that for obvious reasons, configuring Firebase Analytics for use without IDFA is incompatible with AdMob

Google Analytics on-device conversion measurement

If you would like to enable Google Analytics on-device conversion measurement APIs on iOS, define the following variable in your Podfile:

ruby
$RNFirebaseAnalyticsGoogleAppMeasurementOnDeviceConversion = true

During pod install, using that variable adds the GoogleAdsOnDeviceConversion Swift package.

If you use Expo, including EAS Build, add the Analytics config plugin to your app.json / app.config.js instead of editing the generated Podfile manually:

json
[
  "@react-native-firebase/analytics",
  {
    "ios": {
      "googleAppMeasurementOnDeviceConversion": true
    }
  }
]

This adds $RNFirebaseAnalyticsGoogleAppMeasurementOnDeviceConversion = true to the generated iOS Podfile during prebuild.

After the native dependency is linked, call the measurement helpers with an email, phone number, or SHA-256 hex hash. On Android and web these promises resolve without calling native (no-op). Hashed helpers expect a 64-character hex digest of the normalized credential.

js
import {
  getAnalytics,
  initiateOnDeviceConversionMeasurementWithEmailAddress,
  initiateOnDeviceConversionMeasurementWithHashedEmailAddress,
  initiateOnDeviceConversionMeasurementWithPhoneNumber,
  initiateOnDeviceConversionMeasurementWithHashedPhoneNumber,
} from '@react-native-firebase/analytics';

async function startOnDeviceConversion() {
  const analytics = getAnalytics();

  await initiateOnDeviceConversionMeasurementWithEmailAddress(analytics, 'user@example.com');
  await initiateOnDeviceConversionMeasurementWithPhoneNumber(analytics, '+15555550100');

  // Example 64-character SHA-256 hex digests (replace with real hashes of normalized values).
  await initiateOnDeviceConversionMeasurementWithHashedEmailAddress(
    analytics,
    '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
  );
  await initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(
    analytics,
    '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
  );
}

Device Identification

If you would like to enable Firebase Analytics to generate automatic audience metrics for iOS (as it does by default in Android), you must link additional iOS libraries, as documented by the Google Firebase team. Specifically you need to link in AdSupport.framework.

To do this, add this variable to your Podfile so @react-native-firebase/analytics will link it in for you:

ruby
$RNFirebaseAnalyticsEnableAdSupport = true

Note: this setting will have no effect if you disabled Ad IDs as described above, since this setting is specifically linking in the AdSupport framework which requires the Ad IDs.

firebase.json

Disable Auto-Initialization

Analytics can be further configured to disable auto collection of Analytics data. This is useful for opt-in-first data flows, for example when dealing with GDPR compliance. This is possible by setting the below noted property on the firebase.json file at the root of your project directory.

json
{
  "react-native": {
    "analytics_auto_collection_enabled": false
  }
}

To re-enable analytics (e.g. once you have the users consent), call the setAnalyticsCollectionEnabled method:

js
import { getAnalytics, setAnalyticsCollectionEnabled } from '@react-native-firebase/analytics';

async function enableCollectionAfterConsent() {
  await setAnalyticsCollectionEnabled(getAnalytics(), true);
}

To update the user's consent once you have it, call setConsent (see Consent).

Other Analytics keys in firebase.json (analytics_collection_deactivated, analytics_idfv_collection_enabled, google_analytics_adid_collection_enabled, google_analytics_ssaid_collection_enabled, google_analytics_registration_with_ad_network_enabled and the four analytics_default_allow_* consent defaults) are described in JSON Config. Rebuild the native app after changing any of them.

Disable screenview tracking

Analytics automatically tracks some information about screens in your application, such as the class name of the UIViewController or Activity that is in focus. Automatic screenview reporting can be turned off/on through google_analytics_automatic_screen_reporting_enabled property of firebase.json file.

json
{
  "react-native": {
    "google_analytics_automatic_screen_reporting_enabled": false
  }
}

Seeing Events in Firebase Console Realtime View or Analytics DebugView

Events show in the Firebase Console Realtime View within a few seconds of your app sending the events. This is an easy way to verify your events implementation as you develop your application.

However, the Realtime View on Firebase Console offers no way to filter to a specific stream of events so after your app launches your development events will be mixed with all events from your app.

To examine just your development events you will need to use the Analytics DebugView available on the main Google Analytics site for your app as documented in the "Monitor the events in DebugView" section of the Google Analytics documentation

Analytics events only show up in DebugView if marked correctly. Follow the instructions below for each platform to mark your events as Debug events.

iOS

Analytics batches events and uploads them roughly once an hour. To see events in DebugView with minimal delay, enable debug mode by adding the command line argument -FIRDebugEnabled in Xcode (see DebugView). Debug mode stays on until you launch with -FIRDebugDisabled.

To always set the flag when running debug builds of your app, you can edit your scheme in Xcode and add the argument under "Arguments Passed On Launch".

Android

Analytics batches events and uploads them roughly once an hour. To see events in DebugView with minimal delay, run adb shell setprop debug.firebase.analytics.app <package-name> in a terminal, where <package-name> is your app's package name. Debug mode stays on until you run adb shell setprop debug.firebase.analytics.app .none..

Other / Web

To mark your events as "Debug" events for platforms using react-native-firebase "other" platform support, you need to set the global debug flag globalThis.RNFBDebug to true then reload the app.

This toggle must be set to the value you want before accessing the analytics instance for the first time, so you should do it as early in your app's bootstrap sequence as possible.

For example, you might modify your index.js file like so:

javascript
// codeblock-ignore: imports the app's own ./App and ./app.json
/**
 * @format
 */

import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';

if (__DEV__) {
  globalThis.RNFBDebug = true;
}

AppRegistry.registerComponent(appName, () => App);

Package version

SDK_VERSION is the React Native Firebase Analytics package version string exported from @react-native-firebase/analytics. The firebase-js-sdk does not export SDK_VERSION from @firebase/analytics.

js
import { SDK_VERSION } from '@react-native-firebase/analytics';

console.log('Analytics package version:', SDK_VERSION);