DataGrail Consent Android SDK

Beta Feature

Mobile App Consent Management is in beta for select customers and prospects. Please contact your Account Manager or support@datagrail.io for more information.

The DataGrail Consent Android SDK provides a fully native Kotlin implementation for managing user consent preferences in your Android applications. This guide covers installation, configuration, and usage of the SDK.

Requirements

• Android API 21 (Android 5.0 Lollipop) or later
• Kotlin 1.9 or later
• Gradle 8.0 or later

Installation

Add the SDK to your Android project using Gradle and configure the required permissions.

Gradle

Add the DataGrail Consent SDK to your app's build.gradle.kts:

dependencies {
    implementation("com.datagrail:consent:1.0.0")
}

Then sync your project.

Permissions

Add the internet permission to your AndroidManifest.xml:

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

Quick Start

Follow these steps to get the Android SDK running in your app.

Initialize the SDK

Initialize the SDK early in your app's lifecycle, typically in your Application class:

import android.app.Application
import com.datagrail.consent.DataGrailConsent

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        DataGrailConsent.getInstance().initialize(
            context = this,
            configUrl = "https://api.consent.datagrail.io/config/YOUR_CONFIG_ID.json"
        ) { result ->
            result.fold(
                onSuccess = {
                    Log.d("Consent", "SDK initialized")
                },
                onFailure = { error ->
                    Log.e("Consent", "Failed to initialize: ${error.message}")
                }
            )
        }
    }
}

Don't forget to register your application class in AndroidManifest.xml:

<application
    android:name=".MyApplication"
    ...>

Check if Consent is Needed

Before showing the consent banner, check if the user needs to provide consent:

if (DataGrailConsent.getInstance().needsConsent()) {
    // Show consent banner
}

Show The Consent Banner

Display the native consent banner dialog to collect user preferences:

DataGrailConsent.getInstance().showBanner(activity) { preferences ->
    if (preferences != null) {
        // User made a choice
        Log.d("Consent", "User consented to ${preferences.cookieOptions.size} categories")
    } else {
        // User dismissed without saving
    }
}

You can also specify a display style:

// Full screen style
DataGrailConsent.getInstance().showBanner(
    activity = this,
    style = BannerDisplayStyle.FULL_SCREEN
) { preferences ->
    // Handle result
}

// Modal style (default)
DataGrailConsent.getInstance().showBanner(
    activity = this,
    style = BannerDisplayStyle.MODAL
) { preferences ->
    // Handle result
}

Listen For Consent Changes

Register a callback to be notified when consent preferences change:

DataGrailConsent.getInstance().onConsentChanged { preferences ->
    // Update your tracking configuration
    updateTrackingBasedOnConsent(preferences)
}

API Reference

The Android SDK provides the following methods for managing consent in your application.

Initialization

fun initialize(
    context: Context,
    configUrl: String,
    callback: (Result<Unit>) -> Unit
)

Initializes the SDK with your configuration URL. Call this once when your app starts.

Consent Status

fun needsConsent(): Boolean

Returns true if the user needs to provide consent (no valid consent on file or consent has expired).

Get Current Preferences

fun getPreferences(): ConsentPreferences?

Returns the user's current consent preferences, or null if none have been saved.

Save Preferences

fun savePreferences(
    preferences: ConsentPreferences,
    callback: (Result<Unit>) -> Unit
)

Saves consent preferences locally and syncs with the backend.

Quick Actions

// Accept all categories
fun acceptAll(callback: (Result<Unit>) -> Unit)

// Reject all non-essential categories
fun rejectAll(callback: (Result<Unit>) -> Unit)

Category Checks

fun isCategoryEnabled(categoryKey: String): Boolean

Check if a specific consent category is enabled:

if (DataGrailConsent.getInstance().isCategoryEnabled("category_marketing")) {
    // Initialize marketing SDKs
}

if (DataGrailConsent.getInstance().isCategoryEnabled("category_analytics")) {
    // Initialize analytics
}

