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.4.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 "${swazzler_version}" apply false
    }
}

Kotlin

pluginManagement {
    repositories {
        mavenCentral()
    }
    val swazzler_version: String by settings
    plugins {
        id("io.embrace.swazzler") version "${swazzler_version}" apply false
    }
}

Include swazzler_version in your gradle.properties file:

swazzler_version=7.4.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.4.0'
    }
}

Kotlin

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

Then apply the plugin in your app/build.gradle file & ensure you specify Java 8 in compileOptions:

Groovy

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

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

Kotlin

apply(plugin = "com.android.application")
apply(plugin = "embrace-swazzler")

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

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.4.0'

Kotlin

implementation("io.embrace:embrace-android-sdk:7.4.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.

Add the config file

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.

warning

It's not recommended to directly hardcode access tokens into your source code. Instead, you can add it as an environment variable like EMBRACE_API_TOKEN and reference that.

info

Your app ID and API token are available on the Embrace dashboard.

---

NDK crash capture

If you want to capture NDK crash reports from your app add the ndk_enabled setting to your config file:

{
  "app_id": "xxxxx",
  "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "ndk_enabled": true
}

---

Next, you'll be creating your first session.