Skip to main content
This guide covers upgrading to Permutive iOS SDK v2.6.x, which introduces config-driven automatic ID collection. When enabled for your workspace, the SDK automatically collects the user’s IDFA, IDFV, 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 v2.6.0

Automatic IDFA collection

The SDK captures the IDFA as an idfa alias when enabled in your workspace config and the user has authorized tracking

Automatic IDFV collection

The SDK captures the identifierForVendor as an idfv alias — no user permission required

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 idfa, the priority defined in your config.
  • Only collected when the user has authorized tracking via App Tracking Transparency (ATT status authorized). Requires iOS 14+.
  • If ATT status is not determined, collection is skipped until the user responds — the SDK does not present the ATT prompt itself.
  • If ATT status is denied or restricted, no alias is stored and any existing idfa alias is cleared.
  • A zeroed-out IDFA (00000000-0000-0000-0000-000000000000) is treated as no IDFA — nothing is stored.
  • If an alias with the same tag and value already exists, storage is skipped to avoid duplicates.
  • Stored as an alias with tag idfv, the priority defined in your config.
  • Uses identifierForVendor — no user permission is required, and it works on both iOS and tvOS.
  • Stored as an alias with tag ip_address, the priority defined in your config.
  • Retrieved from an internal endpoint and updated when the IP changes.
  • No app or privacy-manifest changes are required for IP collection.

​
Standard Upgrade

Upgrading the SDK requires only a dependency bump.
Update the package to 2.6.0 (or later) in Xcode via File → Packages → Update to Latest Package Versions, or pin the version in Package.swift:
.package(url: "https://github.com/permutive/permutive-ios", from: "2.6.0")
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 IDFA Collection

The steps below are only required if you opt into automatic IDFA collection. They do not apply to a standard version upgrade, and they are not needed for automatic IDFV or IP address collection (which require no app changes).
The Permutive SDK links the AppTrackingTransparency framework so it can read the ATT status. This affects your App Store submission and privacy declarations even if your app never used ATT before — follow the path that matches your app.

​
If you already use App Tracking Transparency

Your app already declares NSUserTrackingUsageDescription and requests authorization, so the only requirement is to keep your privacy manifest consistent.
1

Reconcile your privacy manifest

Xcode merges the SDK’s PrivacyInfo.xcprivacy with your app’s at build time. Ensure your NSPrivacyCollectedDataTypes entries match what data your app actually collects.

​
If you opt into IDFA collection but do not already use App Tracking Transparency

To collect the IDFA, the SDK reads the ATT authorization status and the advertising identifier. If your app does not already use ATT, you need to add a tracking usage description and decide how your app declares tracking before enabling IDFA collection.
1

Add NSUserTrackingUsageDescription to Info.plist

The presence of AppTrackingTransparency symbols in the binary requires a NSUserTrackingUsageDescription key in Info.plist to pass App Store review:
<key>NSUserTrackingUsageDescription</key>
<string>We use this identifier to deliver and measure personalized advertising.</string>
The value can be any descriptive string — it will not be shown to users unless your app explicitly calls ATTrackingManager.requestTrackingAuthorization(). Without this key, the app submission will be rejected regardless of whether IDFA collection is active.
The Permutive SDK does not present the ATT prompt for you. If you want IDFA to actually be collected, your app must request authorization (and be granted it) — otherwise only IDFV/IP are collected.
2

Update your App Privacy nutrition label

In App Store Connect, under App Privacy → Data Types, declare:
  • Identifiers → Device ID — collected, linked to the user’s identity, used for tracking
  • Purposes: whichever apply to your use of Permutive (typically Third-Party Advertising, Analytics)
Keep your privacy declarations in sync with what the SDK actually collects. Misdeclaring collected identifiers can lead to App Store rejections.

​
Verifying Collection

Enable developer logging and look for the identity being set: 
Permutive.shared.setDeveloperMode(enabled: true)
Look for log lines such as: 
IDFA auto-collection success
If IDFA is skipped, the log states why (for example, ATT not yet determined by user, ATT status is denied, or IDFA is zeroed out). See the Verification Guide for complete steps.

​
Manual vs. Automatic IDFA Collection

If you currently set the IDFA yourself (for example via setIdentityForIDFA — see the IDFA Provider guide), we recommend removing the manual code 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 skips storage when an idfa alias with the same value already exists, so you won’t get duplicate identities during the transition.
Manual (setIdentityForIDFA)Automatic (config-driven)
EnablementApp codeWorkspace config (remote)
App update needed to toggleYesNo
ATT authorization requiredYes (iOS 14+)Yes (iOS 14+)
NSUserTrackingUsageDescription requiredYesYes
Available on tvOSYes (tvOS 14.5+)Yes (tvOS 14.5+)
Alias tagidfaidfa

​
Rollback

If you need to roll back to v2.5.x, pin the previous version: 
.package(url: "https://github.com/permutive/permutive-ios", from: "2.5.2")
You can leave the NSUserTrackingUsageDescription key in your Info.plist — it is harmless when collection is disabled.

​
Getting Help

IDFA Provider

Manual IDFA capture, ATT, and privacy considerations

Identity Management

How aliases and identities work

Verification

Verify identity capture

Issues

Solutions to common issues