Embrace.io Android SDK

Embrace.io Android SDK

Welcome to the Android SDK! Embrace.io helps you monitor the performance and stability of your mobile apps to keep your users happy. We provide unmatched visibility into the experiences of each user and give you the information and insights you need to maximize the performance of your app.

The purpose of this guide is to get you quickly started with the Embrace.io SDK and begin sending data from your app.

Requirements

Get started

  1. Installing the Embrace.io SDK

  2. Monitoring the performance of your app startup

  3. Identifying your users

  4. Logging messages

  5. Defining additional app moments

  6. Logging network calls

  7. Crashes

  8. Live events

To send additional context and information and get even more out of the Embrace.io dashboard, check out our documentation site https://embrace-io.github.io. (Apologies for the iOS focused docs - we started with the easier platform, even though Android is better!)

Have questions? Contact us on Slack ([https://embrace-io-community.slack.com](https://embrace-io-community.slack.com)) or email us at [support@embrace.io](support@embrace.io).

Installing the Embrace.io Android SDK

By now, you should have received a unique API key. If not, please contact us via Slack or email [support@embrace.io](support@embrace.io) and we’ll get you started!

The Android SDK is currently hosted on our public Maven repository on Bintray. A Bintray account is not required to download the SDK. However, the repository must be registered in your `build.gradle` file in order for Gradle to pull all necessary dependencies.

buildscript {
    // Register Embrace.io repository for downloading the SDK plugin.
    repositories {
        maven {
            url "http://embrace-io.bintray.com/mvn-public"
        }
    }
    
    dependencies {
        classpath 'embrace-io:embrace-swazzler:2.0.5'
    }
}

apply plugin: 'com.android.application'
apply plugin: 'embrace-swazzler'

repositories {
    // Register Embrace.io repository for downloading library dependencies.
    maven {
        url "http://embrace-io.bintray.com/mvn-public"
    }
}

In order for your custom Application class to be used, it needs to be registered in the Android manifest. The manifest is also where you will be declaring your Embrace API key. This can be done by making the following changes to your AndroidManifest.xml file.

<manifest
    android:package="com.mycompany">
    <application
        android:name="com.mycompany.MyApplication" />
        <!-- The API key specific to your application. -->
        <meta-data
            android:name="io.embrace.android.embracesdk.api.key"
            android:value="<EMBRACE_API_KEY>" />
        <!-- The fully qualified class name to the auto-generated BuildConfig class.
             This value should be set to the package name defined in the manifest tag followed by ".BuildConfig".
             Note that this value is NOT the same as the application ID.-->
        <meta-data
            android:name="io.embrace.android.embracesdk.build.config"
            android:value="com.mycompany.BuildConfig" />
    </application>
</manifest>

The final step is to add the following Proguard rules to your application. These rules help us surface meaningful debugging information to you when we capture uncaught exceptions. While not absolutely critical, we highly recommend adding these rules as they will significantly improve your experience with Embrace.io.

-keep class io.embrace.android.embracesdk.** { *; }
-dontwarn io.embrace.android.embracesdk.**

-keepattributes Exceptions, InnerClasses, LineNumberTable, SourceFile
-keep class com.mycompany.BuildConfig { *; }

Congratulations! You’ve successfully integrated Embrace.io into your Android application! You’re now ready to measure the performance of your app’s startup process.

Monitoring the performance of your app startup

Making sure that your app is as responsive as possible at startup is a concern that all developers share. Fortunately, Embrace.io makes it easy to measure this. The Embrace.io SDK automatically creates a startup app moment and begins an active timer as soon as the SDK is enabled. Stopping the startup timer is extremely simple and can be done by executing the following method call.

Embrace.getInstance().endAppStartup();

While it’s tempting to simply append this line at the end of your `Activity.onResume()` callback, we highly recommend giving some thought into finding the optimal place to end the app’s startup sequence. Ideally the startup performance should represent the time required for the application to be useable from a cold launch. In practice however, accurately defining this can be tricky, especially for complex applications with many different UI flows. Generally speaking, we’ve found that most successful integrations tends to follow these guidelines.

App moments should not be affected by user input

App moments are meant to tell you how your application is performing, not what your users are doing. One of the most common mistakes we’ve seen developers make is to wrap an app moment around a section of code that requires user interaction. For example, it’s common for some applications to display a login activity on startup. Ending the startup sequence after the user has successfully authenticated themselves in the app would capture the time required to initialize the application as well as the time it took for the user to enter their login credentials. Ultimately this skews the data towards reporting longer startup times. A better approach would be to split this into two moments. The startup moment could be defined as the time it takes to display the login UI while another moment might measure the time between the user initiating the login request to showing their personalized content.

All reachable flows must be terminated

Another common problem when defining an app moment is not terminating it at all reachable paths from the moment’s start. This is especially prevalent during startup because different triggers may cause the user to enter the application using different user flows. For instance, the user might be shown a different activity depending on whether the app was started via the launcher or in response to a notification broadcast. When a moment is not terminated, this results in a large number of stalled moment issues which usually indicates a serious problem since we expect that all moments eventually terminate. If you suspect that there is a flow that is not accounted for, we recommend checking out the screenshots associated with the moment. A screenshot will only be taken if the moment duration exceeds 5 seconds.

Identifying your users

The Embrace.io SDK requires you to add identifiers to the current user so that you can associate them with your own internal data and perform searches and segmentation in the web dashboard. The Embrace.io SDK supports the following mechanisms for identifying your users.

Tagging users is simple and can be done using the following method calls.

Embrace.getInstance().setUsername("daniel");
Embrace.getInstance().setUserEmail("daniel@embrace.io");
Embrace.getInstance().setUserIdentifier("1337");

Untagging users is even easier and can be done by doing the following.

Embrace.getInstance().clearUsername();
Embrace.getInstance().clearUserEmail();
Embrace.getInstance().clearUserIdentifier();

Logging messages

We try our best to collect and surface up meaningful information about your application in order to build up a context as to what is happening on your users’ mobile devices. However, sometimes a well-placed and descriptive log message complementing that data can provide a much clearer view into what’s happening on your users’ phones.

In addition to whatever custom message you’d like to set, log messages come in three flavors: INFO, WARNING, and ERROR. Error logs contain information about the calling thread’s stack trace. All have the ability to set custom properties.

Info messages are called via

Embrace.getInstance().logInfo("<Name>", props);

Warning messages are called via

Embrace.getInstance().logWarning("<Name>", props);

Error messages are called via

Embrace.getInstance().logError("<Name>", props);

Properties are simple key-value attribute pairs that can be sent along with the log message payload and are yet another way to provide visibility into your app’s state. Only a maximum of 10 properties are allowed to be set. Currently only string types are allowed to be keys. Values can be any of the following supported types.

Log messages can be sent in the following manner:

Embrace.getInstance().logInfo("Suspicious user was identified!", null);

Map<String, Object> props = new HashMap<>();

props.put("name", "Daniel");
props.put("age", 25);
props.put("score", 102.2);
props.put("is-new-record", true);

Embrace.getInstance().logError("User with impossible score detected!", props);

Defining additional app moments

The startup moment is automatically created by the SDK. You can also define your own custom app moments. App moments allow you to wrap portions of code and hyperfocus on the performance behavior of your application in those areas. The following attributes are monitored and collected by the Android SDK within an app moment.

While app moments are very powerful tools and provide a great deal of contextual information, they are not designed as a global monitor for your app’s performance. Rather they provide the most value enclosing short sections that you think may have a bug, is performing poorly or has a critical business impact (e.g. purchase flows). In general, we recommend defining one or two moments in addition to the startup moment inside your application.

App moments are identified by name and can be started in the following manner:

Embrace.getInstance().startEvent("<NAME>");

Terminating app moments is just as simple.

Embrace.getInstance().endEvent("<NAME>");

Remember, it is important that all flows from the start of the moment be accounted for when stopping the moment. Failure to do so may lead to some moments stalling out. As with ending the app startup moment, terminating an already completed app moment has no effect.

Logging network calls

If your app uses either the OkHttp3 and/or Http(s)URLConnection networking libaries then the SDK will automatically log metadata about your network calls out-of-the-box without any code changes. We **DO NOT** collect or inspect the request/response body. Only the following metrics are collected in order to identify and report networking issues that your app may have.

Crashes

The latest version of the Android SDK also includes support for capturing and reporting crashes. No configuration is required by the developer to enable this functionality. Uncaught exceptions will be processed and handled by the thread exception handler which will send metadata about the crash to Embrace. If your app is using another crash reporting solution such as Crashlytics, Embrace will not interfere with the operation of the Crashlytics exception handler. However, we cannot guarantee that other crash reporting solutions will not interfere with our exception handling logic.

Live events

Once you’re done integrating the Embrace SDK into your Android application it’s extremely easy to verify its operation using the Live Events feature in the dashboard. The Live Events page allows you to see in real-time what types of messages are being sent from your application. The following requirements must be met to have your messages appear on the Live Events page.

Live Events is meant primarily for testing and integration purposes only. As a result, messages that appear in Live Events will not be shown elsewhere on the dashboard. If the Live Event functionality does not seem to work for you, we recommend double-checking that the BuildConfig `meta-data` tag in the Android Manifest correctly refers to the fully-qualified class name of the `BuildConfig` class.

Support

We have many more bells and whistles to help you better understand and gain visibility into your app and each user’s experience. Please go to documentation site https://embrace-io.github.io for more features.

Have questions? Contact us on Slack (https://embrace-io-community.slack.com) or email us at [support@embrace.io](support@embrace.io).