SKAdNetwork 转化值映射：如何实现动态 SKAN 架构自动化

MMP 是如何自动映射 SKAdNetwork 架构的？移动衡量伙伴（MMP）或归因后端通过将应用内事件和收入层级转化为集中控制台上的动态、版本化 JSON 配置架构，来实现 SKAdNetwork 架构映射的自动化。移动端 SDK 会在启动时获取此配置，并在运行时在本地评估转化规则，从而允许支持的转化规则变更在无需发布新的 iOS 应用二进制包的情况下即可生效。

SKAdNetwork 转化值架构是一套厂商或应用级别的规则集，用于将应用内用户行为（例如收入交易、新手引导里程碑或功能互动）映射到苹果的 6 位细粒度值（0 到 63）以及 3 级粗粒度值（low、medium、high）。动态映射架构将版本化的配置文件从云端后端分发到客户端 SDK，消除了在编译好的 iOS 应用二进制文件中硬编码转化逻辑的需求。

自动化 SKAdNetwork 转化值映射的架构设计

区分苹果平台层与厂商架构层

为了构建健壮的转化值引擎，工程团队必须将苹果的原生框架规则与厂商级别的架构抽象分离开来：

• 苹果平台层：管理核心操作系统原语，包括三个连续的转化窗口（首次启动后的第 0–2 天、第 3–7 天、第 8–35 天）、6 位细粒度值（0–63）、粗粒度值（low、medium、high）、回传数据层级以及 SKAdNetwork.updatePostbackConversionValue API。
• 厂商架构层：包含应用定义的业务规则，例如收入分桶、新手引导转化漏斗演进、位运算标志分配、远程 JSON 同步以及客户端规则评估。

┌────────────────────────────────────────┐
│                           Vendor Schema Layer                                  │
│  [MMP / Analytics Console] ──► [Publishes Versioned JSON Configuration]     │
│                                              │                                │
│  [Client Mobile SDK]       ──► [Evaluates In-App Events Locally in Memory]  │
└──────────────────────────────────────┬─┘
                                       │ (Calculates Fine, Coarse, & Lock)
                                       ▼
┌────────────────────────────────────────┐
│                           Apple Platform Layer                                 │
│  [StoreKit Framework]      ──► [SKAdNetwork.updatePostbackConversionValue]  │
│  [Operating System]        ──► [Manages Conversion Windows & Timers]        │
│  [System]                  ──► [Prepares and Sends Signed Postback]         │
└────────────────────────────────────────┘

硬编码转化逻辑的局限性

直接在 iOS 应用代码中硬编码转化逻辑会带来显著的运营限制：

• 依赖 App Store 审核：对收入阈值、事件权重或窗口锁定触发条件的任何修改，都需要经历完整的二进制包发布周期。
• 版本碎片化：生产环境中多个历史应用版本会传输冲突的转化语义，从而污染下游报表模型。
• 优化缺乏灵活性：增长团队无法根据实时的营销效果，在注重互动和注重变现的策略之间灵活调整转化策略。

动态配置交付流水线

自动化映射架构通过多阶段流水线将转化逻辑与编译后的二进制文件解耦：

1. 控制台配置：市场人员和分析师在集中式仪表盘上配置事件权重、币种层级和窗口锁定规则。
2. 架构版本控制与锁定：后端发布版本化的 JSON 配置负载。为了防止用户在 35 天转化生命周期内出现语义漂移，成熟的厂商实现会锁定在初始转化窗口建立的活跃架构配置，确保即使在应用重启后，确切的映射规则依然可用。
3. 客户端引入与缓存：移动端 SDK 在应用初始化时下载活跃架构，并在本地持久化存储中缓存配置负载和版本元数据。
4. 本地规则评估：当应用内事件发生时，SDK 会针对缓存的规则集在本地进行评估，而不会在事件执行路径中添加同步的远程配置请求。

另请参阅：SKAdNetwork ──> 移动归因架构

跨 SKAN 4.0 窗口设计动态转化值架构

多窗口架构分段

SKAdNetwork 4.0 将转化衡量划分为以应用首次启动为锚点的三个连续窗口：

• 窗口 1（第 0–2 天）：首次启动后的前 48 小时。
• 窗口 2（第 3–7 天）：首次启动后的第 48 小时到第 168 小时。
• 窗口 3（第 8–35 天）：首次启动后的第 168 小时到第 840 小时。

动态架构引擎将这些窗口的规则进行分段，根据自应用初始启动以来经过的时间来执行相应的数值计算。

窗口 1（第 0–2 天）：构建细粒度和粗粒度值

窗口 1 是唯一符合条件公开细粒度转化值的转化窗口。窗口 1 的配置定义了两个并发的映射：

• 细粒度映射（0–63）：高分辨率规则，用于捕获初始变现层级、新手引导里程碑或综合互动得分。
• 粗粒度映射（low、medium、high）：当分配的回传数据层级不允许进行细粒度报告时公开的低分辨率回退状态。

窗口 2（第 3–7 天）和窗口 3（第 8–35 天）：粗粒度生命周期追踪

第二和第三次回传不会暴露细粒度转化值；对于符合条件的数据层级，它们仅公开粗粒度值。

窗口 2 和窗口 3 的架构专注于长期留存和变现里程碑：

• 窗口 2 粗粒度映射：评估中游漏斗留存（例如，low = 第 3–7 天活跃；medium = 完成 3 个会话；high = 重复购买或试用转化）。
• 窗口 3 粗粒度映射：评估长尾留存和订阅续费（例如，low = 第 8–35 天留存；medium = 达到关卡里程碑；high = 有效付费订阅用户）。

配置转化架构的开发者可以参考 SKAN 转化映射文档 获取关于多窗口规则结构的技术指南。

厂商定义的编码模型：收入分桶、漏斗与位运算逻辑

这些编码模型代表了厂商和应用级别的设计模式，而非苹果规定的架构类型。

基于收入的架构

收入架构将可用的细粒度值分配到累积购买金额中：

• 线性分桶：将收入范围划分为相等的区间（例如，以 $1.50 为增量划分为 64 个分桶，最高可达 $96.00）。非常适合交易金额可预测的应用。
• 对数分桶：为低成本购买分配精细的分桶，同时为高价值交易扩大分桶范围（例如，值 1–20 覆盖 $0.99–$19.99；值 21–50 覆盖 $20.00–$100.00；值 51–63 覆盖 $100.00–$1000.00+）。
• 基于百分位分桶：根据实证变现曲线，将历史用户购买分布映射到队列细分中。

漏斗演进架构与数值方向性

在 SKAdNetwork 3 及更早版本中，苹果要求转化值必须单调递增。在 SKAdNetwork 4.0 中，苹果取消了这一限制，允许窗口 1 中的转化值在后续 API 调用中增加或减少。

然而，许多归因架构有意将单调递进强制执行为厂商级别的设计惯例，以确保更高的数值代表逐步增强的商业成果：

• 值 0：应用已安装并打开。
• 值 10：注册完成。
• 值 20：新手引导教程完成。
• 值 30：添加支付方式。
• 值 45：商品已加入购物车。
• 值 63：初始结账完成。

位运算分类架构

位运算架构将 6 位整数（$2^6 = 64$）视为六个独立的布尔标志（$b_5 b_4 b_3 b_2 b_1 b_0$)：

以下版本化的 JSON 负载说明了一个多窗口动态配置文档：

{
  "schema_version": "4.0.1",
  "app_id": "1234567890",
  "currency": "USD",
  "windows": {
    "window_1": {
      "mode": "hybrid_revenue_and_funnel",
      "fine_mapping": [
        { "event": "app_open", "min_revenue_cents": 0, "fine_value": 0, "lock": false },
        { "event": "registration_complete", "min_revenue_cents": 0, "fine_value": 10, "lock": false },
        { "event": "tutorial_complete", "min_revenue_cents": 0, "fine_value": 20, "lock": false },
        { "event": "purchase", "min_revenue_cents": 99, "fine_value": 30, "lock": false },
        { "event": "purchase", "min_revenue_cents": 999, "fine_value": 45, "lock": false },
        { "event": "purchase", "min_revenue_cents": 4999, "fine_value": 63, "lock": true }
      ],
      "coarse_mapping": {
        "low": { "events": ["app_open", "registration_complete"] },
        "medium": { "events": ["tutorial_complete"] },
        "high": { "events": ["purchase"] }
      }
    },
    "window_2": {
      "mode": "coarse_retention_and_monetization",
      "coarse_mapping": {
        "low": { "events": ["app_open"], "lock": false },
        "medium": { "events": ["session_milestone"], "lock": false },
        "high": { "events": ["repeat_purchase"], "lock": true }
      }
    },
    "window_3": {
      "mode": "coarse_long_tail_ltv",
      "coarse_mapping": {
        "low": { "events": ["app_open"], "lock": false },
        "medium": { "events": ["level_milestone"], "lock": false },
        "high": { "events": ["subscription_active"], "lock": true }
      }
    }
  }
}

动态 SDK 配置：在运行时引入并评估远程配置

客户端规则评估机制

归因 SDK 在应用运行时在本地评估转化规则：

• 事件路径上无同步远程配置获取：应用内操作会针对活跃规则集触发本地内存评估，立即调用 StoreKit API 而不阻塞应用执行。
• 数据最小化：对于此处展示的 SKAdNetwork 转化更新路径，原始事件输入可以在本地进行评估，仅需将最终的转化值传递给 StoreKit。这本身并不描述或限制 SDK 实现的其他数据分析流。

处理离线状态与本地持久化

当应用在离线或网络条件较差的情况下启动时：

1. SDK 在本地持久化中独立初始化首次启动时间戳锚点。
2. SDK 从持久化本地存储中加载已锁定的配置架构，验证缓存的负载是否与锁定的架构版本匹配。
3. 如果在离线时发生应用内事件，SDK 会针对缓存的规则集对其进行评估，并立即调用 StoreKit 更新 API。
4. 回传准备和交付仍由系统管理且为异步进行；应用本身无需分发回传。

下面的 Swift 实现演示了一个多窗口架构评估引擎，它可计算细粒度和粗粒度值、管理窗口特定的锁定状态、持久化锁定的架构配置，并且仅在 StoreKit 成功执行后才提交状态更新：

import Foundation
import StoreKit

// MARK: - Schema Configuration Models

struct SKANSchemaConfig: Codable {
    let schemaVersion: String
    let appId: String
    let currency: String
    let windows: SchemaWindows

    enum CodingKeys: String, CodingKey {
        case schemaVersion = "schema_version"
        case appId = "app_id"
        case currency, windows
    }
}

struct SchemaWindows: Codable {
    let window1: Window1Config
    let window2: WindowCoarseConfig
    let window3: WindowCoarseConfig

    enum CodingKeys: String, CodingKey {
        case window1 = "window_1"
        case window2 = "window_2"
        case window3 = "window_3"
    }
}

struct Window1Config: Codable {
    let mode: String
    let fineMapping: [FineRule]
    let coarseMapping: CoarseRuleGroup

    enum CodingKeys: String, CodingKey {
        case mode
        case fineMapping = "fine_mapping"
        case coarseMapping = "coarse_mapping"
    }
}

struct FineRule: Codable {
    let event: String
    let minRevenueCents: Int
    let fineValue: Int
    let lock: Bool

    enum CodingKeys: String, CodingKey {
        case event
        case minRevenueCents = "min_revenue_cents"
        case fineValue = "fine_value"
        case lock
    }
}

struct WindowCoarseConfig: Codable {
    let mode: String
    let coarseMapping: [String: CoarseRule]

    enum CodingKeys: String, CodingKey {
        case mode
        case coarseMapping = "coarse_mapping"
    }
}

struct CoarseRuleGroup: Codable {
    let low: CoarseRule
    let medium: CoarseRule
    let high: CoarseRule
}

struct CoarseRule: Codable {
    let events: [String]?
    let lock: Bool?
}

// MARK: - Multi-Window SKAN 4.0 Schema Engine

final class SKANSchemaEngine {

    static let shared = SKANSchemaEngine()
    private init() {}

    private var activeSchema: SKANSchemaConfig?
    private var firstLaunchDate: Date?
    private var lockedWindows = Set<Int>()
    private var lastRecordedFineValue: Int = 0
    private var pinnedSchemaVersion: String?

    /// Initializes the first-launch timestamp anchor independently of remote configuration fetches
    func initializeLifecycleAnchor() {
        let defaults = UserDefaults.standard
        if let storedLaunch = defaults.object(forKey: "skan_first_launch_date") as? Date {
            self.firstLaunchDate = storedLaunch
        } else {
            let now = Date()
            self.firstLaunchDate = now
            defaults.set(now, forKey: "skan_first_launch_date")
        }

        let lockedArray = defaults.array(forKey: "skan_locked_windows") as? [Int] ?? []
        self.lockedWindows = Set(lockedArray)
        self.lastRecordedFineValue = defaults.integer(forKey: "skan_last_fine_value")
        self.pinnedSchemaVersion = defaults.string(forKey: "skan_pinned_schema_version")

        // Restore previously cached schema payload if it matches the pinned version
        if let pinnedVersion = self.pinnedSchemaVersion,
           let cachedData = defaults.data(forKey: "skan_cached_schema_payload"),
           let cachedSchema = try? JSONDecoder().decode(SKANSchemaConfig.self, from: cachedData),
           cachedSchema.schemaVersion == pinnedVersion {
            self.activeSchema = cachedSchema
        }
    }

    /// Loads active schema, persisting the pinned payload to maintain consistency across the 35-day lifecycle
    func configure(schema: SKANSchemaConfig) {
        let defaults = UserDefaults.standard
        if let pinned = pinnedSchemaVersion {
            // If already pinned, accept only schemas matching the pinned version
            if pinned == schema.schemaVersion {
                self.activeSchema = schema
                if let data = try? JSONEncoder().encode(schema) {
                    defaults.set(data, forKey: "skan_cached_schema_payload")
                }
            }
        } else {
            // Pin the initial schema version for this lifecycle
            self.activeSchema = schema
            self.pinnedSchemaVersion = schema.schemaVersion
            defaults.set(schema.schemaVersion, forKey: "skan_pinned_schema_version")
            if let data = try? JSONEncoder().encode(schema) {
                defaults.set(data, forKey: "skan_cached_schema_payload")
            }
        }
    }

    /// Determines the active conversion window based on elapsed time from first launch
    private var currentWindowIndex: Int {
        guard let firstLaunch = firstLaunchDate else { return 0 }
        let elapsedHours = Date().timeIntervalSince(firstLaunch) / 3600.0

        switch elapsedHours {
        case 0.0..<48.0:
            return 1
        case 48.0..<168.0:
            return 2
        case 168.0...840.0:
            return 3
        default:
            return 0 // Window closed (>35 days)
        }
    }

    /// Evaluates an in-app event against the active schema for the current window
    func trackEvent(name: String, revenueCents: Int = 0) {
        guard #available(iOS 16.1, *),
              let schema = activeSchema else { return }

        let window = currentWindowIndex
        guard window >= 1 && window <= 3, !lockedWindows.contains(window) else { return }

        var targetFineValue: Int?
        var targetCoarseValue: SKAdNetwork.CoarseConversionValue?
        var shouldLock = false
        var matchedRule = false

        if window == 1 {
            // Window 1: Evaluate fine-grained rules with highest-threshold precedence
            let matchingFineRules = schema.windows.window1.fineMapping
                .filter { $0.event == name && revenueCents >= $0.minRevenueCents }
                .sorted { $0.minRevenueCents < $1.minRevenueCents }

            if let highestRule = matchingFineRules.last {
                targetFineValue = highestRule.fineValue
                if highestRule.lock { shouldLock = true }
                matchedRule = true
            }

            // Window 1: Evaluate coarse-grained rules explicitly
            if schema.windows.window1.coarseMapping.high.events?.contains(name) == true {
                targetCoarseValue = .high
                matchedRule = true
            } else if schema.windows.window1.coarseMapping.medium.events?.contains(name) == true {
                targetCoarseValue = .medium
                matchedRule = true
            } else if schema.windows.window1.coarseMapping.low.events?.contains(name) == true {
                targetCoarseValue = .low
                matchedRule = true
            }
        } else {
            // Windows 2 & 3: Evaluate coarse rules only
            let coarseConfig = (window == 2) ? schema.windows.window2 : schema.windows.window3
            
            if let highRule = coarseConfig.coarseMapping["high"], highRule.events?.contains(name) == true {
                targetCoarseValue = .high
                if highRule.lock == true { shouldLock = true }
                matchedRule = true
            } else if let medRule = coarseConfig.coarseMapping["medium"], medRule.events?.contains(name) == true {
                targetCoarseValue = .medium
                if medRule.lock == true { shouldLock = true }
                matchedRule = true
            } else if let lowRule = coarseConfig.coarseMapping["low"], lowRule.events?.contains(name) == true {
                targetCoarseValue = .low
                if lowRule.lock == true { shouldLock = true }
                matchedRule = true
            }
        }

        // If no explicit rule matched for this event, do not trigger a StoreKit update
        guard matchedRule else { return }

        let fineToSubmit = targetFineValue ?? (window == 1 ? lastRecordedFineValue : 0)
        let clampedFine = max(0, min(63, fineToSubmit))
        let coarseToSubmit = targetCoarseValue ?? .low

        // Dispatch StoreKit conversion update
        // Note: StoreKit ignores the fineValue parameter after Window 1
        SKAdNetwork.updatePostbackConversionValue(
            clampedFine,
            coarseValue: coarseToSubmit,
            lockWindow: shouldLock
        ) { [weak self] error in
            guard let self = self else { return }
            if let error = error {
                print("StoreKit conversion update failed: \(error.localizedDescription)")
            } else {
                // Commit local state only after StoreKit successfully accepts the update
                DispatchQueue.main.async {
                    if window == 1 {
                        self.lastRecordedFineValue = clampedFine
                        UserDefaults.standard.set(clampedFine, forKey: "skan_last_fine_value")
                    }
                    if shouldLock {
                        self.lockedWindows.insert(window)
                        UserDefaults.standard.set(Array(self.lockedWindows), forKey: "skan_locked_windows")
                    }
                    print("SKAN 4.0 update succeeded: Window=\(window), Fine=\(clampedFine), Coarse=\(coarseToSubmit.rawValue), Locked=\(shouldLock)")
                }
            }
        }
    }
}

