Follow these steps to setup the Didomi Android SDK:

• ​Add the SDK to your project​

• ​Add a Proguard rule for Didomi​

• ​Initialize the SDK​

• ​Setup the SDK UI​

• ​Configure the SDK​

Add the SDK to your project

We offer our SDK as a pre-compiled package that you can add to your application. We support SDK versions >= 16 (minSdkVersion = 16).

The package is distributed through the JCenter repository. Make sure it is added to your repositories in your build.gradle file:

buildscript {
    repositories {
        jcenter()
    }
}

Add our SDK to your dependencies:

dependencies {
    compile 'io.didomi.sdk:android:1.11.0'
}

Our SDK requires permissions to use the Internet connection and check its status so also make sure to add the following permissions to your AndroidManifest file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.my.app">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
</manifest>

Geolocation permissions are not required but will be used if your app has them to avoid making extra HTTP requests for determining the user country.

Add a Proguard rule for Didomi

The Didomi SDK uses GSON to generate JSON-encoded API events sent back to the Didomi platform for analytics. We use @SerializedName to indicate the name of the JSON properties and ensure that they are correctly encoded into JSON.

In certain configurations, the host app configuration for Proguard will obfuscate some key SDK classes and break the API events sent to Didomi. This translates into incorrect analytics for the app on Android and is hard to catch as it usually only becomes apparent once in production (as debug/test builds usually do not run through Proguard).

To ensure that this does not happen, add the following rule to your Proguard file:

-keep class io.didomi.sdk.apiEvents.** { *; })

If you want to check whether that issue applies to you, you can monitor the events sent by the Didomi SDK in your production build.

Correct events should look like:

Notice how the parameters and user.token properties have a lot of data.

Incorrect events will look like this:

Notice how the parameters and user.token properties are empty.

Initialize the SDK

Once our SDK has been added to your project, you need to initialize it. The initialization process will run in a background thread and prepare the SDK for interactions with the user and your application. It is important to launch the SDK initialization as soon as possible.

In the onCreate function of your main Application class, call the Didomi.getInstance().initialize function and pass a reference to your Application instance and your API key:

package com.my.app;
​
import android.app.Application;
import android.util.Log;
​
import io.didomi.sdk.Didomi;
​
public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
​
        try {
            Didomi.getInstance().initialize(
                this,
                "<API key>",
                null,
                null,
                null,
                false
            );
            
            // Do not use the Didomi.getInstance() object here for anything else than registering your ready listener
            // The SDK might not be ready yet
            
            Didomi.getInstance().onReady(() -> {
                // The SDK is ready, you can now interact with it
            });
        } catch(Exception e) {
            Log.e("App", "Error while initializing the Didomi SDK", e);
        }
    }
}

It is a good idea to have a try/catch block around the Didomi initialization code and log any error that might happen.

Keep in mind that the SDK initialization is an asynchronous process so you must avoid interacting with the Didomi object until it is actually ready to handle your requests. Use the onReady function to register a listener for the ready event.

Setup the SDK UI

In order for the SDK to be able to display UI elements and interact with the user, you must provide a reference to your main activity. Call the setupUI function of the SDK in the onCreate lifecycle event of your main activity:

package io.didomi.sample;
​
import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
​
import io.didomi.sdk.Didomi;
​
public class SampleActivity extends AppCompatActivity {
​
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
​
        Didomi.getInstance().setupUI(this);
    }
}
​

We use the activity to get the fragment manager and register our own lifecycle events. We do not keep a reference to the activity outside of the call to the setupUI function to avoid leaks.

Configure the SDK

We support three options for configuration the UI and the behavior of the SDK:

• ​Didomi Console: the SDK is configured remotely from the Didomi Console

• ​Local file: the SDK is configured from a didomi_config.json file embedded in your app package

• ​Remote file: the SDK is configured from a remote didomi_config.json file

From the Console (Recommended)

You can configure the consent notice in your app by creating a notice in your Didomi Console. It will automatically be linked to your app through your API Key and, optionally, your app package name. You can access the Didomi console here.

In order to enable this option, make sure to pass the disableDidomiRemoteConfig parameter as false when calling the initialize method as shown below.

Didomi.getInstance().initialize(
    this,
    "<API key>",
    null,
    null,
    null,
    false
);

The SDK will automatically use the remote configuration hosted by Didomi and cache it locally. The cached version is refreshed every 60 minutes. If there is no connection available to download the remote configuration and no locally cached version, the SDK will try to use a local assets/didomi_config.json configuration file as a fallback. See the Local option below for more information on how to configure the SDK through a local configuration file.

Local file

In this option, you create your own SDK configuration file and embed in your app package.

The SDK behavior is configured in a didomi_config.json file that must be placed at the root of your assets/ folder. Create a file with the following content to get started:

{
    "app": {
        "name": "My App Name",
        "privacyPolicyURL": "http://www.website.com/privacy",
        "vendors": {
            "iab": {
                "all": true
            }
        },
        "gdprAppliesGlobally": true,
        "gdprAppliesWhenUnknown": true
    }
}

You also need to disable loading the remote configuration to ensure that only the local file is loaded and that no HTTP request is sent. Update your initialize call to set the disableDidomiRemoteConfig parameter to true:

Didomi.getInstance().initialize(
    this,
    "<API key>",
    null,
    null,
    null,
    true
);

Your SDK is now setup. Read the Getting started section to learn more about how to configure it to match your app UI and requirements.

Remote file

You can provide a remote URL for the SDK to download the didomi_config.json configuration file from. That allows you to update the SDK configuration without having to re-publish you mobile application.

When that configuration is enabled, the SDK will automatically use the remote configuration and cache it locally. The cached version is refreshed every 60 minutes. If there is no connection available to download the remote file and no locally cached version, the SDK will try to use the local assets/didomi_config.json as a fallback.

To enable that option, change your call to initialize to provide the remote file URL:

Didomi.getInstance().initialize(
    this,
    "<API key>",
    null,
    "https://www.website.com/didomi_config.json",
    null,
    false
);

Also see the reference documentation of the initialize function for more information.