Didomi - Developers documentation
  • Introduction
  • SDKs
    • Introduction
    • Web SDK
      • Getting started
      • Tags and vendors management
        • Tags management
          • Events & Variables
            • Deprecated
            • Custom events
          • Tag managers
            • Adobe Launch/DTM
            • Eulerian
            • Google Tag Manager
              • Configure the Didomi / GTM integration
              • Didomi's GTM template
            • Tealium
            • Other tag managers
        • Custom Didomi <script> tags
        • Third-party integrations
          • Google Ad Manager / AdSense
            • GDPR via Non-Personalized Ads
              • Share consent and load/refresh ads
              • Share consent without loading or refreshing ads
            • US states laws
          • Google Consent Mode V2
          • Kameleoon
          • Piano Analytics (AT Internet)
          • Prebid
            • GDPR via IAB TCF
            • US states laws
          • Salesforce DMP (Krux)
        • IAB frameworks
        • Programmatic API
      • Configuration
        • Bots (SEO & Performance tools)
        • Configuration by URL
        • Cookies and storage
        • Custom domains for events
        • Notice
          • Behavior
          • Interactions
          • Look and feel
        • Preferences
        • Theme
      • AB tests
      • Custom domain
        • Domain delegation
        • Reverse proxy
      • Share consents between domains
      • Share consents across devices
      • Pass user choices in query string
      • Serve Didomi assets from your domain
      • Reference
        • API
          • Deprecated
        • Events
      • Performance
    • Mobile and TV SDKs
      • Android and Android TV
        • Setup
        • Logging
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • iOS and tvOS
        • Setup
        • Logging
        • App Tracking Transparency (iOS 14.5+)
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • Unity
        • Setup
        • Reference
        • Versions
        • Troubleshooting
      • React Native
        • Setup
        • Reference
          • Deprecated
        • Versions
      • Flutter
        • Setup
        • Reference
        • Versions
      • Consent notice
        • Getting started
        • Customize the notice
        • Customize the preferences popup
        • Customize the theme & UI
        • Load notice by ID
      • Third-party SDKs
      • Share consents across devices
      • Share consent with WebViews
      • Google Consent Mode v2
      • FAQ
    • AMP SDK
      • Blocking Behaviors
        • Load immediately on page load
        • Load only after consent (positive or negative)
        • Load only after positive consent
      • Consent status for vendors
    • Help & Support
  • API
    • Introduction
      • Authentication
      • Errors
      • Pagination
      • Filters
      • Caching
      • Rate limiting
      • Quotas
      • Translations
    • Data Manager
      • Regulations
      • Configuration Tree
      • Purposes
        • Purposes & Vendors Numerical IDs
      • Preferences Library
      • User Rights
    • Widgets
      • Consent notices
        • Notices
        • Configurations
        • Multi-Regulation Configurations
          • Migration of Existing Notices and API Updates
        • Deployments
        • Tutorials
          • Create and publish a consent notice
          • Create and publish a multi-regulation consent notice
      • Privacy widgets
        • Create a widget
        • Retrieve widgets
        • Edit a widget
          • Content & Design
            • Themes & Shapes
            • Components
              • auth
              • dsar_form
              • footer
              • header
              • preference
              • preference_value
              • save
              • section
              • sections
            • Options
          • Purposes & preferences
          • Settings
        • Deploy a Widget
          • Use your own subdomain
          • Use your own domain
          • Implement an embeddable widget on your website
        • Authentication
          • Manage authentication providers
          • Authenticate your end-user
        • Archive a widget
        • Headless widgets
          • Public Methods
          • Custom elements
          • Custom events
          • Event listeners
        • Tutorial
          • Launch a Preference Center from a mobile app
    • Compliance Reports
      • Properties
      • Reports
      • CSV format reference
      • Websites
    • Consents and Preferences
      • Events
        • Generate IAB TCF consent string
      • Links
      • Proofs
      • Tokens
      • Secrets
      • Users
      • Tutorial
        • Collect and operate data
    • Privacy Requests
      • Requests
      • Notes
      • Links
      • Emails
  • Integrations
    • Introduction
      • Quotas
    • Generic integrations
      • Batch export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
        • Exported data
          • Notices consents
        • Logs
      • Webhooks
      • Batch import
      • Analytics export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
    • Third-party apps
      • CMP integrations
        • Didomi-mParticle integration for your CMP
        • Deploy Didomi’s SDK for your Adobe Commerce website
      • Preference Management Platform integrations
        • Actito
        • Adobe Campaign Classic
        • Adobe Experience Cloud
        • Adobe Marketo Engage
        • Adobe Source Connector
        • Braze
        • Dotdigital
        • Hubspot
        • Mailchimp
        • Microsoft Dynamics 365
        • Salesforce Marketing Cloud
        • Salesforce Sales & Service Cloud
        • Selligent
        • Brevo (ex Sendinblue)
    • Tutorials
      • Configure a HTTP webhook
      • Configure a batch export
      • Configure an analytics export
    • Emailing
      • Configurations
        • Actito Email
        • Actito SMS
        • Adobe Campaign Classic
        • Adobe Campaign Standard
      • Emails
        • Templates
        • Manage your templates
