cordova-plugin-firebasex-performance

Firebase Performance Monitoring module for the modular FirebaseX Cordova plugin suite.

The Firebase Performance Monitoring SDK enables you to measure, monitor and analyze the performance of your app in the Firebase console.

This plugin wraps the Firebase Performance Monitoring SDK and provides methods to control performance data collection and create custom performance traces in your Cordova app.

Table of Contents

• Installation
  • Plugin variables
• Android Performance Monitoring Gradle plugin
• Disable data collection on startup
• API
  • setPerformanceCollectionEnabled
  • isPerformanceCollectionEnabled
  • startTrace
  • incrementCounter
  • stopTrace
• Reporting issues

Installation

Install the plugin by adding it to your project's config.xml:

cordova plugin add cordova-plugin-firebasex-performance

or by running:

cordova plugin add cordova-plugin-firebasex-performance

This module depends on cordova-plugin-firebasex-core which will be installed automatically as a dependency.

Plugin variables

The following plugin variables are used to configure the performance module at install time. They can be set on the command line at plugin installation time:

cordova plugin add cordova-plugin-firebasex-performance --variable VARIABLE_NAME=value

Or in your config.xml:

<plugin name="cordova-plugin-firebasex-performance">
    <variable name="VARIABLE_NAME" value="value" />
</plugin>

| Variable | Default | Description | |---|---|---| | ANDROID_FIREBASE_PERF_VERSION | 22.0.2 | Android Firebase Performance SDK version. | | IOS_FIREBASE_SDK_VERSION | 12.9.0 | iOS Firebase SDK version (for performance pod). | | FIREBASE_PERFORMANCE_COLLECTION_ENABLED | true | Whether to enable performance data collection on app startup. Set to false to disable on startup and enable at runtime using setPerformanceCollectionEnabled(). | | ANDROID_FIREBASE_PERFORMANCE_MONITORING | false | Whether to add the Firebase Performance Monitoring Gradle plugin for automatic Android network request monitoring. | | ANDROID_FIREBASE_PERF_GRADLE_PLUGIN_VERSION | 2.0.1 | Version of the Firebase Performance Monitoring Gradle plugin to use. |

Android Performance Monitoring Gradle plugin

• The Firebase Performance Monitoring Gradle plugin for Android is required to enable automatic monitoring of network requests in Android apps.
• However, as outlined here, adding this Gradle plugin to your Android builds can significantly increase Android build times and memory usage.
• For this reason, the Gradle plugin is not added to your Android app builds by default.
• If you want to add it to make use of automatic network request monitoring on Android, set the ANDROID_FIREBASE_PERFORMANCE_MONITORING plugin variable at plugin install time:
  • --variable ANDROID_FIREBASE_PERFORMANCE_MONITORING=true
• If you choose to add it, the Gradle plugin currently requires Gradle v6.1.1 and Android Studio v4.0 or above.
• Note: on iOS when this plugin is installed, automatic network request monitoring takes place without requiring any extra configuration.

Disable data collection on startup

By default, performance data collection is enabled on app startup. To disable this, set the FIREBASE_PERFORMANCE_COLLECTION_ENABLED plugin variable to false at install time:

cordova plugin add cordova-plugin-firebasex-performance --variable FIREBASE_PERFORMANCE_COLLECTION_ENABLED=false

Data collection can then be enabled/disabled at runtime using setPerformanceCollectionEnabled().

API

The following methods are available via the FirebasexPerformance global object.

setPerformanceCollectionEnabled

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

Parameters:

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

FirebasexPerformance.setPerformanceCollectionEnabled(true); // Enables performance data collection

FirebasexPerformance.setPerformanceCollectionEnabled(false); // Disables performance data collection

isPerformanceCollectionEnabled

Indicates whether performance 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 setPerformanceCollectionEnabled().
• 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

FirebasexPerformance.isPerformanceCollectionEnabled(
    function (enabled) {
        console.log(
            "Performance data collection is " +
                (enabled ? "enabled" : "disabled")
        );
    },
    function (error) {
        console.error(
            "Error getting Performance data collection setting: " + error
        );
    }
);

startTrace

Start a trace.

Parameters:

• {string} name - name of trace to start
• {function} success - callback function to call on successfully starting trace
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasexPerformance.startTrace("test trace", success, error);

incrementCounter

To count the performance-related events that occur in your app (such as cache hits or retries), add a line of code similar to the following whenever the event occurs, using a string other than retry to name that event if you are counting a different type of event:

Parameters:

• {string} name - name of trace
• {string} counterName - name of counter to increment
• {function} success - callback function to call on successfully incrementing counter
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasexPerformance.incrementCounter("test trace", "retry", success, error);

stopTrace

Stop the trace.

Parameters:

• {string} name - name of trace to stop
• {function} success - callback function to call on successfully stopping trace
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasexPerformance.stopTrace("test trace");

Reporting issues

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

• Check the existing issues to see if the issue has already been reported.
• Check the issue template and provide all requested information.
• The more information and context you provide, the easier it is for the maintainers to understand the issue and provide a resolution.