Android Integration Guide

Embrace.io is designed to be super simple to implement. As app developers, we hated implementing analytics tools that state “just 5 minutes to integrate” but are really a ton of events that take forever to get right.

With the Embrace.io SDK, our goal is 15 minutes or less. Slap it in and we start to gather a ton of information. What we don’t have is context so we’ll ask for it in three forms - 1) user identitication, 2) logging, and 3) start/end events specifying the most important moments in your app.

Note: by this point you should have received an API key. If you still haven’t, reach out to us on Slack or via email.

Requirements

Get started

Installing the Android SDK

The Embrace.io SDK is available on jCenter but we will need to add your Bintray user to our organization in order to access it (since we are in closed Beta). Creating a Bintray account is free and can be done here. To integrate it into your Gradle project, make the following changes to your build.gradle file. Your Bintray API key can be obtained by going to Edit Profile > API Key.

buildscript {
    repositories {
        maven {
            url "http://embrace-io.bintray.com/mvn-public"

            credentials {
                username = "<BINTRAY_USERNAME>"
                password = "<BINTRAY_API_KEY>"
            }
        }
    }
    
    dependencies {
        classpath 'embrace-io:embrace-swazzler:1.0.0'
    }
}

apply plugin: 'embrace-swazzler'

repositories {
    maven {
        url "http://embrace-io.bintray.com/mvn-public"

        credentials {
            username = "<BINTRAY_USERNAME>"
            password = "<BINTRAY_API_KEY>"
        }
    }
}

dependencies {
    compile 'embrace-io:embrace-android-sdk:1.0.3'
}

In order to provide the most accurate measure of the performance of your app, it is highly recommended to initialize the Embrace.io Android SDK as early as possible. Ideally, this should be the first thing that should be done as soon as your app is launched. For most typical situations, this can be accomplished by creating a custom class that extends android.app.Application and initializing Embrace within the onCreate() callback method.

package com.mycompany;

import io.embrace.android.embracesdk.Embrace;

public final class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Embrace.getInstance().start(this);
    }
}

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.

<application
    android:name="com.mycompany.MyApplication" />
    <meta-data
        android:name="io.embrace.android.embracesdk.api.key"
        android:value="<EMBRACE_API_KEY>" />
</application>

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

Congratulations you’ve successfully integrated Embrace.io into your Android application! You’re now ready to define your first app moment and measure the startup performance of your app.

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 your app’s performance. In fact, by just enabling the Embrace.io SDK, an active timer is started in the background for measuring your app’s startup performance. Stopping the startup timer is extremely simple and can be done by executing the following method call.

Embrace.getInstance().endAppStartup();

When identifying the end of the app’s startup sequence, it’s best to give this a bit of consideration. In some cases, it may not be the most optimal to simply mark the end of the Activity.onResume() to be the end of app startup. For example, it’s possible that even though the Activity itself has been fully created, parts of the UI may still be waiting for resources to be downloaded and rendered onto the screen. As a result, ending the app’s startup there would mean that any extra time the user had to wait before the app was ready would not be recorded. In cases like these, we generally recommend adding this line at the point where the user can perform useful interactions with your app.

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 two flavors (info and error). Error logs contain information about the calling thread’s stack trace. Both have the ability to set custom properties.

Info messages are called via Embrace.getInstance().logInfo("<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 there is a limitation that only string types are allowed to be keys and that must map to a value of one 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);

Logging network calls

The Embrace.io Android SDK provides a mechanism for logging network calls that transpired in the app. These network calls are then collected and processed in order to determine if any issues occurred due to these network calls. At the moment, the Embrace.io SDK currently has no way of knowing if a network call happened within the app and therefore must be alerted of the fact in order for any processing to be done to it. (We plan to add support for OkHttp and other networking libraries in the coming months.) Luckily, the API for logging these network calls is fairly straightforward as shown below.

import io.embrace.android.embracesdk.EmbHttpMethod;

String url = "http://httpstat.us/404";
int statusCode = 404;
long startTime = System.currentTimeMillis();
long endTime = startTime + 100L;
long bytesSent = 96;
long bytesReceived = 7;

Embrace.getInstance().logNetworkCall(url, EmbHttpMethod.GET, statusCode, startTime, endTime,
        bytesSent, bytesReceived);

Next steps

Happy developing!