Powered by GitBook
On this page
  • Requirements
  • Add the SDK to your project
  • Languages
  • Initialize the SDK
  • Setup the SDK UI
  • Deep links
  • Configure the SDK
  • From the Console (Recommended)
  • Local file (deprecated)
  • Remote file
  • Download Global Vendor List (GVL)
  1. SDKs
  2. Mobile and TV SDKs
  3. Android and Android TV

Setup

PreviousAndroid and Android TVNextLogging

Last updated 15 days ago

Follow these steps to setup the Didomi Android and Android TV SDK:

Requirements

We offer our SDK as a pre-compiled package that you can add to your application. We support SDK versions >= 19 (minSdkVersion(19)) and its target/compile version is the .

Add the SDK to your project

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

buildscript {
    repositories {
        mavenCentral()
    }
}

Add our SDK to your dependencies:

dependencies {
    implementation 'io.didomi.sdk:android:2.24.1'
}

Our SDK uses some Java features. Java 8 being deprecated, you need to use a higher version. In order to use it, the following compileOptions must be specified in your application build.gradle :

android {
    compileSdkVersion (...)

    defaultConfig {
        (...)
    }

    buildTypes {
        (...)
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

If your project is composed of several modules, make sure the compileOptions are defined in each module build.gradle , otherwise, compilation errors may occur.

If you are using gradle plugin version 7.0.0 or above, Java 8 compilation is the default, hence compileOptions do not need to be set.

Our SDK requires permissions to use the Internet connection and check its status so the following permissions will be merged 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_NETWORK_STATE" />
</manifest>

Multidex

Example of error that can be caused by reaching the 64K limit:

FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':launcher:transformClassesWithDexBuilderForRelease'.
> com.android.build.api.transform.TransformException: java.lang.IllegalArgumentException: java.lang.IllegalArgumentException
android {    
    defaultConfig {
        multiDexEnabled = true
    }
}

Languages

Restricting the supported languages can reduce your application size.

android {
    defaultConfig {
        resourceConfigurations += ["en", "de", "fr", "es"]
    }
}
android {
    defaultConfig {
        resourceConfigurations += listOf("en", "de", "fr", "es")
    }
}

For example: to add Hebrew language to the filtered list of language, you need to use iw.

App bundles

The Didomi SDK can be configured to restrict the languages it supports. If the user device language is not in the supported languages list, and app is distributed with Android App Bundles on the play store, it is possible that texts are removed from the downloaded app. In this case, all the texts will be displayed in english, except the custom texts.

To avoid this behavior, it is possible to either

  • disable the splitting by language in App Bundle configuration.

Disable splitting by language

android {
    bundle {
        language {
            enableSplit = false
        }
    }
}

Get missing language through Install Manager

private lateinit var splitInstallManager: SplitInstallManager

override fun attachBaseContext(newBase: Context) {
    super.attachBaseContext(newBase)
    splitInstallManager = SplitInstallManagerFactory.create(newBase)
    SplitCompat.installActivity(this)
}

private fun onLanguageChanged(languageCode) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP && !splitInstallManager.installedLanguages.contains(languageCode)) {
        // Creates a request to download and install additional language resources.
        val request = SplitInstallRequest.newBuilder()
            // Uses the addLanguage() method to include needed language resources in the request.
            .addLanguage(Locale.forLanguageTag(languageCode))
            .build()

        // Submits the request to install the additional language resources.
        splitInstallManager
            .startInstall(request)
            .addOnFailureListener { (...) }
            .addOnCompleteListener { task ->
                if (task.isSuccessful) {
                    (...)
                    // Recreate activity so new language is available
                    recreate()
                }
            }
        return
    }
}

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.MultiDexApplication;
import android.util.Log;

