@capacitor-firebase/analytics

Unofficial Capacitor plugin for Firebase Analytics.[^1]

Installation

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: 22.2.0)

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

iOS

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

Configuration

No configuration required for this plugin.

Demo

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

Usage

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

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

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

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

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

const setSessionTimeoutDuration = async () => {
  await FirebaseAnalytics.setSessionTimeoutDuration({
    duration: '120',
  });
};

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

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

const resetAnalyticsData = async () => {
  await FirebaseAnalytics.resetAnalyticsData();
};

const initiateOnDeviceConversionMeasurementWithEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithEmailAddress({
    emailAddress: '[email protected]',
  });
};

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

const initiateOnDeviceConversionMeasurementWithHashedEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithHashedEmailAddress({
    emailAddressToHash: '[email protected]',
  });
};

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

API

• getAppInstanceId()
• setConsent(...)
• setUserId(...)
• setUserProperty(...)
• setCurrentScreen(...)
• logEvent(...)
• setSessionTimeoutDuration(...)
• setEnabled(...)
• isEnabled()
• resetAnalyticsData()
• initiateOnDeviceConversionMeasurementWithEmailAddress(...)
• initiateOnDeviceConversionMeasurementWithPhoneNumber(...)
• initiateOnDeviceConversionMeasurementWithHashedEmailAddress(...)
• initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(...)
• Interfaces
• Enums

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

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 |

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.

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.