The Embrace Developer Hub

Welcome to the Embrace documentation. You'll find comprehensive guides and documentation to help you start working with Embrace as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Android Quick Integration

Welcome to the Android SDK! The basic integration is two simple steps and detailed via the self-service flow. The complete integration is outlined below.

Once completed, verify the success of the integration using the Live Integration feature located in 'Recent Sessions' tab in the dashboard.

Requirements

  • Android 4.1 (API 16) or later
  • Gradle 4.4 or later
  • Android Build Tools Plugin 3.0.0 or later
  • Java source and target version 1.8 or later
  • Unique Embrace App ID
  • Unique Embrace API Token
    If you do not use Gradle and/or need an App ID and API Token, contact us at support@embrace.io or on Slack.

Current version of the SDK is 3.3.1.

If you are upgrading from a SDK older than 3.x - you will need to update your integration. Please go to Upgrading to 3.X of the Android SDK for a list of the changes to make to your app.

Initialize the Android SDK

Android Permissions

Your application Android permissions must have access to the internet to send events. Embrace automatically requests the following two permissions. Please make sure these permissions are set in your AndroidManifest.xml:

  • android.permission.INTERNET
  • android.permission.ACCESS_NETWORK_STATE

Enable Java 8 support

Version 3.x of the SDK requires support for Java 8 to be enabled. To enable support for Java 8, add the following to your project's build.gradle file:

compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

Add the SDK to your app

The Embrace Android SDK is publicly available in jCenter. To add it to your app, simply make the following changes in your project’s build.gradle file:

buildscript {
    repositories {
        jcenter()
        google()
    }

    dependencies {
        classpath 'embrace-io:embrace-swazzler:3.3.1'
    }
}

*When integrating, plug in your device and the Integration Testing page will alert you if the version is out of date.

Then in your app's build gradle file:

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

repositories {
    jcenter()
}

embrace {
    appId = '<EMBRACE_APP_ID>'
    apiToken = '<API_TOKEN>'
}

If you haven't receive an App ID or API Token, reach out to us via support@embrace.io or on Slack.

Initialize the SDK

Initialize the Embrace client as early as possible so we can correctly track crashes, OOMs, ANRs and terminations. From your app’s custom Application class, which must extend android.app.Application, call Embrace.getInstance().start(this) at the start of the onCreate method.

import io.embrace.android.embracesdk.Embrace;

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

For more info on the Application class, please refer to the reference in the Android Developer docs.

If you use a third party, like Akamai or Cloudflare, initialize Embrace after the network SDK. For more info please refer to the Network Libraries support document.

Define the App Startup

Embrace automatically detects the beginning and end of the Startup. However, since Startups end in multiple ways - a deep link to a particular activity, a load of a home screen, or a promotion, you must explicitly define which activities do not constitute the end of a Startup.

By default, Embrace automatically determines that the startup has ended when the Activity.onResume() method returns. However, not all apps fit this paradigm (ex. splash screens) and your app may require more time before the user can interact with it. Add @StartupActivity annotation to any Activity class that you wish to skip; e.g. not end on occurrence. For example:

@StartupActivity
public class MainActivity extends Activity {
  // Your code goes here...
}

For more information and options on implementing startup, go to Define App Startup.

Identify your Users

You must identify the user in order to search for the user in the dashboard, associate the user with your own internal data, and link to any third-party integrations, such as Zendesk.

Tag users with one or more identifiers as early as possible in the startup and whenever in the app the identifier may be set; for example, after registering. To tag a user use one or more of the following lines:

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

For more information and options on tagging and untagging users, go to Identify Your Users.

Define App Moments

An app Moment - Moment - A section of the app that blocks the user from progressing until it finishes loading, processing, etc. identifies locations in your app where your users may be blocked from an experience; e.g. not able to progress to the next screen. The best example is app Startup, and others include Purchase (from click to accept/reject) and Video start (from click to play.)

Think of Moments as a start/stop watch through which Embrace measures time taken, abandonment rates, and other important metrics that affect user experiences. Screenshots and stacktraces are automatically taken to provide additional context.

App Moments are identified by name and are started and ended in the following manner:

Embrace.getInstance().startEvent("purchase-cart");
//...
Embrace.getInstance().endEvent("purchase-cart");

You should define at least 3-4 moments in your app that are of utmost importance. We have provided Default Flows for easier integration. Please refer to Purchase Flow, User Registration Flow, Subscription Flow.

To add optional parameters or for more complex setups, please refer to Define App Moments.

Add Error Logging and Breadcrumbs

A well-placed and descriptive log message is the developer's chance to help themselves:

  1. Provides a much clearer view of what's happening on your users' phones within a user session. Context!
  2. Gathers stacktraces and screenshots
  3. Alerts to unusual activity and spikes
  4. Makes user flows visible (Breadcrumbs!)

Add Breadcrumbs, Info, Warning and Error log messages throughout your app for whenever errors and context are expected and visibility is valuable. Think error conditions, events that may precede an error, handled errors, etc. or wherever you might want a screenshot or stacktrace. While all logs display on the timeline, only Info, Warning, and Error are aggregated and alerted. Use the following lines of code as examples:

// Log an error message (Screenshot default:on, Stacktrace on)
Embrace.getInstance().logInfo("User has entered checkout flow", props);

// Log a warning message (Screenshot default:on, Stacktrace off)
Embrace.getInstance().logWarning("User attempted expired credit card", props);

// Log an info message (Screenshot default:off, Stacktrace off)
Embrace.getInstance().logError("User purchase request failed", props);

// Add a Breadcrumb to the User Timeline  (No stacktrace or screenshot)
Embrace.getInstance().logBreadcrumb("Your 64-char-or-less message here...")

When to use each type:

  • Errors - exceptions, handled exceptions, and egregious issues on which you'd like to be alerted
  • Warnings - potential errors that do not rise to the same level of an error and for which you may want an alert
  • Info - log info of interest that you'd like to see aggregated across user timelines
  • Breadcrumbs - context to events that will only display on a user timeline and will not be aggregated or alerted

Note on Stacktraces and Screenshots:
Screenshots are defaulted on for only Errors and can be turned on for Warning and Info.
Stacktraces are always on for all the log types other than Breadcrumbs.

To add optional properties for greater visibility and for best practices, please refer to Add Error Logs and Breadcrumbs.

Test your integration

While integrating the Embrace SDK, it's extremely easy to verify using the Live Integration feature in the dashboard.

Plug-in your device and see in real-time the messages sent from your application. To successfully use the Live Integration page under Recent Sessions:

  • The application must be running a DEBUG build
  • The application must be connected to the debugger in Android Studio

When testing, verify the following events are set correctly:

  1. Startup Moment
  2. User Identifier
  3. Log Message (Error, Warning or Info)
  4. Breadcrumbs

Questions?

Contact us at support@embrace.io or on Slack.


Android Quick Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.