cordova-plugin-firebasex-crashlytics

Firebase Crashlytics module for the modular FirebaseX Cordova plugin suite.

This plugin wraps the Firebase Crashlytics SDK and provides methods to log crashes and non-fatal errors, set user identifiers and custom keys, and control crash data collection in your Cordova app.

Table of Contents

• Installation
  • Plugin variables
• Disable data collection on startup
• iOS setup
  • Set up project to automatically upload dSYM files
• API
  • setCrashlyticsCollectionEnabled
  • isCrashlyticsCollectionEnabled
  • didCrashOnPreviousExecution
  • setCrashlyticsUserId
  • sendCrash
  • setCrashlyticsCustomKey
  • logMessage
  • logError
• Reporting issues

Installation

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

cordova plugin add cordova-plugin-firebasex-crashlytics

or by running:

cordova plugin add cordova-plugin-firebasex-crashlytics

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 crashlytics module at install time. They can be set on the command line at plugin installation time:

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

Or in your config.xml:

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

| Variable | Default | Description | |---|---|---| | ANDROID_FIREBASE_CRASHLYTICS_VERSION | 20.0.4 | Android Firebase Crashlytics SDK version. | | ANDROID_FIREBASE_CRASHLYTICS_NDK_VERSION | 20.0.4 | Android Firebase Crashlytics NDK version. | | IOS_FIREBASE_SDK_VERSION | 12.9.0 | iOS Firebase SDK version (for crashlytics pod). | | FIREBASE_CRASHLYTICS_COLLECTION_ENABLED | true | Whether to enable Crashlytics data collection at app startup. Set to false to disable data collection on startup. |

Disable data collection on startup

By default, Crashlytics 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 FIREBASE_CRASHLYTICS_COLLECTION_ENABLED plugin variable to false at plugin install time:

cordova plugin add cordova-plugin-firebasex-crashlytics \
 --variable FIREBASE_CRASHLYTICS_COLLECTION_ENABLED=false

This will disable Crashlytics data collection (on both Android & iOS) until you call setCrashlyticsCollectionEnabled:

FirebasexCrashlytics.setCrashlyticsCollectionEnabled(true);

Notes:

• Calling setCrashlyticsCollectionEnabled() will have no effect if the FIREBASE_CRASHLYTICS_COLLECTION_ENABLED variable is set to true (the default).
• Calling setCrashlyticsCollectionEnabled(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.

iOS setup

Set up project to automatically upload dSYM files

This plugin automatically adds a Crashlytics dSYM upload build phase to the Xcode project during installation. This ensures debug symbols are uploaded to Firebase for symbolicated crash reports. The build phase is removed when the plugin is uninstalled.

See the Firebase Documentation Get started with Firebase Crashlytics for more details.

Make sure cordova-plugin-firebasex-crashlytics is the last plugin in the cordova section of your package.json:

{
    "cordova": {
        "platforms": [
            "ios",
            "android"
        ],
        "plugins": {
            "cordova-plugin-firebasex-crashlytics": {
            }
        }
    }
}

API

The following methods are available via the FirebasexCrashlytics global object.

setCrashlyticsCollectionEnabled

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

Parameters:

• {boolean} setEnabled - whether to enable or disable Crashlytics data collection.
• {function} success - (optional) callback function which will be invoked on success
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

var shouldSetEnabled = true;
FirebasexCrashlytics.setCrashlyticsCollectionEnabled(
    shouldSetEnabled,
    function () {
        console.log("Crashlytics data collection is enabled");
    },
    function (error) {
        console.error(
            "Crashlytics data collection couldn't be enabled: " + error
        );
    }
);

isCrashlyticsCollectionEnabled

Indicates whether Crashlytics collection setting is currently enabled.

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

FirebasexCrashlytics.isCrashlyticsCollectionEnabled(
    function (enabled) {
        console.log(
            "Crashlytics data collection is " +
                (enabled ? "enabled" : "disabled")
        );
    },
    function (error) {
        console.error(
            "Error getting Crashlytics data collection setting: " + error
        );
    }
);

didCrashOnPreviousExecution

Checks whether the app crashed on its previous run.

Parameters:

• {function} success - callback function which will be invoked on success. Will be passed a {boolean} indicating whether the app crashed on its previous run.
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasexCrashlytics.didCrashOnPreviousExecution(function(didCrashOnPreviousExecution){
    console.log(`Did crash on previous execution: ${didCrashOnPreviousExecution}`));
}, function(error){
    console.error(`Error getting Crashlytics did crash on previous execution: ${error}`);
});

setCrashlyticsUserId

Set Crashlytics user identifier.

To diagnose an issue, it's often helpful to know which of your users experienced a given crash. Crashlytics includes a way to anonymously identify users in your crash reports. To add user IDs to your reports, assign each user a unique identifier in the form of an ID number, token, or hashed value.

See the Firebase docs for more.

Parameters:

• {string} userId - User ID to associate with Crashlytics reports

FirebasexCrashlytics.setCrashlyticsUserId("user_id");

sendCrash

Simulates (causes) a fatal native crash which causes a crash event to be sent to Crashlytics (useful for testing). See the Firebase documentation regarding crash testing. Crashes will appear under Event type = "Crashes" in the Crashlytics console.

Parameters: None

FirebasexCrashlytics.sendCrash();

setCrashlyticsCustomKey

Records a custom key and value to be associated with subsequent fatal and non-fatal reports.

Multiple calls to this method with the same key will update the value for that key.

The value of any key at the time of a fatal or non-fatal event will be associated with that event.

Keys and associated values are visible in the session view on the Firebase Crashlytics console.

A maximum of 64 key/value pairs can be written, and new keys added beyond that limit will be ignored. Keys or values that exceed 1024 characters will be truncated.

Parameters:

• {string} key - A unique key
• {string | number | boolean} value - A value to be associated with the given key
• {function} success - (optional) callback function which will be invoked on success
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasexCrashlytics.setCrashlyticsCustomKey(
    "number",
    3.5,
    function () {
        console.log("set custom key: number, with value: 3.5");
    },
    function (error) {
        console.error("Failed to set-custom key", error);
    }
);
FirebasexCrashlytics.setCrashlyticsCustomKey("bool", true);
FirebasexCrashlytics.setCrashlyticsCustomKey("string", "Ipsum lorem");
// Following is just used to trigger report for Firebase
FirebasexCrashlytics.logMessage("about to send a crash for testing!");
FirebasexCrashlytics.sendCrash();

logMessage

Sends a crash-related log message that will appear in the Logs section of the next native crash event. Note: if you don't then crash, the message won't be sent! Also logs the message to the native device console.

Parameters:

• {string} message - message to associate with next native crash event

FirebasexCrashlytics.logMessage("about to send a crash for testing!");
FirebasexCrashlytics.sendCrash();

logError

Sends a non-fatal error event to Crashlytics. In a Cordova app, you may use this to log unhandled Javascript exceptions, for example.

The event will appear under Event type = "Non-fatals" in the Crashlytics console. The error message will appear in the Logs section of the non-fatal error event. Note that logged errors will only be sent to the Crashlytics server on the next full app restart. Also logs the error message to the native device console.

Parameters:

• {string} errorMessage - non-fatal error message to log to Crashlytics
• {object} stackTrace - (optional) a stack trace generated by stacktrace.js
• {function} success - (optional) callback function which will be invoked on success
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

// Send an unhandled JS exception
var appRootURL = window.location.href.replace("index.html", "");
window.onerror = function (errorMsg, url, line, col, error) {
    var logMessage = errorMsg;
    var stackTrace = null;

    var sendError = function () {
        FirebasexCrashlytics.logError(
            logMessage,
            stackTrace,
            function () {
                console.log("Sent JS exception");
            },
            function (error) {
                console.error("Failed to send JS exception", error);
            }
        );
    };

    logMessage +=
        ": url=" +
        url.replace(appRootURL, "") +
        "; line=" +
        line +
        "; col=" +
        col;

    if (typeof error === "object") {
        StackTrace.fromError(error).then(function (trace) {
            stackTrace = trace;
            sendError();
        });
    } else {
        sendError();
    }
};

// Send a non-fatal error
FirebasexCrashlytics.logError(
    "A non-fatal error",
    function () {
        console.log("Sent non-fatal error");
    },
    function (error) {
        console.error("Failed to send non-fatal error", error);
    }
);

An example of how the error entry will appear in the Crashlytics console: Android

iOS

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.