UMPUtils

UMPUtils is an Android library supporting Google's User Messaging Platform (UMP) with functionality not offered by UMP itself.

Usage

Check the level of consent given by users of your app:

// provide a bit string containing all vendors used by your ad setup
val targetVendorConfiguration = BitString("11001001")

// get an interpretation of the currently stored consent data
val interpretation = UMPUtility.interpretConfiguration(context, targetVendorConfiguration)

if (interpretation.userDidNotConsent) {
    // do something if the user likely clicked "Do not consent" in the UMP dialog
}

if (interpretation.adDisplayLikely) {
    // based on user consent, it is likely that ads can be shown
} else if (interpretation.adDisplayPossible) {
    // user did not decline completely, but trying to display ads will likely result in "no fills" most of the time
}

or check for individual ad types:

val targetVendorConfiguration = BitString("11001001") //
val interpretation = UMPUtility.interpretConfiguration(context, targetVendorConfiguration)

when (interpretation.adLevel) {
    ConsentInterpretation.AdLevel.PERSONALIZED -> {
        // displaying personalized ads should be possible
    }

    ConsentInterpretation.AdLevel.NON_PERSONALIZED -> {
        // at most displaying non-personalized ads should be possible
    }

    ConsentInterpretation.AdLevel.LIMITED -> {
        // at most displaying limited ads should be possible
    }
    
    else -> {
        // no ads can be displayed
    }
}

Use the consent status as cached by UMP boiled down to a simple boolean:

if (UMPUtility.consentDialogDisplayNecessary(context)) {
    // dialog needs to be displayed to the user, because consent status is either UNKNOWN or REQUIRED
} else {
    // display unnecessary, consent status is either NOT_REQUIRED or already OBTAINED
}

or alternatively:

val statusInt = UMPUtility.getPreviousConsentStatus(context)

when (statusInt) {
    ConsentInformation.ConsentStatus.UNKNOWN -> {
        // no information stored; default value used by UMP
    }
    
    ConsentInformation.ConsentStatus.NOT_REQUIRED -> {
        // value used by UMP if user does NOT need to see UMP dialog (i.e. they are outside EEA/UK)
    }
    
    ConsentInformation.ConsentStatus.REQUIRED -> {
        // value used by UMP if user does need to see UMP dialog
    }
    
    ConsentInformation.ConsentStatus.OBTAINED -> {
        // value used by UMP if user previously saw UMP dialog
    }
}

Get the consent age in days:

val ageInDays: Long = UMPUtility.getConsentAgeInDays(context)

if (ageInDays > 365L) {
    // do something if consent is older than a year
}

Delete all consent data, for example if you stop using UMP, or because an age check determined that the consent is outdated:

UMPUtility.deleteAllConsentData(context)

Warning: Calling this function will remove all entries with keys having an "IABTCF_" prefix from the default shared preferences of the app. Make sure that none of your own entries use matching keys.

Legalese

Google, AdMob, Android and other names related to their products are trademarked by Google LLC. These names are necessarily used in this repository to reference the individual products. No trademark infringement is intended. This repository is not endorsed by or affiliated with Google in any way.

License

All original content in this repository is published under the CC0 1.0 Universal license. You can find the full legal text in the LICENSE file of this repository - but what it means in a nutshell is that you can use code in this repository however you like, including in commercial products, but without any warranties of any kind.

When doing so, you do not need to mention me or this repository in your finished product (e.g. an "About" screen in your app). However, if you consider any of the workarounds published here to be useful, feel free to raise awareness about these issues by sharing this repository with friends and colleagues. If you like, you can always buy me a coffee for the next time I'm working on this: