Skip to main content
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.
Migration Difficulty: Easy | Estimated Time: 15 minutes | Breaking Changes: None

​
What’s New in v1.12.0

Automatic AAID collection

The SDK captures the AAID as an aaid alias when enabled in your workspace config — no AaidAliasProvider needed

Automatic IP collection

The SDK captures the user’s IP as an ip_address alias from an internal endpoint — no app changes required
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.

​
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.
  • 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), storage is skipped to avoid duplicates.
  • 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.

​
Standard Upgrade

Upgrading the SDK requires only a dependency bump. Update your build.gradle.kts or build.gradle to the v1.12.x core: 
dependencies {
    implementation("com.permutive.android:core:1.11.3")
}
Then sync and rebuild: 
./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

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).
1

Declare the AD_ID permission

To collect the AAID, the client app must declare the AD_ID permission in its AndroidManifest.xml:
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
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.
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.
2

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)
Keep your Data Safety declaration in sync with what the SDK actually collects. Misdeclaring collected identifiers can lead to Play Store policy violations.
3

Confirm enablement with Permutive

Automatic collection is enabled remotely via the dashboard. Contact your Customer Success Manager to help enabling or disabling the feature.

​
Verifying Collection

Enable developer logging and look for the identity being set: 
permutive.setDeveloperMode(true)

D/Permutive: Identified user with aliases: aaid, ip_address
See the Verification Guide for complete steps.

​
Manual vs. Automatic AAID Collection

If you already add AaidAliasProvider 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.
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.
Manual (AaidAliasProvider)Automatic (config-driven)
EnablementApp code at initializationWorkspace config (remote)
App update needed to toggleYesNo
AD_ID permission requiredYes (Android 13+)Yes (Android 13+)
Google Play Services requiredYesYes
Alias tagaaidaaid

​
Rollback

If you need to roll back to v1.11.x: 
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:
RequirementVersion
Android API21+ (Android 5.0)
Compile SDK34+
Kotlin1.6+ (if using Kotlin)
Java8+ (JVM target 1.8)

​
Getting Help

AAID Provider

Manual AAID capture and privacy considerations

Identity Management

How aliases and identities work

Verification

Verify identity capture

Issues

Solutions to common issues