> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AAID Provider

> Automatically identify users by Android Advertising ID

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

<CardGroup cols={4}>
  <Card title="Setup" href="#basic-setup" icon="gear" />

  <Card title="Permissions" href="#required-permissions-android-api-31" icon="lock" />

  <Card title="Privacy" href="#privacy-considerations" icon="shield-halved" />

  <Card title="Issues" href="#troubleshooting" icon="wrench" />
</CardGroup>

## 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

1. **Google Ads add-on** installed
2. **Google Play Services** on device
3. **AD\_ID permission** (Android API 31+)

***

## Installation

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

```kotlin theme={"dark"}
dependencies {
    implementation("com.permutive.android:core:1.11.3")
    implementation("com.permutive.android:google-ads:2.2.0")  // Includes AaidAliasProvider
}
```

See [Installation Guide](/sdks/mobile/android/getting-started/installation) for details.

***

## Basic Setup

### Add AaidAliasProvider at Initialization

Add the `AaidAliasProvider` when creating your Permutive instance:

<CodeGroup>
  ```kotlin Kotlin theme={"dark"}
  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
          )
      }
  }
  ```

  ```java Java theme={"dark"}
  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;
      }
  }
  ```
</CodeGroup>

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

***

## Required Permissions (Android API 31+)

### Add AD\_ID Permission

From Android API 31 (Android 12) and later, the `AD_ID` permission is required to access the AAID.

Add this to your `AndroidManifest.xml`:

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

<Warning>
  **Important for Android 12+**

  Without the `AD_ID` permission on Android API 31+, the `AaidAliasProvider` will not work correctly. The AAID will not be captured.
</Warning>

### 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:

1. **On initialization** - AAID is retrieved from Google Play Services
2. **Async retrieval** - ID fetched in background (non-blocking)
3. **Auto-set identity** - AAID automatically set as user alias
4. **Tag created** - Stored with tag `"aaid"`
5. **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

```kotlin theme={"dark"}
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:

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

### AAID + Multiple Custom Aliases

```kotlin theme={"dark"}
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](/sdks/mobile/android/core-concepts/identity-management) for more on multiple identities.

***

## Verification

### Verify AAID is Set

Enable debug logging to verify AAID is captured:

```kotlin theme={"dark"}
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:

```kotlin theme={"dark"}
// This is internal API - use debug logs instead
// But for verification in tests:
// Check that events include AAID in aliases
```

See [Verification Guide](/sdks/mobile/android/getting-started/verification) for complete verification steps.

***

## Use Cases

### Anonymous User Tracking

For apps without user login, AAID provides persistent tracking:

```kotlin theme={"dark"}
// 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:

```kotlin theme={"dark"}
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:

```kotlin theme={"dark"}
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

### GDPR Compliance

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

```kotlin theme={"dark"}
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:

```kotlin theme={"dark"}
permutive.clearPersistentData()
```

This removes:

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

See [Identity Management](../core-concepts/identity-management.mdx#removing-persistent-data).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="AAID Not Being Set">
    **Problem:** AAID not appearing in events.

    **Causes:**

    1. Google Ads add-on not installed
    2. `AaidAliasProvider` not added to Permutive
    3. Missing `AD_ID` permission (Android 12+)
    4. Google Play Services not available
    5. User opted out of ad personalization

    **Solutions:**

    1. Verify `google-ads:2.2.0` is in dependencies
    2. Add `AaidAliasProvider` to `aliasProviders` list
    3. Add `AD_ID` permission to manifest (Android 12+)
    4. Test on device with Google Play Services
    5. Check user's ad personalization settings
    6. Enable debug logging to see AAID capture attempts
  </Accordion>

  <Accordion title="Permission Denied (Android 12+)">
    **Problem:** Error about AD\_ID permission.

    **Cause:** `AD_ID` permission not declared.

    **Solution:** Add to `AndroidManifest.xml`:

    ```xml theme={"dark"}
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
    ```
  </Accordion>

  <Accordion title="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:**

    1. Implement fallback identification method
    2. Use custom identity instead
    3. Check Play Services availability:

    ```kotlin theme={"dark"}
    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
    }
    ```
  </Accordion>

  <Accordion title="AAID Changes Unexpectedly">
    **Problem:** AAID changes unexpectedly.

    **Causes:**

    1. User reset advertising ID in settings
    2. Factory reset
    3. App reinstalled

    **This is expected behavior.** AAID can change, and your implementation should handle this gracefully.

    See [Common Errors](/sdks/mobile/android/troubleshooting/common-errors) for more troubleshooting.
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Tabs>
  <Tab title="Do">
    * Add `AaidAliasProvider` at SDK initialization
    * Declare `AD_ID` permission for Android 12+
    * Obtain user consent before capturing AAID (GDPR)
    * Combine AAID with other identifiers for robustness
    * Handle Google Play Services unavailability
    * Respect user opt-out preferences
  </Tab>

  <Tab title="Don't">
    * Use AAID without user consent (GDPR)
    * Forget `AD_ID` permission on Android 12+
    * Rely solely on AAID (can change or be unavailable)
    * Assume AAID is always available
    * Ignore user opt-out preferences
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Google Ad Manager" icon="google" href="/sdks/mobile/android/integrations/google-ad-manager">
    Use AAID with GAM
  </Card>

  <Card title="Identity Management" icon="fingerprint" href="/sdks/mobile/android/core-concepts/identity-management">
    Multiple identities
  </Card>

  <Card title="Initialization" icon="gear" href="/sdks/mobile/android/getting-started/initialization">
    SDK setup
  </Card>

  <Card title="Verification" icon="check" href="/sdks/mobile/android/getting-started/verification">
    Verify AAID capture
  </Card>

  <Card title="Issues" icon="wrench" href="/sdks/mobile/android/troubleshooting/common-errors">
    Solve common issues
  </Card>
</CardGroup>

***

## API Reference

For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html).

### AaidAliasProvider

* `AaidAliasProvider(context: Context)` - Creates AAID alias provider

### Usage in Permutive

**Kotlin:**

```kotlin theme={"dark"}
Permutive(
    context = ...,
    workspaceId = ...,
    apiKey = ...,
    aliasProviders = listOf(AaidAliasProvider(context))
)
```

**Java:**

```java theme={"dark"}
new Permutive.Builder()
    .context(context)
    .workspaceId(workspaceId)
    .apiKey(apiKey)
    .aliasProvider(new AaidAliasProvider(context))
    .build()
```

***

## Getting Help

If you encounter issues with AAID:

1. Check [Troubleshooting Guide](/sdks/mobile/android/troubleshooting/common-errors)
2. Verify Google Ads add-on is installed
3. Confirm `AD_ID` permission is declared (Android 12+)
4. Enable debug logging
5. Test on device with Google Play Services
6. Contact your Customer Success Manager

For Google Play Services issues, consult [Google's documentation](https://developers.google.com/android/guides/overview).