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

# IFA 与 ATT

> SDK 如何在 iOS 与 Android 上读取设备广告标识符，以及每个平台所需的一次性配置。

**IFA（Identifier for Advertisers，广告标识符）** 是平台原生的广告 ID——iOS 上是 IDFA，Android 上是 GAID。SDK 会自动读取它；你的应用只需要完成下面一次性的平台配置。

如果 IFA 不可用（用户拒绝授权、系统级 opt-out、或在 Web 环境），SDK 会回退到一个内部生成的第一方标识符——填充率仍能维持在合理水平，但在 IFA 可用时，再营销与频次封顶的效果会更好。

## iOS —— IDFA 与 App Tracking Transparency

iOS 14+ 要求 SDK 在读取 IDFA 之前先获得用户同意。对应的系统弹窗是 **App Tracking Transparency（ATT）**。

请在 `Info.plist` 中添加使用说明：

```xml theme={null}
<key>NSUserTrackingUsageDescription</key>
<string>We use your advertising identifier to show you more relevant ads.</string>
```

<Warning>
  缺少此 key 会导致 SDK 在 iOS 14+ 上请求 ATT 时崩溃。
</Warning>

默认情况下，SDK 会在首次创建 session 时自动调用 `ATTrackingManager.requestTrackingAuthorization`。若希望自己控制弹窗时机（例如延后到 onboarding 之后），可以把 `requestTrackingAuthorization: false` 设置到 `SessionOptions`，并传入你自己收集的 `advertisingId`。

<Warning>
  ATT 弹窗只在应用处于活跃状态时才会出现。过早初始化 SDK（例如在 `AppDelegate.didFinishLaunchingWithOptions` 中）可能让弹窗被完全吞掉。
</Warning>

Swift SDK 还会读取 **IDFV**（`UIDevice.current.identifierForVendor`）作为 iOS 上稳定的辅助标识符。IDFV **不需要** ATT 授权，且始终可用。

## Android —— GAID 与 AD\_ID 权限

Android 上的 GAID 一直可用，**无需运行时弹窗**。但要读取它，需要 install-time 的 `com.google.android.gms.permission.AD_ID` 权限（Android 13+ / API 33+）。

不同 SDK 声明此权限的方式不同：

* **Kotlin SDK 与 React Native SDK** —— 通过 manifest merger 自动加入，**无需**修改你的 `AndroidManifest.xml`。
* **Flutter SDK** —— 需要在 `android/app/src/main/AndroidManifest.xml` 中手动声明：

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

<Note>
  如果你的 manifest 中任何地方对 `AD_ID` 权限设置了 `tools:node="remove"`（通常是早期隐私收紧改动的残留），请移除该覆盖，否则 SDK 无法读取 GAID。
</Note>

## Web

浏览器环境没有 OS 级别的 IFA。React、Vue 和 JavaScript SDK 既不读取也不请求它——每次请求都会直接使用第一方兜底标识符。