AAID Provider - Permutive

The AAID (Android Advertising ID) provider automatically identifies users by their Android Advertising ID. This is available through the Google Ads add-on library.

Setup

Permissions

Privacy

Issues

Overview

The AaidAliasProvider provides:

Automatic AAID capture - No manual ID retrieval needed
Persistent identification - User tracking across app sessions
Privacy compliant - Respects user opt-out preferences
Zero maintenance - Automatically updates when AAID changes

Prerequisites

Google Ads add-on installed
Google Play Services on device
AD_ID permission (Android API 33+)

Installation

The AAID provider is included in the Google Ads add-on:

dependencies {
    implementation("com.permutive.android:core:1.12.1")
    implementation("com.permutive.android:google-ads:2.2.0")  // Includes AaidAliasProvider
}

See Installation Guide for details.

Basic Setup

Add AaidAliasProvider at Initialization

Add the AaidAliasProvider when creating your Permutive instance:

import android.app.Application
import com.permutive.android.Permutive
import com.permutive.android.aaid.AaidAliasProvider

class MyApplication : Application() {

    val permutive by lazy {
        Permutive(
            context = this,
            workspaceId = YOUR_WORKSPACE_ID,
            apiKey = YOUR_API_KEY,
            aliasProviders = listOf(AaidAliasProvider(this))  // Add AAID provider
        )
    }
}

import android.app.Application;
import com.permutive.android.Permutive;
import com.permutive.android.aaid.AaidAliasProvider;

public class MyApplication extends Application {

    private Permutive permutive;

    public Permutive getPermutive() {
        if (permutive == null) {
            synchronized (this) {
                if (permutive == null) {
                    permutive = new Permutive.Builder()
                        .context(this)
                        .workspaceId(YOUR_WORKSPACE_ID)
                        .apiKey(YOUR_API_KEY)
                        .aliasProvider(new AaidAliasProvider(this))  // Add AAID provider
                        .build();
                }
            }
        }
        return permutive;
    }
}

That’s it! The AAID will now be automatically captured and set as a user identity.

Required Permissions (Android API 33+)

Add AD_ID Permission

From Android 13 (API 33) and later, the AD_ID permission is required to access the AAID. Add this to your AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">
    
    <!-- Required for AAID on Android 13+ -->
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
    
    <application
        ...>
        ...
    </application>
</manifest>

Important for Android 13+Without the AD_ID permission on Android API 33+, the AAID is returned as all zeros (00000000-0000-0000-0000-000000000000) and the AaidAliasProvider will not capture it.

Checking Permission Status

The permission is automatically granted - no runtime permission request needed. However, users can opt out of ad tracking in their device settings.

How It Works

Automatic ID Capture

When AaidAliasProvider is added:

On initialization - AAID is retrieved from Google Play Services
Async retrieval - ID fetched in background (non-blocking)
Auto-set identity - AAID automatically set as user alias
Tag created - Stored with tag "aaid"
Persisted - AAID saved for future sessions

Alias Details

The AAID is stored as an alias with:

Tag: "aaid"
Identity: The advertising ID (e.g., "38400000-8cf0-11bd-b23e-10b96e40000d")
Priority: 0 (default)
Expiry: Never (unless manually cleared)

User Opt-Out Handling

If a user opts out of ad personalization in device settings:

The AAID provider will receive a zeroed-out ID
This zeroed-out ID will not be set as an alias
Permutive will use the default anonymous ID instead

Combining with Other Identities

You can use AAID alongside other identity methods:

AAID + Custom Identity

val permutive = Permutive(
    context = this,
    workspaceId = YOUR_WORKSPACE_ID,
    apiKey = YOUR_API_KEY,
    identity = "user_12345",  // Your internal user ID
    aliasProviders = listOf(AaidAliasProvider(this))  // + AAID
)

Now the user has two identities:

Custom identity: "user_12345" (tag: "user_id")
AAID: "38400000-8cf0-11bd-b23e-10b96e40000d" (tag: "aaid")

AAID + Multiple Custom Aliases

import com.permutive.android.Alias

val permutive = Permutive(
    context = this,
    workspaceId = YOUR_WORKSPACE_ID,
    apiKey = YOUR_API_KEY,
    customAliases = listOf(
        Alias.create(
            tag = "email_sha256",
            identity = hashSHA256(userEmail),
            priority = 0
        ),
        Alias.create(
            tag = "internal_id",
            identity = "user_12345",
            priority = 1
        )
    ),
    aliasProviders = listOf(AaidAliasProvider(this))  // + AAID
)

See Identity Management for more on multiple identities.

Verification

Verify AAID is Set

Enable debug logging to verify AAID is captured:

permutive.setDeveloperMode(true)

Look for logs like:

D/Permutive: Setting identity with tag: aaid, value: 38400000-8cf0-11bd-b23e-10b96e40000d

Check Current Identities

You can programmatically check if AAID is set:

// This is internal API - use debug logs instead
// But for verification in tests:
// Check that events include AAID in aliases

See Verification Guide for complete verification steps.

Use Cases

Anonymous User Tracking

For apps without user login, AAID provides persistent tracking:

// No custom identity - just AAID
val permutive = Permutive(
    context = this,
    workspaceId = YOUR_WORKSPACE_ID,
    apiKey = YOUR_API_KEY,
    aliasProviders = listOf(AaidAliasProvider(this))
)

User is identified by AAID across app launches and sessions.

Logged-In User + AAID

For apps with user accounts, combine both:

class MyApplication : Application() {
    
    val permutive by lazy {
        Permutive(
            context = this,
            workspaceId = YOUR_WORKSPACE_ID,
            apiKey = YOUR_API_KEY,
            aliasProviders = listOf(AaidAliasProvider(this))
        )
    }
    
    fun onUserLoggedIn(userId: String) {
        // Add user ID as additional identity
        permutive.setIdentity(
            tag = "internal_user_id",
            identity = userId
        )
    }
    
    fun onUserLoggedOut() {
        // AAID remains, but remove user ID
        // (User is still tracked via AAID)
    }
}

Cross-Device Tracking

AAID is device-specific. For cross-device tracking, combine with email or other identifiers:

fun onUserLoggedIn(email: String) {
    permutive.setIdentity(
        tag = "email_sha256",
        identity = hashSHA256(email)
    )
    // Now user has both AAID (device) and email hash (cross-device)
}

Privacy Considerations

AAID is considered personal data under GDPR. Ensure:

✅ User consent obtained before initialization
✅ Privacy policy explains AAID usage
✅ User can opt out via device settings
✅ Data can be deleted on request

class MyApplication : Application() {
    
    private var _permutive: Permutive? = null
    
    val permutive: Permutive?
        get() = _permutive
    
    fun onConsentGranted() {
        if (_permutive == null) {
            _permutive = Permutive(
                context = this,
                workspaceId = YOUR_WORKSPACE_ID,
                apiKey = YOUR_API_KEY,
                aliasProviders = listOf(AaidAliasProvider(this))  // Only after consent
            )
        }
    }
}

Contact your Customer Success Manager for details on GDPR compliance.

User Opt-Out

Users can opt out of ad personalization in:

Settings → Google → Ads → Opt out of Ads Personalization

When opted out:

AAID is zeroed out (00000000-0000-0000-0000-000000000000)
AaidAliasProvider will not set this as an identity
Permutive uses anonymous ID instead

Data Deletion

To clear all user data including AAID:

permutive.clearPersistentData()

This removes:

All identities (including AAID)
All event data
All cohort information

See Identity Management.

Troubleshooting

AAID Not Being Set

Problem: AAID not appearing in events.Causes:

Google Ads add-on not installed
AaidAliasProvider not added to Permutive
Missing AD_ID permission (Android 13+)
Google Play Services not available
User opted out of ad personalization

Solutions:

Verify google-ads:2.2.0 is in dependencies
Add AaidAliasProvider to aliasProviders list
Add AD_ID permission to manifest (Android 13+)
Test on device with Google Play Services
Check user’s ad personalization settings
Enable debug logging to see AAID capture attempts

Permission Denied (Android 13+)

Problem: Error about AD_ID permission.Cause: AD_ID permission not declared.Solution: Add to AndroidManifest.xml:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Google Play Services Not Available

Problem: AAID cannot be retrieved.Cause: Device doesn’t have Google Play Services (e.g., some devices in China).Solutions:

Implement fallback identification method
Use custom identity instead
Check Play Services availability:

val availability = GoogleApiAvailability.getInstance()
val resultCode = availability.isGooglePlayServicesAvailable(context)
if (resultCode == ConnectionResult.SUCCESS) {
    // Play Services available - AAID will work
} else {
    // Play Services not available - use fallback
}

AAID Changes Unexpectedly

Problem: AAID changes unexpectedly.Causes:

User reset advertising ID in settings
Factory reset
App reinstalled

This is expected behavior. AAID can change, and your implementation should handle this gracefully.See Common Errors for more troubleshooting.

Best Practices

Do
Don't

Add AaidAliasProvider at SDK initialization
Declare AD_ID permission for Android 13+
Obtain user consent before capturing AAID (GDPR)
Combine AAID with other identifiers for robustness
Handle Google Play Services unavailability
Respect user opt-out preferences

Use AAID without user consent (GDPR)
Forget AD_ID permission on Android 13+
Rely solely on AAID (can change or be unavailable)
Assume AAID is always available
Ignore user opt-out preferences

Google Ad Manager

Use AAID with GAM

Identity Management

Multiple identities

Initialization

SDK setup

Verification

Verify AAID capture

Issues

Solve common issues

API Reference

For complete API documentation, see the Javadocs.

AaidAliasProvider

AaidAliasProvider(context: Context) - Creates AAID alias provider

Usage in Permutive

Kotlin:

Permutive(
    context = ...,
    workspaceId = ...,
    apiKey = ...,
    aliasProviders = listOf(AaidAliasProvider(context))
)

Java:

new Permutive.Builder()
    .context(context)
    .workspaceId(workspaceId)
    .apiKey(apiKey)
    .aliasProvider(new AaidAliasProvider(context))
    .build()

Getting Help

If you encounter issues with AAID:

Check Troubleshooting Guide
Verify Google Ads add-on is installed
Confirm AD_ID permission is declared (Android 13+)
Enable debug logging
Test on device with Google Play Services
Contact your Customer Success Manager

For Google Play Services issues, consult Google’s documentation.

Setup

Permissions

Privacy

Issues

​Overview

​Prerequisites

​Installation

​Basic Setup

​Add AaidAliasProvider at Initialization

​Required Permissions (Android API 33+)

​Add AD_ID Permission

​Checking Permission Status

​How It Works

​Automatic ID Capture

​Alias Details

​User Opt-Out Handling

​Combining with Other Identities

​AAID + Custom Identity

​AAID + Multiple Custom Aliases

​Verification

​Verify AAID is Set

​Check Current Identities

​Use Cases

​Anonymous User Tracking

​Logged-In User + AAID

​Cross-Device Tracking

​Privacy Considerations

​GDPR Compliance

​User Opt-Out

​Data Deletion

​Troubleshooting

​Best Practices

​Related Documentation

Google Ad Manager

Identity Management

Initialization

Verification

Issues

​API Reference

​AaidAliasProvider

​Usage in Permutive

​Getting Help

Overview

Prerequisites

Installation

Basic Setup

Add AaidAliasProvider at Initialization

Required Permissions (Android API 33+)

Add AD_ID Permission

Checking Permission Status

How It Works

Automatic ID Capture

Alias Details

User Opt-Out Handling

Combining with Other Identities

AAID + Custom Identity

AAID + Multiple Custom Aliases

Verification

Verify AAID is Set

Check Current Identities

Use Cases

Anonymous User Tracking

Logged-In User + AAID

Cross-Device Tracking

Privacy Considerations

GDPR Compliance

User Opt-Out

Data Deletion

Troubleshooting

Best Practices

Related Documentation

API Reference

AaidAliasProvider

Usage in Permutive

Getting Help