Initial SDK setup

Install the SDK

The Exponea Android SDK can be installed or updated using Gradle or Maven. In case of Gradle, you can use Kotlin or Groovy for your build configuration files.

📘

Refer to https://github.com/exponea/exponea-android-sdk/releases for the latest Exponea Android SDK release.

Gradle (Kotlin)

1. In your app's build.gradle.kts file, add com.exponea.sdk:sdk inside the dependencies { } section:
   Kotlin

   implementation("com.exponea.sdk:sdk:4.0.1")
   

2. Rebuild your project (Build > Rebuild Project).

Gradle (Groovy)

1. In your app's build.gradle file, add com.exponea.sdk:sdk inside the dependencies { } section:
   Groovy

   implementation 'com.exponea.sdk:sdk:4.0.1'
   

2. Rebuild your project (Build > Rebuild Project).

Maven

1. In your app's pom.xml file, add com.exponea.sdk:sdk inside the <dependencies> </dependencies> section:
   XML

   <dependency>
      <groupId>com.exponea.sdk</groupId>
      <artifactId>sdk</artifactId>
      <version>4.0.1</version>
   </dependency>   
   

2. Rebuild your app with Maven.

Initialize the SDK

Now that you have installed the SDK in your project, you must import, configure, and initialize the SDK in your application code.

The required configuration parameters are projectToken, authorization, and baseURL. You can find these in the Bloomreach Engagement webapp under Project settings > Access management > API.

📘

Refer to Mobile SDKs API access management for details.

You can configure the SDK in code (preferred) or using a JSON configuration file.

Using configuration in code

Import the SDK:

import com.exponea.sdk.Exponea
import com.exponea.sdk.models.ExponeaConfiguration

Initialize the SDK:

val configuration = ExponeaConfiguration()

configuration.authorization = "Token YOUR_API_KEY"
configuration.projectToken = "YOUR_PROJECT_TOKEN"
configuration.baseURL = "https://api.exponea.com"

Exponea.init(this, configuration)

Using a configuration file

Create a file exponea_configuration.json inside the assets folder of your application with at least the following configuration properties:

{
  "projectToken": "YOUR_PROJECT_TOKEN",
  "authorization": "Token YOUR_API_KEY",
  "baseURL": "https://api.exponea.com"
}

Import the SDK in your code:

import com.exponea.sdk.Exponea

Initialize the SDK:

Exponea.init(this)

The SDK will read the configuration parameters from the configuration file.

📘

Refer to exponea_configuration.json in the example app for an example configuration file.

Where to place the SDK initialization code

In an application subclass

Your Application's onCreate() method is the best place to do the initialization - it's called only once and very early in the application lifecycle. Application is the class for maintaining global application state.

It should look similar to the example below:

class MyApplication : Application() {
  override fun onCreate(){
    super.onCreate()

    val configuration = ExponeaConfiguration()

    configuration.authorization = "Token jlk5askvxss99asmnbgayrks333"
    configuration.projectToken = "47b5cc2c-e661-11e8-bb95-0a580a201692"
    configuration.baseURL = "https://api.exponea.com"

    // SDK initialization
    Exponea.init(this, configuration)
    // or Exponea.init(this) if using configuration file
  }
}

Make sure to register your custom application class in AndroidManifest.xml:

<application
   android:name=".MyApplication">
   ...
</application>

In an activity

You can also initialize the SDK from any Activity, but it's essential to do so as early as possible, preferably in your activity's onCreate() method.

The SDK hooks into the application lifecycle to track sessions (among other things), so you must keep track of activities' onResume callbacks. If you need to initialize the SDK after an activity has been resumed, do so with the context of the current activity.

❗️

Certain API methods can be used before SDK initialization if a previous initialization was done.
These API methods are:

• Exponea.handleCampaignIntent
• Exponea.handleRemoteMessage
• Exponea.handleNewToken
• Exponea.handleNewHmsToken

In such a case, each method will track events with the configuration of the last initialization. Consider initializing the SDK in Application::onCreate to make sure a fresh configuration is applied in case of an application update.

Done!

At this point, the SDK is active and should now be tracking sessions in your app.

Other SDK configuration

Advanced configuration

The SDK can be further configured by setting additional properties of the ExponeaConfiguration object or exponea_configuration.json file. For a complete list of available configuration parameters, refer to the Configuration documentation.

Log level

The SDK supports the following log levels defined in com.exponea.sdk.util.Logger.Level:

The default log level is INFO. While developing or debugging, setting the log level to VERBOSE can be helpful.

You can set the log level at runtime as follows:

Exponea.loggerLevel = Logger.Level.VERBOSE

Data flushing

Read Data flushing to learn more about how the SDK uploads data to the Engagement API and how to customize this behavior.

Troubleshooting

Build error "Manifest merger failed"

You may get a build error similar to the following, especially in a default new "empty activity" project generated by Android Studio:

Manifest merger failed : Attribute application@fullBackupContent value=(@xml/backup_rules) from AndroidManifest.xml:8:9-54
	is also present at [com.exponea.sdk:sdk:4.0.1] AndroidManifest.xml:15:9-70 value=(@xml/exponea_default_backup_rules).

The SDK and the new app generated by Android Studio both enable the auto backup feature in AndroidManifest.xml but each with their own backup rules. It is up to you as a developer to manage the manifest files and ensure they can be merged properly.

Your options include:

• Use the SDK's backup rules:
  XML

  <application
      android:allowBackup="true"
      ...
      >
  </application>
  

  (Remove android:fullBackupContent="@xml/backup_rules")
• Define your own backup rules in app/src/main/res/xml/backup_rules.xml and specify they should replace the SDK's backup rules:
  XML

  <application
      android:allowBackup="false"
      android:fullBackupContent="@xml/backup_rules"
      tools:replace="android:fullBackupContent"
      ...
      >
  </application>
  

• Turn off auto backup:
  XML

  <application
      android:allowBackup="false"
      ...
      >
  </application>
  

  (Remove android:fullBackupContent="@xml/backup_rules")