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

# Migration Guide: v1.12.x

> Upgrade to Permutive Android SDK v1.12.x and opt into config-driven automatic ID collection

This guide covers upgrading to Permutive Android SDK v1.12.x, which introduces **config-driven automatic ID collection**. When enabled for your workspace, the SDK automatically collects the user's Android Advertising ID (AAID) and IP address as identity aliases — with no provider code required.

<Info>
  **Migration Difficulty:** Easy | **Estimated Time:** 15 minutes | **Breaking Changes:** None
</Info>

## What's New in v1.12.0

<CardGroup cols={2}>
  <Card title="Automatic AAID collection" icon="fingerprint">
    The SDK captures the AAID as an `aaid` alias when enabled in your workspace config — no `AaidAliasProvider` needed
  </Card>

  <Card title="Automatic IP collection" icon="globe">
    The SDK captures the user's IP as an `ip_address` alias from an internal endpoint — no app changes required
  </Card>
</CardGroup>

<Check>
  **Good news:** This release is fully backward compatible with no breaking changes or deprecations. Automatic collection is **off by default** and is enabled remotely through your dashboard.
</Check>

## How Automatic ID Collection Works

Collection is driven by your workspace configuration, not by app code. Once you enable it for your workspace in the dashboard, the SDK picks it up on its next config refresh.

<AccordionGroup>
  <Accordion title="AAID collection" icon="fingerprint">
    * Stored as an alias with tag **`aaid`**, the priority defined in your config, and no expiry.
    * **Re-fetched on each new session** to detect Limit Ad Tracking changes, AAID resets, and priority changes from the server config.
    * If the user has **Limit Ad Tracking** enabled, no alias is stored and any existing `aaid` alias is cleared.
    * If an alias with the same tag, value, and priority already exists (from a previous auto-collection **or** a manual [`AaidAliasProvider`](/sdks/mobile/android/integrations/aaid-provider)), storage is skipped to avoid duplicates.
  </Accordion>

  <Accordion title="IP address collection" icon="globe">
    * Stored as an alias with tag **`ip_address`**, the priority defined in your config, and no expiry.
    * Retrieved from Permutive's internal endpoint and updated when the IP changes.
    * **No app or manifest changes are required** for IP collection.
  </Accordion>
</AccordionGroup>

## Standard Upgrade

Upgrading the SDK requires only a dependency bump. Update your `build.gradle.kts` or `build.gradle` to the v1.12.x core:

<Tabs>
  <Tab title="Before (v1.11.x)">
    ```kotlin theme={"dark"}
    dependencies {
        implementation("com.permutive.android:core:1.11.3")
    }
    ```
  </Tab>

  <Tab title="After (v1.12.0)">
    ```kotlin theme={"dark"}
    dependencies {
        implementation("com.permutive.android:core:1.12.0")
    }
    ```
  </Tab>
</Tabs>

Then sync and rebuild:

```bash theme={"dark"}
./gradlew clean build
```

Add-on libraries (`google-ads`, `appnexus`) are unaffected by this release. Automatic collection stays **off** until you enable it for your workspace in the dashboard, so no further changes are needed to complete the upgrade.

## Opting Into AAID Collection

<Warning>
  The steps below are **only required if you opt into automatic AAID collection**. They do not apply to a standard version upgrade, and they are not needed for automatic IP address collection (which requires no app or manifest changes).
</Warning>

<Steps>
  <Step title="Declare the AD_ID permission">
    To collect the AAID, the client app must declare the `AD_ID` permission in its `AndroidManifest.xml`:

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

    <Note>
      This permission is required on **Android 13 (API 33)** and above. Without it, the AAID is returned as all zeros (`00000000-0000-0000-0000-000000000000`), and the SDK treats this the same as no AAID — nothing is stored.
    </Note>

    Google Play Services must also be available on the device. If Play Services is missing or unavailable, the fetch fails silently and no alias is stored.
  </Step>

  <Step title="Update your Play Console Data Safety form">
    Because the AAID is now collected and sent off-device, declare it in **Play Console → App content → Data safety**:

    * **Data type collected:** `Device or other IDs` → `Advertising ID` (under `Personal info`)
    * **Collection:** Yes, collected; sent off-device
    * **Optional vs. required:** Optional — the user can deny via Limit Ad Tracking or by resetting the AAID, and the SDK respects both
    * **Purposes:** whichever apply to your use of Permutive (typically Analytics, Advertising or marketing, Personalization)

    <Warning>
      Keep your Data Safety declaration in sync with what the SDK actually collects. Misdeclaring collected identifiers can lead to Play Store policy violations.
    </Warning>
  </Step>

  <Step title="Confirm enablement with Permutive">
    Automatic collection is enabled remotely via the dashboard. Contact your Customer Success Manager to help enabling or disabling the feature.
  </Step>
</Steps>

## Verifying Collection

Enable developer logging and look for the identity being set:

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

```
D/Permutive: Identified user with aliases: aaid, ip_address
```

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

## Manual vs. Automatic AAID Collection

If you already add [`AaidAliasProvider`](/sdks/mobile/android/integrations/aaid-provider) manually, we recommend **removing the manual provider** once automatic collection is enabled, unless you have a specific use case for it. Automatic, config-driven collection covers the same capture, lets you enable or disable it without shipping an app update, and is managed centrally from the dashboard.

<Note>
  Running both is safe in the meantime — automatic collection deduplicates against any existing `aaid` alias with the same value and priority, so you won't get duplicate identities during the transition.
</Note>

|                               | Manual (`AaidAliasProvider`) | Automatic (config-driven) |
| ----------------------------- | ---------------------------- | ------------------------- |
| Enablement                    | App code at initialization   | Workspace config (remote) |
| App update needed to toggle   | Yes                          | No                        |
| `AD_ID` permission required   | Yes (Android 13+)            | Yes (Android 13+)         |
| Google Play Services required | Yes                          | Yes                       |
| Alias tag                     | `aaid`                       | `aaid`                    |

## Rollback

If you need to roll back to v1.11.x:

```kotlin theme={"dark"}
dependencies {
    implementation("com.permutive.android:core:1.11.3")
}
```

Then sync and rebuild. You can leave the `AD_ID` permission in your manifest — it is harmless when collection is disabled.

## Requirements

v1.12.0 maintains the same minimum requirements as v1.11.x:

| Requirement | Version                |
| ----------- | ---------------------- |
| Android API | 21+ (Android 5.0)      |
| Compile SDK | 34+                    |
| Kotlin      | 1.6+ (if using Kotlin) |
| Java        | 8+ (JVM target 1.8)    |

## Getting Help

<CardGroup cols={2}>
  <Card title="AAID Provider" icon="fingerprint" href="/sdks/mobile/android/integrations/aaid-provider">
    Manual AAID capture and privacy considerations
  </Card>

  <Card title="Identity Management" icon="users" href="/sdks/mobile/android/core-concepts/identity-management">
    How aliases and identities work
  </Card>

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

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