SDK Setup

Add the Embrace Gradle Plugin

The Embrace Gradle Plugin uploads mapping files that gets human-readable stacktraces from production. It also instruments bytecode so that some telemetry is automatically captured.

Add the Embrace Gradle Plugin to your build using one of the methods below:

Version Catalogs

Alter your libs.versions.toml file:

[versions]
embrace = "8.0.0"

[plugins]
embrace = { id = "io.embrace.gradle", version.ref = "embrace" }

Then apply the plugin at your module-level build.gradle.kts:

plugins {
    alias(libs.plugins.embrace)
}

Settings File

Kotlin

Alter your settings.gradle.kts:

pluginManagement {
    repositories {
        mavenCentral()
    }
    plugins {
        id("io.embrace.gradle") version "8.0.0" apply false
    }
}

Then apply the plugin at your module-level build.gradle.kts:

plugins {
    id("io.embrace.gradle")
}

Groovy

Alter your settings.gradle:

pluginManagement {
    repositories {
        mavenCentral()
    }
    plugins {
        id 'io.embrace.gradle' version "8.0.0" apply false
    }
}

Then apply the plugin at your module-level build.gradle:

Alter your settings.gradle:

plugins {
    id 'io.embrace.gradle'
}

Legacy Plugins DSL

Alter your root-level build.gradle:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'io.embrace:embrace-gradle-plugin:8.0.0'
    }
}

Then apply the plugin at your module-level build.gradle:

apply plugin: 'embrace-gradle-plugin'

Add the Embrace Android SDK

Add the Embrace Android SDK to the build.gradle file of each module where you want to invoke Embrace:

Version Catalogs

Alter your libs.versions.toml file:

[libraries]
embrace = { group = "io.embrace", name = "embrace-android-sdk", version.ref = "embrace" }

Then add the dependency at your module-level build.gradle.kts:

implementation(libs.embrace)

Dependencies Block

Kotlin

implementation("io.embrace:embrace-android-sdk:8.0.0")

Groovy

implementation 'io.embrace:embrace-android-sdk:8.0.0'

Create Embrace configuration file

A JSON-formatted file is used to configure Embrace SDK features. To start off, create a new empty JSON file at app/src/main/embrace-config.json:

{ }

Set your app ID and API token

Next, login to the Embrace dashboard and create a project if you haven't already. The dashboard contains the app ID and API token that are necessary for configuring your integration.

For the initial integration and on local developer builds, you can set these in the Embrace configuration file created above:

{
  "app_id": "<your-app-id>",
  "api_token": "<your-api-token>"
}

In production, we recommend setting these values via the build machine's environment variables:

export EMBRACE_APP_ID="<your-app-id>"
export EMBRACE_API_TOKEN="<your-api-token>"

The Embrace SDK will automatically read these environment variables when your app is built. The environment variables will override any values set via the configuration file.

Start the Embrace SDK

Start the SDK on the main thread before the Application object is created. Refer to the FAQ here for rationale.

Auto Start

The Embrace SDK can be started automatically during your Application object's onCreate() method by setting a property in the Embrace Gradle Plugin DSL. This requires your app to use a custom Application subclass, which the Embrace Gradle Plugin will modify at build time to all the SDK start method.

If you don't have an Application subclass, you must create one.

To enable automatic startup, add the following block in your app/build.gradle:

embrace {
    bytecodeInstrumentation {
        autoSdkInitializationEnabled.set(true)
    }
}

If you need to configure your app or the SDK in the onCreate() method before the SDK starts, like if you need to add an OTel Exporter, DO NOT use this method. Instead, start the SDK manually after you do so (see below).

App Startup Library

If you have already integrated the App Startup Library you can define an Initializer to start Embrace:

class EmbraceInitializer : Initializer<Embrace> {
    override fun create(context: Context): Embrace = Embrace.start(context)
    override fun dependencies(): List<Class<out Initializer<*>>> = return emptyList()
}

Then add an entry to your AndroidManifest.xml:

<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    <meta-data  android:name="com.example.EmbraceInitializer"
          android:value="androidx.startup" />
</provider>

Manual

Initialize the Embrace SDK in the onCreate method of your Application subclass.

class MyApplication : Application {
  override fun onCreate() {
      super.onCreate()
      Embrace.start(this)
  }
}

Build and Run the Application

Build and run the application. You should see the following message in Logcat:

Embrace SDK version X.Y.Z started for appId = xxxxx

Confirm data is sent to Embrace

Launch your app, send it to the background by switching to another app, and then relaunch it.

After refreshing the Embrace dashboard you should see the uploaded session in your browser. Depending on network conditions this may ocassionally take a few minutes to show up.

If you stop your app by force killing it Embrace will not upload the completed session until it is relaunched. You must always relaunch your app before data can show in Embrace's dashboard.

Alter default behavior

After completing an SDK integration we recommend you alter the SDK's configuration from the defaults to suit your needs. You can also alter the Gradle Plugin's configuration if needed.