npm.io
8.5.1 • Published 1 week ago

@capacitor-firebase/analytics

Licence
Apache-2.0
Version
8.5.1
Deps
0
Size
158 kB
Vulns
0
Weekly
0
Stars
525
SummaryDependencyVersions

Capacitor Firebase Analytics Plugin

Unofficial Capacitor plugin for Firebase Analytics.[^1]

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Use Cases

The Firebase Analytics plugin is typically used to understand how users interact with your app, for example:

  • Event tracking: Log app events such as sign-ups with custom parameters using logEvent(...).
  • Screen tracking: Record which screens users visit using setCurrentScreen(...).
  • Audience segmentation: Assign user IDs and custom user properties to segment your users.
  • Consent management: Set the user's consent mode and enable or disable data collection to comply with privacy requirements.
  • Conversion measurement: Initiate on-device conversion measurement with an email address or phone number on iOS.

Compatibility

Plugin Version Capacitor Version Status
8.x.x >=8.x.x Active support
7.x.x 7.x.x Deprecated
6.x.x 6.x.x Deprecated
5.x.x 5.x.x Deprecated
1.x.x 4.x.x Deprecated

Guides

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/analytics` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capacitor-firebase/analytics firebase
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

Android
Disable Analytics data collection

See Disable Analytics data collection if you want to disable Analytics data collection.

Disable Advertising ID collection

See Disable Advertising ID collection if you want to disable Advertising ID collection.

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

  • $firebaseAnalyticsVersion version of com.google.firebase:firebase-analytics (default: 23.0.0)

This can be useful if you encounter dependency conflicts with other plugins in your project.

iOS
Swift Package Manager

Add the following to your capacitor.config.json (or capacitor.config.ts) to avoid a SwiftPM package identity collision:

{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/analytics": {
            "symlink": true
          }
        }
      }
    }
  }
}

Attention: SPM packageOptions support requires Capacitor CLI 8.4.0+.

If you are using CocoaPods for your iOS project, you need to add the CapacitorFirebaseAnalytics/Analytics pod to your Podfile (usually ios/App/Podfile):

target 'App' do
capacitor_pods
# Add your Pods here
+  pod 'CapacitorFirebaseAnalytics/Analytics', :path => '../../node_modules/@capacitor-firebase/analytics'
end

Attention: Do not add the pod in the section def capacitor_pods, but under the comment # Add your Pods here (example).

Disable Analytics data collection

See Disable Analytics data collection if you want to disable Analytics data collection.

Disable IDFA collection

If you are using CocoaPods for your iOS project and you want to disable IDFA collection, you can use the CapacitorFirebaseAnalytics/AnalyticsWithoutAdIdSupport pod instead of the CapacitorFirebaseAnalytics/Analytics pod:

target 'App' do
capacitor_pods
# Add your Pods here
-  pod 'CapacitorFirebaseAnalytics/Analytics', :path => '../../node_modules/@capacitor-firebase/analytics'
+  pod 'CapacitorFirebaseAnalytics/AnalyticsWithoutAdIdSupport', :path => '../../node_modules/@capacitor-firebase/analytics'
end

If you are using Swift Package Manager for your iOS project and you want to disable IDFA collection, you can enable the AnalyticsWithoutAdIdSupport trait in your capacitor.config.json (or capacitor.config.ts):

{
  "experimental": {
    "ios": {
      "spm": {
        "swiftToolsVersion": "6.1",
        "packageTraits": {
          "@capacitor-firebase/analytics": ["AnalyticsWithoutAdIdSupport"]
        }
      }
    }
  }
}

Note: SPM trait support requires Capacitor CLI 8.3.0+ and Xcode 16.3+ (Swift 6.1+).

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Usage

The following examples show how to log events, track screens, identify users, manage data collection, configure the session timeout, and initiate on-device conversion measurement.

Log events

Log an app event with a name and optional parameters:

import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const logEvent = async () => {
  await FirebaseAnalytics.logEvent({
    name: 'sign_up',
    params: { method: 'password' },
  });
};
Track screens

Set the current screen name to record which screens users visit. The screenClassOverride option is only available on Android and iOS:

import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setCurrentScreen = async () => {
  await FirebaseAnalytics.setCurrentScreen({
    screenName: 'Login',
    screenClassOverride: 'LoginPage',
  });
};
Identify users

Set the user ID property and custom user properties to segment your users:

import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setUserId = async () => {
  await FirebaseAnalytics.setUserId({
    userId: '123',
  });
};

const setUserProperty = async () => {
  await FirebaseAnalytics.setUserProperty({
    key: 'language',
    value: 'en',
  });
};
Manage data collection

Enable or disable automatic data collection (the value does not apply until the next run of the app), check whether it is enabled (only available on Web), or clear all analytics data from the device (only available on Android and iOS):

import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setEnabled = async () => {
  await FirebaseAnalytics.setEnabled({
    enabled: true,
  });
};

const isEnabled = async () => {
  const { enabled } = await FirebaseAnalytics.isEnabled();
  return enabled;
};

const resetAnalyticsData = async () => {
  await FirebaseAnalytics.resetAnalyticsData();
};
Configure the session timeout

Set the duration of inactivity that terminates the current session. Only available on Android and iOS:

import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setSessionTimeoutDuration = async () => {
  await FirebaseAnalytics.setSessionTimeoutDuration({
    duration: '120',
  });
};
Initiate on-device conversion measurement

Initiate on-device conversion measurement with a plain or hashed email address or phone number. Only available on iOS:

import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const initiateOnDeviceConversionMeasurementWithEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithEmailAddress({
    emailAddress: 'mail@example.com',
  });
};

const initiateOnDeviceConversionMeasurementWithPhoneNumber = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithPhoneNumber({
    phoneNumber: '+49123456789',
  });
};

const initiateOnDeviceConversionMeasurementWithHashedEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithHashedEmailAddress({
    emailAddressToHash: 'mail@example.com',
  });
};

const initiateOnDeviceConversionMeasurementWithHashedPhoneNumber = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithHashedPhoneNumber({
    phoneNumberToHash: '+49123456789',
  });
};

API

getAppInstanceId()
getAppInstanceId() => Promise<GetAppInstanceIdResult>

Retrieves the app instance id.

Only available for Android and iOS.

Returns: Promise<GetAppInstanceIdResult>

Since: 1.4.0

setConsent(...)
setConsent(options: SetConsentOptions) => Promise<void>

Sets the user's consent mode.

Param Type
options SetConsentOptions

Since: 6.0.0

setUserId(...)
setUserId(options: SetUserIdOptions) => Promise<void>

Sets the user ID property.

Param Type
options SetUserIdOptions

Since: 0.1.0

setUserProperty(...)
setUserProperty(options: SetUserPropertyOptions) => Promise<void>

Sets a custom user property to a given value.

Param Type
options SetUserPropertyOptions

Since: 0.1.0

setCurrentScreen(...)
setCurrentScreen(options: SetCurrentScreenOptions) => Promise<void>

Sets the current screen name.

Param Type
options SetCurrentScreenOptions

Since: 0.1.0

logEvent(...)
logEvent(options: LogEventOptions) => Promise<void>

Logs an app event.

Param Type
options LogEventOptions

Since: 0.1.0

setSessionTimeoutDuration(...)
setSessionTimeoutDuration(options: SetSessionTimeoutDurationOptions) => Promise<void>

Sets the duration of inactivity that terminates the current session.

Only available for Android and iOS.

Param Type
options SetSessionTimeoutDurationOptions

Since: 0.1.0

setEnabled(...)
setEnabled(options: SetEnabledOptions) => Promise<void>

Enables/disables automatic data collection. The value does not apply until the next run of the app.

Param Type
options SetEnabledOptions

Since: 0.1.0

isEnabled()
isEnabled() => Promise<IsEnabledResult>

Returns whether or not automatic data collection is enabled.

Only available for Web.

Returns: Promise<IsEnabledResult>

Since: 0.1.0

resetAnalyticsData()
resetAnalyticsData() => Promise<void>

Clears all analytics data for this app from the device. Resets the app instance id.

Only available for Android and iOS.

Since: 0.1.0

logTransaction(...)
logTransaction(options: LogTransactionOptions) => Promise<void>

Logs a StoreKit 2 transaction.

Only available for iOS (15.0+).

Param Type
options LogTransactionOptions

Since: 8.2.0

initiateOnDeviceConversionMeasurementWithEmailAddress(...)
initiateOnDeviceConversionMeasurementWithEmailAddress(options: InitiateOnDeviceConversionMeasurementWithEmailAddressOptions) => Promise<void>

Initiates on-device conversion measurement with an email address.

Only available for iOS.

Param Type
options InitiateOnDeviceConversionMeasurementWithEmailAddressOptions

Since: 7.2.0

initiateOnDeviceConversionMeasurementWithPhoneNumber(...)
initiateOnDeviceConversionMeasurementWithPhoneNumber(options: InitiateOnDeviceConversionMeasurementWithPhoneNumberOptions) => Promise<void>

Initiates on-device conversion measurement with a phone number.

Only available for iOS.

Param Type
options InitiateOnDeviceConversionMeasurementWithPhoneNumberOptions

Since: 7.2.0

initiateOnDeviceConversionMeasurementWithHashedEmailAddress(...)
initiateOnDeviceConversionMeasurementWithHashedEmailAddress(options: InitiateOnDeviceConversionMeasurementWithHashedEmailAddressOptions) => Promise<void>

Initiates on-device conversion measurement with a hashed email address.

Only available for iOS.

Param Type
options InitiateOnDeviceConversionMeasurementWithHashedEmailAddressOptions

Since: 7.2.0

initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(...)
initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(options: InitiateOnDeviceConversionMeasurementWithHashedPhoneNumberOptions) => Promise<void>

Initiates on-device conversion measurement with a hashed phone number.

Only available for iOS.

Param Type
options InitiateOnDeviceConversionMeasurementWithHashedPhoneNumberOptions

Since: 7.2.0

Interfaces
GetAppInstanceIdResult
Prop Type Description Since
appInstanceId string The app instance id. Not defined if FirebaseAnalytics.<a href="#consenttype">ConsentType</a>.ANALYTICS_STORAGE has been set to FirebaseAnalytics.<a href="#consentstatus">ConsentStatus</a>.DENIED. 1.4.0
SetConsentOptions
Prop Type Description Since
type ConsentType The consent type. 6.0.0
status ConsentStatus The consent status. 6.0.0
SetUserIdOptions
Prop Type Since
userId string | null 0.1.0
SetUserPropertyOptions
Prop Type Since
key string 0.1.0
value string | null 0.1.0
SetCurrentScreenOptions
Prop Type Description Default Since
screenName string | null 0.1.0
screenClassOverride string | null Only available for Android and iOS. null 0.1.0
LogEventOptions
Prop Type Description Since
name string The event name. 0.1.0
params { [key: string]: any; } The optional event params. 0.1.0
SetSessionTimeoutDurationOptions
Prop Type Description Default Since
duration number Duration in seconds. 1800 0.1.0
SetEnabledOptions
Prop Type Since
enabled boolean 0.1.0
IsEnabledResult
Prop Type Since
enabled boolean 0.1.0
LogTransactionOptions
Prop Type Description Since
transactionId string The StoreKit 2 Transaction.id value as a numeric string. 8.2.0
InitiateOnDeviceConversionMeasurementWithEmailAddressOptions
Prop Type Description Since
emailAddress string The email address to initiate on-device conversion measurement with. 7.2.0
InitiateOnDeviceConversionMeasurementWithPhoneNumberOptions
Prop Type Description Since
phoneNumber string The phone number to initiate on-device conversion measurement with. 7.2.0
InitiateOnDeviceConversionMeasurementWithHashedEmailAddressOptions
Prop Type Description Since
emailAddressToHash string The email address to initiate on-device conversion measurement with. 7.2.0
InitiateOnDeviceConversionMeasurementWithHashedPhoneNumberOptions
Prop Type Description Since
phoneNumberToHash string The phone number to initiate on-device conversion measurement with. 7.2.0
Enums
ConsentType
Members Value Since
AdPersonalization 'AD_PERSONALIZATION' 6.0.0
AdStorage 'AD_STORAGE' 6.0.0
AdUserData 'AD_USER_DATA' 6.0.0
AnalyticsStorage 'ANALYTICS_STORAGE' 6.0.0
FunctionalityStorage 'FUNCTIONALITY_STORAGE' 6.0.0
PersonalizationStorage 'PERSONALIZATION_STORAGE' 6.0.0
ConsentStatus
Members Value Since
Granted 'GRANTED' 6.0.0
Denied 'DENIED' 6.0.0

Test your implementation

Here you can find more information on how to test the Firebase Analytics implementation using the DebugView.

FAQ

How can I verify that my events are being logged?

Use the DebugView in the Firebase console to inspect events as they are logged by your app. See the DebugView documentation for more information on how to test your Firebase Analytics implementation.

How can I disable analytics data collection?

You can enable or disable automatic data collection at runtime using the setEnabled(...) method; note that the value does not apply until the next run of the app. To disable data collection by default, follow the platform-specific instructions linked in the Installation section for Android and iOS.

How do I set the user's consent mode?

Call the setConsent(...) method with a consent type (for example analytics storage or ad storage) and a consent status (granted or denied). This allows you to manage what data is collected based on the user's consent.

Why is the app instance ID not defined?

The appInstanceId returned by getAppInstanceId() is not defined if the analytics storage consent type has been set to denied via setConsent(...). Also note that getAppInstanceId() is only available on Android and iOS.

How do I disable Advertising ID or IDFA collection?

On Android, follow the Disable Advertising ID collection guide. On iOS, use the CapacitorFirebaseAnalytics/AnalyticsWithoutAdIdSupport pod instead of the CapacitorFirebaseAnalytics/Analytics pod if you are using CocoaPods, or enable the AnalyticsWithoutAdIdSupport package trait if you are using Swift Package Manager. See the Installation section for details.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.

Keywords

capacitorpluginnativecapacitor-pluginfirebasefirebase analyticsanalyticsevent trackingscreen trackinguser propertiesconsent mode