> ## 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: v2.6.x

> Upgrade to Permutive iOS SDK v2.6.x and opt into config-driven automatic ID collection

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.

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

## What's New in v2.6.0

<CardGroup cols={3}>
  <Card title="Automatic IDFA collection" icon="fingerprint">
    The SDK captures the IDFA as an `idfa` alias when enabled in your workspace config and the user has authorized tracking
  </Card>

  <Card title="Automatic IDFV collection" icon="id-card">
    The SDK captures the `identifierForVendor` as an `idfv` alias — no user permission required
  </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="IDFA collection" icon="fingerprint">
    * 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.
  </Accordion>

  <Accordion title="IDFV collection" icon="id-card">
    * 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.
  </Accordion>

  <Accordion title="IP address collection" icon="globe">
    * 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.
  </Accordion>
</AccordionGroup>

## Standard Upgrade

Upgrading the SDK requires only a dependency bump.

<Tabs>
  <Tab title="Swift Package Manager">
    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`:

    ```swift theme={"dark"}
    .package(url: "https://github.com/permutive/permutive-ios", from: "2.6.0")
    ```
  </Tab>

  <Tab title="CocoaPods">
    Update your `Podfile`:

    ```ruby theme={"dark"}
    pod 'Permutive_iOS', '~> 2.6.0'
    ```

    Then run:

    ```bash theme={"dark"}
    pod update Permutive_iOS
    ```
  </Tab>
</Tabs>

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

<Warning>
  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).
</Warning>

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.

<Steps>
  <Step title="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.
  </Step>
</Steps>

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

<Steps>
  <Step title="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:

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

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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)

    <Warning>
      Keep your privacy declarations in sync with what the SDK actually collects. Misdeclaring collected identifiers can lead to App Store rejections.
    </Warning>
  </Step>
</Steps>

## Verifying Collection

Enable developer logging and look for the identity being set:

```swift theme={"dark"}
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](/sdks/mobile/ios/getting-started/verification) for complete steps.

## Manual vs. Automatic IDFA Collection

If you currently set the IDFA yourself (for example via `setIdentityForIDFA` — see the [IDFA Provider](/sdks/mobile/ios/integrations/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.

<Note>
  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.
</Note>

|                                           | Manual (`setIdentityForIDFA`) | Automatic (config-driven) |
| ----------------------------------------- | ----------------------------- | ------------------------- |
| Enablement                                | App code                      | Workspace config (remote) |
| App update needed to toggle               | Yes                           | No                        |
| ATT authorization required                | Yes (iOS 14+)                 | Yes (iOS 14+)             |
| `NSUserTrackingUsageDescription` required | Yes                           | Yes                       |
| Available on tvOS                         | Yes (tvOS 14.5+)              | Yes (tvOS 14.5+)          |
| Alias tag                                 | `idfa`                        | `idfa`                    |

## Rollback

If you need to roll back to v2.5.x, pin the previous version:

<Tabs>
  <Tab title="Swift Package Manager">
    ```swift theme={"dark"}
    .package(url: "https://github.com/permutive/permutive-ios", from: "2.5.2")
    ```
  </Tab>

  <Tab title="CocoaPods">
    ```ruby theme={"dark"}
    pod 'Permutive_iOS', '~> 2.5.2'
    ```
  </Tab>
</Tabs>

You can leave the `NSUserTrackingUsageDescription` key in your `Info.plist` — it is harmless when collection is disabled.

## Getting Help

<CardGroup cols={2}>
  <Card title="IDFA Provider" icon="fingerprint" href="/sdks/mobile/ios/integrations/idfa-provider">
    Manual IDFA capture, ATT, and privacy considerations
  </Card>

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

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

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