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

pluginManagement {
    repositories {
        mavenCentral()
    }

    plugins {
        id 'io.embrace.swazzler' version "${embrace_version}" apply false
    }
}

Kotlin

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

plugins {
    id 'io.embrace.swazzler'
}

Kotlin

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

Legacy approach

tip

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

buildscript {
    repositories {
        mavenCentral()
        google()
    }
    dependencies {
        classpath 'io.embrace:embrace-swazzler:7.6.0'
    }
}

Kotlin

buildscript {
    repositories {
        mavenCentral()
        google()
    }
    dependencies {
        classpath("io.embrace:embrace-swazzler:$embrace_version")
    }
}

Then apply the plugin in your app/build.gradle file:

Groovy

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

Kotlin

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.

Note on Permissions

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

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

Kotlin

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

info

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

warning

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"
}

info

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.