Android SDK

Installation

To add the SDK to your app, please follow these steps:

1. This guide covers the Mobile SDK v2.0.0 production release. Release details: https://github.com/UtiqTech/android-sdk/releases/tag/v2.0.0

2. Add the following dependency to your project’s build.gradle or settings.gradle file under the allprojects block

Groovy

allprojects {
   repositories {
      maven {
         url 'https://maven.pkg.github.com/UtiqTech/android-sdk'
         credentials {
            username = GITHUB_USERNAME
            password = GITHUB_TOKEN
         }
      }
   }
}

Kotlin DSL

allprojects {
   repositories {
       maven { 
          url = uri("https://maven.pkg.github.com/UtiqTech/android-sdk")
          credentials { 
             username = GITHUB_USERNAME
             password = GITHUB_TOKEN
          }
       }
   }
} 

2. Add this dependency com.utiq:utiq-android:2.0.0 to the build.gradle or build.gradle.kts file of your App or module.

3. Also, add the following permissions to your manifest file if you didn't' already.

<uses-permission android:name="android.permission.INTERNET"/>

4. Initialize the SDK

Basic initialization

Assuming you have an Application class registered in AndroidManifest.xml, call the initialize function inside onCreate(), passing the application context and the SDK token provided by us.

Kotlin

Utiq.initialize(this, SDK_TOKEN)

Java

Utiq.initialize(this, SDK_TOKEN);

Initializing with custom options

UtiqOptions() is an optional parameter for SDK initialization. You can initialize the SDK without it, but if you want to enable or disable specific options, configure them in UtiqOptions and pass it to the initializer.

Kotlin

val options = UtiqOptions().enableLogging()
Utiq.initialize(this, SDK_TOKEN, options)

Java

UtiqOptions options = new UtiqOptions().enableLogging();
Utiq.initialize(this, SDK_TOKEN, options);

java.lang.RuntimeException: Unable to get provider androidx.startup.InitializationProvider
Caused by: java.lang.RuntimeException: Failed to create an instance of class androidx.work.impl.WorkDatabase

-keep class androidx.work.** { *; }

Basic usage

Once the SDK is initialized, call its public functions through Utiq. In v2.0.0, fetchIDs() is the recommended identifier API and returns all available records. fetchIdConnectData() remains only as a deprecated single-record compatibility API and will be removed in a future release.

Fetch Utiq identifiers with fetchIDs

Kotlin

Utiq.fetchIDs(dataCallback = { ids ->
    ids.forEach { id -> println("mtid: ${id.mtid}, atid: ${id.atid}, attrid: ${id.attrid}, ttl: ${id.ttl}") }
}, errorCallback = { error ->
    error.printStackTrace()
})

Java

Utiq.fetchIDs(null, ids -> {
    ids.forEach(id -> System.out.println("mtid: " + id.getMtid() + ", atid: " + id.getAtid() + ", attrid: " + id.getAttrid() + ", ttl: " + id.getTtl()));
} , error -> {
    error.printStackTrace();
});

Kotlin

Utiq.fetchIDs(dataCallback = { ids ->
    ids.forEach { id -> println("mtid: ${id.mtid}, atid: ${id.atid}, attrid: ${id.attrid}, ttl: ${id.ttl}") }
}, errorCallback = { error ->
    error.printStackTrace()
})

Java

Utiq.fetchIDs(null, ids -> {
    ids.forEach(id -> System.out.println("mtid: " + id.getMtid() + ", atid: " + id.getAtid() + ", attrid: " + id.getAttrid() + ", ttl: " + id.getTtl()));
} , error -> {
    error.printStackTrace();
});

Utiq Consent

The SDK does not provide a built-in consent dialog. Your application must collect user consent using either a standard Consent Management Platform (CMP) or a custom pop-up that matches your app's look and feel.

User consent for the Utiq technology must be in place before calling fetchIDs().

Reject consent

Kotlin

Utiq.rejectConsent()

Java

Utiq.rejectConsent(null, null);

You don’t need to provide success/failure closures, unless you want to log the outcome.

Kotlin

Utiq.rejectConsent(successCallback = { ... }, errorCallback = { error -> ... })

Java

Utiq.rejectConsent(() -> { ... }, error -> { ... });

consenthub URL

If you need to access the ConsentHub URL from within the mobile app (for example, in a web view), you can do so by calling the function that returns the ConsentHub URL.

Kotlin

val consentHubUrl = Utiq.getConsentHubUrl()

Java

try {
    String consentHubUrl = Utiq.getConsentHubUrl(null);
} catch (Throwable error) {
    // Handle the error
}

Error handling

Functions with callbacks described in the previous sections include both success and failure callbacks (or closures). APIs declared as throwing, including the ConsentHub URL function, report synchronous failures directly and must be handled using the platform's exception-handling mechanism. The failure callback returns a custom error that is specific to the function. You can use this error to take a defined action based on the error type. APIs declared as throwing, including the ConsentHub URL function, report synchronous failures directly and must be handled using the platform's exception-handling mechanism.

Support and bug reporting

If you have suggestions, want to report a bug, or have any other inquiries, please contact onboard@utiq.com