import io.didomi.sdk.Didomi;

public class SampleApplication extends MultiDexApplication {
    @Override
    public void onCreate() {
        super.onCreate();

        try {
            Didomi.getInstance().initialize(
                this,
                new DidomiInitializeParameters(
                    /*apiKey*/ "<Your API key>",
                    /*localConfigurationPath*/ "<Your local config path>",
                    /*remoteConfigurationURL*/ "<Your remote config url>",
                    /*providerID*/ "<Your provider ID>",
                    /*disableDidomiRemoteConfig*/ true|false,
                    /*languageCode*/ "<Your language code>",
                    /*noticeID*/ "<Your notice ID>",
                    /*tvNoticeId*/ "<Your TV notice ID>",
                    /*androidTvEnabled*/ true|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);
        }
    }
}

package com.my.app

import android.util.Log
import androidx.multidex.MultiDexApplication
import io.didomi.sdk.Didomi
import io.didomi.sdk.DidomiInitializeParameters

class SampleApplication : MultiDexApplication() {

    override fun onCreate() {
        super.onCreate()
        try {
            Didomi.getInstance().initialize(
                this,
                DidomiInitializeParameters(
                    apiKey = "<Your API key>",
                    localConfigurationPath = "<Your local config path>",
                    remoteConfigurationURL = "<Your remote config url>",
                    providerID = "<Your provider ID>",
                    disableDidomiRemoteConfig = true|false,
                    languageCode = "<Your language code>",
                    noticeID = "<Your notice ID>"
                    tvNoticeId = "<Your TV notice ID>",
                    androidTvEnabled = true|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 (e: Exception) {
            Log.e("SampleApp", "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

Note: the setupUI method should be called only from your main/entry Activities which in most cases should be once per app launch.

You do not need to call onReady, isReady or shouldConsentBeCollected before calling setupUI because they are called internally. Therefore, by calling this method the consent notice and preference views will only be displayed if it is required and only once the SDK is ready.

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 androidx.fragment.app.FragmentActivity
import io.didomi.sdk.Didomi;

public class SampleActivity extends FragmentActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Didomi.getInstance().setupUI(this);
    }
}
package io.didomi.sample

import android.os.Bundle
import androidx.fragment.app.FragmentActivity
import io.didomi.sdk.Didomi

class SampleActivity : FragmentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        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.

For Jetpack compose, you will need to extend FragmentActivity instead of ComponentActivity.

Deep links

If you are using deep links or have multiple main activities in your app make sure that the setupUI function is called on every activity that the user can launch the app on. This will ensure that consent is always collected as needed and there is no path where the user can launch the app without consent being collected. If setupUI is missing at some entry points, you will see lower consent rates as users will be using the app without giving consent.

Configure the SDK

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

On Android TV / Fire TV, only Didomi Console option is enabled. Local and remote files configuration will be ignored.

From the Console (Recommended)

It is possible to disable this option by setting the disableDidomiRemoteConfig parameter to true . Default is false.

Didomi.getInstance().initialize(
    this,
    new DidomiInitializeParameters(
        /*apiKey*/ "<Your API key>",
        /*localConfigurationPath*/ null,
        /*remoteConfigurationURL*/ null,
        /*providerId*/ null,
        /*disableDidomiRemoteConfig*/ false
    )
);
Didomi.getInstance().initialize(
    this,
    DidomiInitializeParameters(
        apiKey = "<Your API key>",
        localConfigurationPath = null,
        remoteConfigurationURL = null,
        providerId = null,
        disableDidomiRemoteConfig = false
    )
)

The SDK will automatically use the remote configuration hosted by Didomi and cache it locally. The cached version is refreshed every 60 minutes.

Local file (deprecated)

Using a local file automatically disables the TCF integration. If your app uses the TCF, you must use a configuration from the Didomi Console.

Using a local file will prevent you to support multiple regulations.

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
    }
}
Didomi.getInstance().initialize(
    this,
    new DidomiInitializeParameters(
        /*apiKey*/ "<Your API key>",
        /*localConfigurationPath*/ null,
        /*remoteConfigurationURL*/ null,
        /*providerId*/ null,
        /*disableDidomiRemoteConfig*/ true
    )
);
Didomi.getInstance().initialize(
    this,
    DidomiInitializeParameters(
        apiKey = "<API key>",
        localConfigurationPath = null,
        remoteConfigurationURL = null,
        providerId = null,
        disableDidomiRemoteConfig = true
    )
)

Remote file

Using your own remote file automatically disable the TCF integration. If your app uses the TCF, you must use a configuration from the Didomi Console.

Enabling this option will prevent the configuration from being loaded from the Didomi Console.

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.

Didomi.getInstance().initialize(
    this,
    new DidomiInitializeParameters(
        /*apiKey*/ "<Your API key>",
        /*localConfigurationPath*/ null,
        /*remoteConfigurationURL*/ "https://www.website.com/didomi_config.json",
        /*providerId*/ null,
        /*disableDidomiRemoteConfig*/ false
    )
);
Didomi.getInstance().initialize(
    this,
    DidomiInitializeParameters(
        apiKey = "<Your API key>",
        localConfigurationPath = null,
        remoteConfigurationURL = "https://www.website.com/didomi_config.json",
        providerId = null,
        disableDidomiRemoteConfig = false
    )
)

Download Global Vendor List (GVL)

Since version 1.28.0 the GVL will be downloaded by default from our API before the SDK is initialized. If you want to stop this behavior, provide the app.vendors.iab.requireUpdatedGVL flat set to false in the CUSTOM JSON section when editing your notice on the Console app (or in your local didomi_config.json file if that's the case).

{
    "app": {
        "vendors": {
            "iab": {
                "requireUpdatedGVL": false
            }
        }
    }
}

A timeout can also be provided to specify a maximum timeout for the Download of the GVL. This can be done by providing the app.vendors.iab.updateGVLTimeout property (in seconds).

{
    "app": {
        "vendors": {
            "iab": {
                "updateGVLTimeout": 10
            }
        }
    }
}

If your project already uses several libraries, it is possible that by adding Didomi it reaches the limit of 64K references. In this case, it is necessary to enable multidex in your project:

Didomi SDK supports the following .

Note that the Hebrew (he) language code is rewritten as iw, Indonesian (id) as in, and Yiddish (yi) as ji (see for more information).

dynamically retrieve missing languages from Play Store through Install Manager, as described in Android developer doc:

: the SDK is configured remotely from the Didomi Console

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

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

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 .

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 call to set the disableDidomiRemoteConfig parameter to true:

Your SDK is now setup. to learn more about how to configure it to match your app UI and requirements.

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

Also see the for more information.

https://developer.android.com/studio/build/multidex#groovy
https://developer.android.com/reference/java/util/Locale.html#legacy-language-codes
https://developer.android.com/guide/playcore/feature-delivery/on-demand?hl=fr#lang_resources
here
Read the Getting started section
minimum required for Google Play
Requirements
Add the SDK to your project
Initialize the SDK
Setup the SDK UI
Configure the SDK
Didomi Console
Local file
Remote file
languages
initialize
initialize
reference documentation of the initialize function