自动化 lockWindow 执行以加速回传准备

lockWindow 参数的运作机制

当应用调用带生态 lockWindow: true 的 updatePostbackConversionValue(_:coarseValue:lockWindow:) 时，该更新将成为活跃窗口的最终转化值更新。操作系统会立即准备回传，并忽略该窗口剩余时间内其他附加的转化值更新。

Default Window 1 (No Lock):
[First Launch] ─────────────── 48 Hours Open ───────────────► [Closes] ──► Delay (24-48h) ──► Postback 1

Locked Window 1 (Purchase at Hour 6):
[First Launch] ── 6h (Lock: true) ──► [Conversion Locked / Postback Prepared] ──► Delay (24-48h) ──► Postback 1 Sent Sooner

自动化窗口锁定的战略权衡

• 加速回传分发：提前完成转化可使苹果随机化的回传延迟立即开始，从而更快地向广告网络交付转化数据。
• 窗口独立性：锁定当前窗口不会提前下一窗口的开始时间；无论窗口 1 何时锁定，窗口 2 仍然从第 3 天开始。
• 观测截断：一旦窗口被锁定，系统将在该转化窗口的剩余时间内忽略后续的转化值更新调用。应用内事件可能会继续发生，但它们无法再更改该窗口的 SKAdNetwork 转化状态。

协调 SKAN 架构与 AdAttributionKit

苹果不断演进的归因技术栈

苹果现在推荐针对 App Store 及替代应用市场的应用广告活动使用 AdAttributionKit。SKAdNetwork 仍然适用于现有的集成和互操作性，因此动态映射引擎应将其业务规则层与框架特定的转化 API 保持分离：

• 共享值维度：两个框架都评估 6 位细粒度值（0 到 63）和 3 级粗粒度值（low、medium、high）。
• 不同的 API 层：SKAdNetwork 使用 SKAdNetwork.updatePostbackConversionValue，而 AdAttributionKit 使用 Postback.updateConversionValue。
• 桥接行为：如果集成同时支持这两个框架，苹果建议调用两个框架的转化更新 API，同时兼顾已文档化的 SKAdNetwork 到 AdAttributionKit 的桥接行为。

对比决策矩阵：硬编码客户端逻辑与动态配置

总结与决策架构

将 SKAdNetwork 转化值映射自动化，能够将增长实验与移动端二进制发布周期解耦。通过从集中式归因仪表盘分发动态架构并在 SDK 内在本地进行评估，工程团队可以微调收入分桶、优化漏斗里程碑并配置自动化窗口锁定，从而允许支持的转化规则变更在无需重新提交应用二进制包至 App Store Connect 的情况下即可生效。

应用级深度链接路由可以作为独立的数据衡量和新手引导层，与苹果注重隐私的归因框架协同运行。类似 OpoInstall 的平台为第一方上下文路由和延迟深度链接提供了基础设施，使团队能够在 web-to-app 转化漏斗中保持用户的意图。

若要详细了解如何配置符合隐私规范的归因和深度链接流水线，请参阅 OpoInstall 文档。

相关材料

• 概念：转化值架构、动态架构映射、收入分桶、窗口锁定、单调性

• 技术：Apple SKAdNetwork、Apple AdAttributionKit、StoreKit 框架、OpoInstall 移动端 SDK

• 标准：IETF RFC 8259 JSON 规范

• API：StoreKit updatePostbackConversionValue API、AdAttributionKit Postback.updateConversionValue API

官方文档

• 更新回传转化值的苹果开发者文档

• 关于 SKAdNetwork 的苹果开发者文档

• 关于 AdAttributionKit 的苹果开发者文档

• 在多个转化窗口中接收回传的苹果开发者文档

• 理解 AdAttributionKit 与 SKAdNetwork 的互操作性