cordova-plugin-firebasex-analytics

Firebase Analytics plugin for the modular FirebaseX Cordova plugin suite.

This plugin wraps the Firebase Analytics SDK and provides methods to log events, set user properties, and control analytics data collection in your Cordova app.

Supported platforms: Android and iOS

Installation
- Plugin variables
Disable data collection on startup
Google Tag Manager
- Android
- iOS
API
Reporting issues

Installation

cordova plugin add cordova-plugin-firebasex-analytics

Dependency: Requires cordova-plugin-firebasex-core to be installed.

Plugin variables

The following plugin variables can be set at installation time using the --variable flag:

Variable	Default	Description
`ANDROID_FIREBASE_ANALYTICS_VERSION`	`23.0.0`	Android Firebase Analytics SDK version.
`ANDROID_PLAY_SERVICES_TAGMANAGER_VERSION`	`18.1.1`	Android Play Services Tag Manager version.
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for analytics pods).
`IOS_GOOGLE_TAG_MANAGER_VERSION`	`9.0.0`	iOS Google Tag Manager pod version.
`FIREBASE_ANALYTICS_COLLECTION_ENABLED`	`true`	Whether to enable analytics data collection on app startup. Set to `false` to disable until user consent is given - see Disable data collection on startup.
`FIREBASE_ANALYTICS_WITHOUT_ADS`	`false`	If `true`, removes IDFA/AdID tracking support for a smaller binary.
`GOOGLE_ANALYTICS_ADID_COLLECTION_ENABLED`	`true`	Whether to enable collection of the Advertising ID.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE`	`true`	Default consent for analytics data storage.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE`	`true`	Default consent for ad-related data storage.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA`	`true`	Default consent for ad user data collection.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS`	`true`	Default consent for ad personalization signals.
`IOS_ON_DEVICE_CONVERSION_ANALYTICS`	`false`	Whether to enable on-device conversion analytics on iOS.

For example, to disable analytics collection on startup and remove ad tracking:

cordova plugin add cordova-plugin-firebasex-analytics --variable FIREBASE_ANALYTICS_COLLECTION_ENABLED=false --variable FIREBASE_ANALYTICS_WITHOUT_ADS=true

Disable data collection on startup

By default, analytics data will begin being collected as soon as the app starts up. However, for data protection or privacy reasons, you may wish to disable data collection until such time as the user has granted their permission.

To do this, set the following plugin variables to false at plugin install time:

FIREBASE_ANALYTICS_COLLECTION_ENABLED
GOOGLE_ANALYTICS_ADID_COLLECTION_ENABLED
GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE
GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE
GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA
GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS

For example:

cordova plugin add cordova-plugin-firebasex-analytics \
 --variable FIREBASE_ANALYTICS_COLLECTION_ENABLED=false \
 --variable GOOGLE_ANALYTICS_ADID_COLLECTION_ENABLED=false \
 --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE=false \
 --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE=false \
 --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA=false \
 --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS=false

This will disable analytics data collection (on both Android & iOS) until you call setAnalyticsCollectionEnabled and setAnalyticsConsentMode:

FirebasexAnalytics.setAnalyticsCollectionEnabled(true);
FirebasexAnalytics.setAnalyticsConsentMode({
    [FirebasexAnalytics.AnalyticsConsentMode.ANALYTICS_STORAGE]: FirebasexAnalytics.AnalyticsConsentStatus.GRANTED,
    [FirebasexAnalytics.AnalyticsConsentMode.AD_STORAGE]: FirebasexAnalytics.AnalyticsConsentStatus.GRANTED,
    [FirebasexAnalytics.AnalyticsConsentMode.AD_USER_DATA]: FirebasexAnalytics.AnalyticsConsentStatus.GRANTED,
    [FirebasexAnalytics.AnalyticsConsentMode.AD_PERSONALIZATION]: FirebasexAnalytics.AnalyticsConsentStatus.GRANTED,
});

Notes:

Calling setAnalyticsCollectionEnabled() will have no effect if the FIREBASE_ANALYTICS_COLLECTION_ENABLED variable is set to true.
Calling setAnalyticsCollectionEnabled(true|false) will enable/disable data collection during the current app session and across subsequent app sessions until such time as the same method is called again with a different value.

Google Tag Manager

https://developers.google.com/tag-platform/tag-manager/mobile

Android

Create directory resources/android/containers
Download your container-config json file from Tag Manager and add a <resource-file> node in your config.xml.

<platform name="android">
    <resource-file src="resources/android/containers/GTM-XXXXXXX.json" target="app/src/main/assets/containers/GTM-XXXXXXX.json" />
    ...

Preview mode (optional)

More info

<platform name="android">
  <config-file parent="/manifest/application" target="AndroidManifest.xml">
    <activity android:exported="true" android:name="com.google.android.gms.tagmanager.TagManagerPreviewActivity" android:noHistory="true" tools:replace="android:noHistory">
      <intent-filter>
        <data android:scheme="tagmanager.c.{{BUNDLE_ID}}" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
      </intent-filter>
    </activity>
  </config-file>
    ...

iOS

The application name should not contain spaces

<name short="Cordova App">CordovaApp</name>

Create directory resources/ios/container
Download your container-config json file from Tag Manager and to directory.

Preview mode (optional)

More info

Add xmlns:tools="http://schemas.android.com/tools" to <widget> tag
Add to config.xml

<platform name="ios">
  <edit-config file="*-Info.plist" mode="merge" target="CFBundleURLTypes">
    <array>
      <dict>
        <key>CFBundleURLName</key>
        <string>{{BUNDLE_ID}}</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>tagmanager.c.{{BUNDLE_ID}}</string>
        </array>
      </dict>
    </array>
  </edit-config>
    ...
</platform>

API

The list of available methods for this plugin is described below.

Firebase Analytics enables you to log events in order to track use and behaviour of your apps.

By default, Firebase does not store fine-grain analytics data - only a sample is taken and detailed event data is then discarded. The Firebase Analytics console is designed to give you a coarse overview of analytics data.

If you want to analyse detailed, event-level analytics you should consider exporting Firebase Analytics data to BigQuery. The easiest way to set this up is by streaming Firebase Analytics data into BigQuery. Note that until you set this up, all fine-grain event-level data is discarded by Firebase.

setAnalyticsCollectionEnabled

Manually enable/disable analytics data collection, e.g. if disabled on app startup.

Parameters:

{boolean} setEnabled - whether to enable or disable analytics data collection

FirebasexAnalytics.setAnalyticsCollectionEnabled(true); // Enables analytics data collection

FirebasexAnalytics.setAnalyticsCollectionEnabled(false); // Disables analytics data collection

isAnalyticsCollectionEnabled

Indicates whether analytics data collection is enabled.

Notes:

This value applies both to the current app session and subsequent app sessions until such time as it is changed.
It returns the value set by setAnalyticsCollectionEnabled().
If automatic data collection was not disabled on app startup, this will always return true.

Parameters:

{function} success - callback function which will be invoked on success. Will be passed a {boolean} indicating if the setting is enabled.
{function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasexAnalytics.isAnalyticsCollectionEnabled(
    function (enabled) {
        console.log(
            "Analytics data collection is " + (enabled ? "enabled" : "disabled")
        );
    },
    function (error) {
        console.error(
            "Error getting Analytics data collection setting: " + error
        );
    }
);

AnalyticsConsentMode

Constants defining the mode of consent to set:

{string} AnalyticsConsentMode.ANALYTICS_STORAGE - consent for analytics data storage
{string} AnalyticsConsentMode.AD_STORAGE - consent for ad storage
{string} AnalyticsConsentMode.AD_USER_DATA - consent for ad user data
{string} AnalyticsConsentMode.AD_PERSONALIZATION - consent for ad personalization

AnalyticsConsentStatus

Constants defining the status of consent to set:

{string} AnalyticsConsentStatus.GRANTED - consent granted
{string} AnalyticsConsentStatus.DENIED - consent denied

setAnalyticsConsentMode

Sets the user's consent mode status for various types of data collection in the application. This includes consent for analytics data storage, ad storage, ad personalization, and ad user data. The consent status can be set to 'GRANTED' or 'DENIED'. Read more here

Parameters:

{object} consent - map of the consent modes as AnalyticsConsentMode and their status as AnalyticsConsentStatus

var consents = {};
consents[FirebasexAnalytics.AnalyticsConsentMode.ANALYTICS_STORAGE] = FirebasexAnalytics.AnalyticsConsentStatus.GRANTED;
consents[FirebasexAnalytics.AnalyticsConsentMode.AD_STORAGE] = FirebasexAnalytics.AnalyticsConsentStatus.GRANTED;
consents[FirebasexAnalytics.AnalyticsConsentMode.AD_USER_DATA] = FirebasexAnalytics.AnalyticsConsentStatus.GRANTED;
consents[FirebasexAnalytics.AnalyticsConsentMode.AD_PERSONALIZATION] = FirebasexAnalytics.AnalyticsConsentStatus.DENIED;

FirebasexAnalytics.setAnalyticsConsentMode(consents, function() {
    console.log("Consent mode set");
}, function(error) {
    console.error("Error setting consent mode: " + error);
});

logEvent

Log an event using Analytics:

Parameters:

{string} eventName - name of event to log to Firebase Analytics
- Limit of 40 characters.
- Dots are not allowed in eventName.
{object} eventProperties - key/value object of custom event properties.
- This must be a flat (non-nested) object.
- The value must be a primitive type such as string/number/etc. (not a complex object such as array or nested object).
- Limit of 40 characters for parameter name and 100 characters for parameter value.

FirebasexAnalytics.logEvent("select_content", {
    content_type: "page_view",
    item_id: "home",
});

setScreenName

Set the name of the current screen in Analytics:

Parameters:

{string} screenName - name of screen to log to Firebase Analytics

FirebasexAnalytics.setScreenName("Home");

setUserId

Set a user id for use in Analytics:

Parameters:

{string} userName - name of user to set in Firebase Analytics

FirebasexAnalytics.setUserId("user_id");

setUserProperty

Set a user property for use in Analytics:

Parameters:

{string} name - name of user property to set in Firebase Analytics
{string} value - value of user property to set in Firebase Analytics

FirebasexAnalytics.setUserProperty("name", "value");

initiateOnDeviceConversionMeasurement

Initiates on-device conversion measurement using either user's email address or phone number. iOS only.

Parameters:

{object} userIdentifier - user identifier as either emailAddress or phoneNumber key
{function} success - callback function which will be invoked on success.
{function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasexAnalytics.initiateOnDeviceConversionMeasurement(
    { emailAddress: "me@here.com" },
    function () {
        console.log("On device conversion measurement initiated");
    },
    function (error) {
        console.error(
            "Error initiating on device conversion measurement: " + error
        );
    }
);

Reporting issues

Before reporting an issue with this plugin, please do the following:

Check the existing issues and pull requests for duplicates
Ensure you are using the latest version of the plugin and its dependencies
Include full details of the error including relevant logs and device/platform information

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github		.github
scripts		scripts
src		src
types		types
www		www
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
plugin.xml		plugin.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

cordova-plugin-firebasex-analytics

Installation

Plugin variables

Disable data collection on startup

Google Tag Manager

Android

Preview mode (optional)

iOS

Preview mode (optional)

API

setAnalyticsCollectionEnabled

isAnalyticsCollectionEnabled

AnalyticsConsentMode

AnalyticsConsentStatus

setAnalyticsConsentMode

logEvent

setScreenName

setUserId

setUserProperty

initiateOnDeviceConversionMeasurement

Reporting issues

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

cordova-plugin-firebasex-analytics

Installation

Plugin variables

Disable data collection on startup

Google Tag Manager

Android

Preview mode (optional)

iOS

Preview mode (optional)

API

setAnalyticsCollectionEnabled

isAnalyticsCollectionEnabled

AnalyticsConsentMode

AnalyticsConsentStatus

setAnalyticsConsentMode

logEvent

setScreenName

setUserId

setUserProperty

initiateOnDeviceConversionMeasurement

Reporting issues

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages