在 iOS 17.4+ 用…

适用于在 Apple 生态中用 AdAttributionKit 衡量安装与重定向广告效果，并实现发布者、广告主、广告网络三方的归因流程。

适用场景

解决思路

1. 在迁移与互操作评审中，明确说明系统会把 AdAttributionKit 和 SKAdNetwork 展示合并评估：每次转化只有一个展示获胜；click-through 优先于 view-through；click-through 之间按最近时间打破平局；之后才回退到最近的 view-through 展示。
2. 处理延迟：postback 在转化窗口关闭后 24-48 小时发送（第一窗口），或 24-144 小时发送（第二/第三窗口）。
3. 不依赖设备或用户 ID；postback 只包含聚合 source identifiers 和 conversion values。
4. 解析 source ID 时不要假定固定长度；返回 2、3 或 4 位数字取决于 crowd anonymity tier。
5. 发布者 App 将每个广告网络 ID 加入 Info.plist 的 AdNetworkIdentifiers 数组，使展示有资格进行安装校验。
6. Ad network ID 必须小写；也可接受以 .skadnetwork 结尾的 SKAdNetwork ID，因为两个框架共享 ID。
7. 对 click-through 自定义渲染广告，在每个可点击广告或控件上覆盖一个 UIEventAttributionView；它必须覆盖可点击区域，并保持在会拦截触摸的视图之上，直到 handleTap() 成功。
8. 广告主 App 在 Info.plist 顶层 AdAttributionKit 字典下添加 AttributionCopyEndpoint，使设备把获胜 postback 副本发送到你的服务器。
9. 由 URL 中可注册域名（忽略子域名）推导 well-known endpoint，例如 https://example.com/.well-known/appattribution/report-attribution/；配置服务器在该路径接受 HTTPS POST 请求，且域名有有效 SSL 证书。
10. 若还要接收获胜 re-engagement postback 副本，在同一个 AdAttributionKit 字典中添加 OptInForReengagementPostbackCopies 并设为 true。
11. 广告主 App 首次启动后尽早调用 Postback.updateConversionValue(0, lockPostback: false)，以开始转化窗口。
12. 广告网络用 JWS（JSON Web Signature）创建签名展示；发布者 App 用 AppImpression(compactJWS: signedJWSString) 注册并处理展示。
13. JWS 中包含 ad network ID、advertised item ID、publisher item ID、source identifier、timestamp、可选 re-engagement eligibility flag。
14. 在调用展示 API 前检查 AppImpression.isSupported；不支持时回退到替代广告展示。
15. 当广告内容已展示并消失时，调用 impression.handleView() 记录 view-through 展示。
16. 对长期展示的广告，使用 beginView() 和 endView() 跟踪展示时长。
17. 响应广告点击时，在创建 AppImpression 后 15 分钟内调用 handleTap()；否则请求新的 impression。
18. handleTap() 成功后，如果被推广 App 未安装，系统打开其 App Store 或 marketplace 页面；如果已安装，系统直接启动它。
19. handleTap() 成功需要 UIEventAttributionView 覆盖广告。
20. 对 StoreKit 渲染的广告，将 impression 传给 StoreKit overlay 或 product view controller API；例如设置 SKOverlay.AppConfiguration.appImpression = impression；StoreKit 会在展示 2 秒后自动记录 view-through，并在点击时记录 click-through。
21. 理解获胜归因可能跨多个转化窗口产生多个 postback；低数据 tier 和非获胜归因披露更少；查看 references/adattributionkit-patterns.md 获取当前窗口和延迟矩阵。
22. 区分归因资格窗口与 conversion/postback 窗口；按当前文档和参考配置并验证 view-through、click-through、install-update、re-engagement 限制，不要合并这两个概念。
23. 提前锁定 conversion value：调用 Postback.updateConversionValue(42, coarseConversionValue: .high, lockPostback: true) 以在窗口结束前定稿并更早收到 postback；锁定后该系统会忽略该转化窗口中的进一步更新。
24. 代码和分析必须容忍 postback 数据随系统分配 tier 披露：可能缺失 source digits、fine/coarse conversion values、publisher item ID 和 country；详细 tier 矩阵见参考。
25. fine-grained conversion value 使用 0...63 的整数（6 bits），仅在第一封 postback 且 Tier 2 或更高时可用；调用 Postback.updateConversionValue(35, coarseConversionValue: .medium, lockPostback: false)。
26. coarse conversion value 使用 .low、.medium、.high 三级，用于较低 tier 以及第二/第三封 postback；调用 Postback.updateConversionValue(10, coarseConversionValue: .high, lockPostback: false)。
27. iOS 18+ 按 conversion type 分别更新 install 与 re-engagement postback：server JSON 用 conversion-type 值 re-engagement（带连字符）；Swift API 用 .reengagement（不带连字符）。创建 PostbackUpdate(fineConversionValue: 20, lockPostback: false, conversionTypes: [.install]) 并调用 Postback.updateConversionValue(installUpdate)；re-engagement 同理。
28. iOS 18.4+ 使用 conversion tags 在存在重叠转化窗口时有选择地更新特定 postback：创建 PostbackUpdate(..., conversionTag: savedConversionTag, conversionTypes: [.reengagement]) 并调用 Postback.updateConversionValue(update)；系统通过 re-engagement URL 的 AdAttributionKitReengagementOpen 查询参数传递 conversion tag。
29. 生成 impression 的 JWS payload 中，当要跟踪已安装 App 的 re-engagement 时，将 eligible-for-re-engagement 设为 true。
30. 处理 re-engagement 点击时用 universal link 调用 impression.handleTap(reengagementURL: reengagementURL)；系统会追加 AdAttributionKitReengagementOpen 作为查询参数。
31. 被推广 App 检查 universal link 中是否存在 Postback.reengagementOpenURLParameter，以检测 AdAttributionKit 驱动的打开；例如解析 URLComponents 的 queryItems。
32. Re-engagement 限制：只有 click-through 交互会创建 re-engagement postback，view-through 不会；设备强制执行每月每 App 和每年每设备限制；即使系统不创建 postback，URL 上也始终存在 AdAttributionKitReengagementOpen 参数。
33. 避免常见错误：首次启动必须更新 conversion value，应在预期窗口结束前调用规范的首启更新。
34. 避免常见错误：广告网络 ID 不要含大写字符，使用精确小写网络标识符。
35. 避免常见错误：handleTap() 不要使用过期 impression 或缺少当前 attribution view tap；用 UIEventAttributionView 覆盖广告，保持 impression 新鲜，并从已验证的点击流程调用。
36. 避免常见错误：不要丢弃 tap 错误；显式处理 expired-impression 和 missing-view 情况。
37. 避免常见错误：postback endpoint 不要延迟或丢弃响应；接受请求，持久化或排队处理，并及时返回预期成功。
38. 发布者 App 检查清单：Info.plist 的 AdNetworkIdentifiers 包含所有广告网络 ID 且小写。
39. 检查广告网络 ID 在发布者 App 的 Info.plist 与 JWS kid 之间匹配。
40. 检查 UIEventAttributionView 覆盖每个可点击的 click-through 广告或控件。
41. 检查 handleTap() 时 click-through AppImpression 不超过 15 分钟。
42. 检查被推广 App 首次启动调用 updateConversionValue。
43. 检查服务器 well-known 路径端点接受 HTTPS POST 且有有效 SSL。
44. 检查 postback 验证使用正确环境的 Apple 公钥。
45. 检查按 postback-identifier 过滤重复 postback。
46. 检查服务器对 postback 请求返回 HTTP 200。
47. 检查 re-engagement URL 是被推广 App 已注册的 universal link。
48. 检查 conversion value 策略考虑全部三个转化窗口。
49. 检查在尝试 impression API 前检查 AppImpression.isSupported。
50. 参考 references/adattributionkit-patterns.md 获取 postback 验证、服务器处理、测试、SKAdNetwork 迁移、替代市场、归因规则配置；并参考 Apple 的 AdAttributionKit、Presenting ads in your app、Receiving ad attributions and postbacks、Verifying a postback、SKAdNetwork interoperability 文档。

适用边界 · 注意事项

• 不适用于非 iOS 17.4+ 或不使用 AdAttributionKit 与 Apple 归因栈的项目。
• 需要实时 postback、用户级标识、跨平台统一归因或不受 crowd anonymity tier 限制的细分数据时不适用。
• 如果无法配置 HTTPS well-known endpoint、有效 SSL、universal link 或处理排队与持久化 postback 的服务器，则不能完整使用该归因接收与重定向流程。