Mobile SDK Integration Guide

Overview

This document describes how app developers should synchronize their Consent Management Platform (CMP) with the Utiq Mobile SDK consent state.

It is intended for developers integrating Utiq alongside a CMP such as Didomi, OneTrust, or another consent solution that manages vendor and purpose choices.

Flows to be implemented

if CMP consent exists for Utiq, call fetchIdConnectData(...) to get Utiq IDs
if CMP consent does not exist for Utiq, whether never given or revoked later, call rejectConsent(...) and do not call fetchIdConnectData(...)
if fetchIdConnectData(...) returns UserOptedOutFromUtiqException, switch off Utiq in the CMP
if consent is revoked via the Manage Utiq page/screen, switch off Utiq in the CMP and call rejectConsent(...)

What this means in practice

The CMP is the source of truth for Utiq consent in the app.

The app must keep the Utiq SDK aligned with the CMP:

CMP says Utiq is enabled: use fetchIdConnectData(...)
CMP says Utiq is disabled: call rejectConsent(...)
SDK says the user opted out in Utiq consenthub: update the CMP so Utiq is disabled there too
Manage Utiq page/screen is used to revoke Utiq: disable Utiq vendor/purpose in the CMP and call rejectConsent(...)

Recommended app behavior

When CMP consent exists for Utiq

The app should:

call fetchIdConnectData(...) when Utiq IDs are needed
use the returned values from dataCallback(...)

When CMP consent does not exist for Utiq

This includes:

the user rejected Utiq in the CMP
the user revoked previously granted consent in the CMP

The app should:

call rejectConsent(...)
clear any app state that depends on previously fetched Utiq IDs
do not call fetchIdConnectData(...)

When `fetchIdConnectData(...)` reports Utiq opt-out

If errorCallback(...) receives UserOptedOutFromUtiqException, the app should:

switch off Utiq in the CMP (reject Utiq purpose and vendor)
clear any app state that depends on previously fetched Utiq IDs

This is the main path for synchronizing a consent change that happened outside the app, for example through consenthub.

Minimal examples

Disclaimer: This integration examples below are directional, and come with owner of the app responsibility - so test thoroughly before going to production.

Android

KOTLIN

// Utiq consent exists in the CMP
Utiq.fetchIdConnectData(
    stubToken = stubToken, // <-- only for testing, DO NOT SET FOR PRODUCTION
    dataCallback = { ids ->
        renderIds(ids)
    },
    errorCallback = { error ->
        if (error is UserOptedOutFromUtiqException) {
            cmp.disableUtiq()
            clearUtiqUiState()
        }
    }
)

// Utiq consent is not given or was withdrawn
Utiq.rejectConsent(
    successCallback = {
        clearUtiqUiState()
    },
    errorCallback = { error ->
        showError(error.message)
    }
)

iOS

SWIFT

// Utiq consent exists in the CMP
Utiq.shared.fetchIdConnectData(
    dataCallback: { ids in
        self.renderIds(ids)
    },
    errorCallback: { error in
        let nsError = error as NSError
        if nsError.code == UserOptedOutFromUtiqException().code {
            self.cmp.disableUtiq()
            self.clearUtiqUiState()
        }
    }
)

// Utiq consent is not given or was withdrawn
Utiq.shared.rejectConsent(
    successCallback: {
        self.clearUtiqUiState()
    },
    errorCallback: { error in
        self.showError(error.localizedDescription)
    }
)

Error handling

Only one fetchIdConnectData(...) error should automatically update the CMP:

UserOptedOutFromUtiqException

Other errors are normally technical or eligibility errors and should not automatically switch off Utiq in the CMP.

App lifecycle note

The app may be resumed from memory or restarted from scratch when the user returns to it.

Because of this:

do not rely on in-memory state alone
always derive Utiq behavior from the current CMP consent state and current SDK state

Testing

The App SDK integration should be validated using the testing principles described here: Mobile SDK Testing Guide

Disclaimer

This guidance describes how to keep SDK and CMP states technically aligned. It does not replace the developer's responsibility to configure their CMP, vendor disclosures, purposes, legal text, and jurisdiction-specific consent experience in accordance with their legal and compliance requirements.