Show Banner UI

fun showBanner(
    activity: FragmentActivity,
    style: BannerDisplayStyle = BannerDisplayStyle.MODAL,
    completion: (ConsentPreferences?) -> Unit
)

Display the native consent banner dialog. The completion handler receives the saved preferences, or null if the user dismissed without saving.

Consent Change Notifications

fun onConsentChanged(callback: (ConsentPreferences) -> Unit)

Register a callback to be notified whenever consent preferences change.

Reset

fun reset()

Clears all stored consent data. Useful for testing or when a user logs out.

Integration Patterns

These patterns demonstrate common ways to integrate the SDK into your application architecture.

Delayed Tracking Initialization

Wait for consent before initializing tracking SDKs:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        DataGrailConsent.getInstance().initialize(this, configUrl) { result ->
            if (result.isSuccess) {
                initializeTrackingIfAllowed()
            }
        }

        DataGrailConsent.getInstance().onConsentChanged {
            initializeTrackingIfAllowed()
        }
    }

    private fun initializeTrackingIfAllowed() {
        if (DataGrailConsent.getInstance().isCategoryEnabled("category_analytics")) {
            // Initialize analytics SDK
        }

        if (DataGrailConsent.getInstance().isCategoryEnabled("category_marketing")) {
            // Initialize marketing SDK
        }
    }
}

Consent Wall

Block app functionality until consent is provided:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        if (DataGrailConsent.getInstance().needsConsent()) {
            showConsentWall()
        } else {
            proceedToMainApp()
        }
    }

    private fun showConsentWall() {
        DataGrailConsent.getInstance().showBanner(this) { preferences ->
            if (preferences != null) {
                proceedToMainApp()
            } else {
                // User must provide consent - show wall again or exit
                showConsentWall()
            }
        }
    }

    private fun proceedToMainApp() {
        // Continue with normal app flow
    }
}

Settings Screen Integration

Allow users to manage their preferences from app settings:

binding.managePrivacyButton.setOnClickListener {
    DataGrailConsent.getInstance().showBanner(this) { preferences ->
        if (preferences != null) {
            Toast.makeText(this, "Preferences updated", Toast.LENGTH_SHORT).show()
        }
    }
}

Accessibility

The SDK provides full TalkBack support:

• All UI elements include content descriptions
• Proper importance flags ensure correct focus management
• Toggle states are announced with context (e.g., "Marketing consent - Enabled")
• Clear action hints describe what buttons and links do

Offline Support

The SDK automatically handles offline scenarios:

• Consent preferences are saved locally first (SharedPreferences)
• Failed backend syncs are queued and retried automatically
• Exponential backoff retry (5 attempts, 250ms base delay)
• Manual retry available via retryPendingRequests()

Running the Demo App

A demo app is included to help you explore the SDK:

cd mobile/android
./launch_demo.sh

Or manually using Android Studio:

1. Open the mobile/android directory in Android Studio
2. Select the demo run configuration
3. Choose an emulator or connected device
4. Click Run

Or via command line:

cd mobile/android
./gradlew :demo:installDebug
adb shell am start -n com.datagrail.consent.demo/.MainActivity

Troubleshooting

Common issues and how to resolve them.

SDK Not Initializing

• Verify the config URL is valid HTTPS
• Check that INTERNET permission is in your manifest
• Review Logcat for JSON parsing errors

Banner Not Showing

• Ensure needsConsent() returns true
• Verify showBanner is set to true in your config
• Check that you're passing a FragmentActivity (not a plain Activity)

Preferences Not Persisting

• Verify savePreferences() callback shows success
• Check backend connectivity
• Review offline queue with retryPendingRequests()

ProGuard / R8

If you're using code shrinking, add these rules to your proguard-rules.pro:

-keep class com.datagrail.consent.** { *; }
-keepclassmembers class com.datagrail.consent.models.** { *; }

Next Steps

• Review the Configuration Guide for config.json options
• Explore common integration patterns
• Check the API Reference for all available methods