Adding the Android Embrace SDK
Add Embrace as a dependency
If you are using Version Catalogs:
Add our gradle plugin to your libs.versions.toml
file
[versions]
embrace = "7.6.0"
...
[plugins]
embrace = { id = "io.embrace.swazzler", version.ref = "embrace" }
Then add the following at the top of your app/build.gradle.kts
:
plugins {
alias(libs.plugins.embrace)
}
If you are not using Version Catalogs:
Add the following to your settings.gradle
:
- Groovy
- Kotlin
pluginManagement {
repositories {
mavenCentral()
}
plugins {
id 'io.embrace.swazzler' version "${embrace_version}" apply false
}
}
pluginManagement {
repositories {
mavenCentral()
}
val embrace_version: String by settings
plugins {
id("io.embrace.swazzler") version "${embrace_version}" apply false
}
}
Include embrace_version
in your gradle.properties
file:
embrace_version=7.6.0
Then add the following at the top of your app/build.gradle
:
- Groovy
- Kotlin
plugins {
id 'io.embrace.swazzler'
}
plugins {
id("io.embrace.swazzler")
}
Legacy approach
If you use Gradle's legacy Plugins DSL follow this approach instead.
Alter the build.gradle
at your project's root as shown below:
- Groovy
- Kotlin
buildscript {
repositories {
mavenCentral()
google()
}
dependencies {
classpath 'io.embrace:embrace-swazzler:7.6.0'
}
}
buildscript {
repositories {
mavenCentral()
google()
}
dependencies {
classpath("io.embrace:embrace-swazzler:$embrace_version")
}
}
Then apply the plugin in your app/build.gradle
file:
- Groovy
- Kotlin
apply plugin: 'com.android.application'
apply plugin: 'embrace-swazzler'
apply(plugin = "com.android.application")
apply(plugin = "embrace-swazzler")
The Embrace Gradle Plugin performs a few key functions:
- Adds the Embrace SDK to your app's dependency list.
- Injects configuration info the SDK reads at run time.
- Instruments bytecode to insert SDK hooks that capture telemetry.
- Uploads mapping files to get human-readable stacktraces in production.
Embrace automatically adds the following permissions so that it can make HTTP requests to deliver captured data.
android.permission.INTERNET
android.permission.ACCESS_NETWORK_STATE
Add a dependency to modules or libraries you want to call Embrace from (optional)
If you have an app that uses internal modules or libraries, you must specify the Embrace SDK dependency directly in your module's Gradle file
- Groovy
- Kotlin
implementation 'io.embrace:embrace-android-sdk:7.6.0'
implementation("io.embrace:embrace-android-sdk:7.6.0")
You still need to apply the Embrace Gradle Plugin in the app's Gradle file (apply plugin: 'embrace-swazzler')
and verify that the version set in your project Gradle file is the same as the version set for the SDK in the module’s Gradle file.
Set your app ID and API token
Your app ID and API token are available on the Embrace dashboard.
With environment variables (recommended)
Set the following environment variables in your development environment:
export EMBRACE_APP_ID="xxxxx"
export EMBRACE_API_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
The Embrace SDK will automatically read these environment variables at runtime.
With a config file
Hardcoding access tokens in your source code might lead to security issues. We recommend using environment variables.
Add a file at app/src/main/embrace-config.json
with the following contents:
{
"app_id": "xxxxx",
"api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Further configuration options are documented here.
NDK crash capture
If you want to capture NDK crash reports from your app add the ndk_enabled
setting to your app/src/main/embrace-config.json
file:
{
"ndk_enabled": true
}
Next, you'll be creating your first session.