Маппинг значений конверсий SKAdNetwork: автоматизация динамических схем SKAN

Как MMP выполняет автоматический маппинг схем SKAdNetwork? Платформа мобильной аналитики (MMP) или бэкенд атрибуции автоматизируют маппинг схем SKAdNetwork, преобразуя внутриигровые события и уровни доходов в динамические версионированные JSON-конфигурации на централизованной консоли. Мобильный SDK загружает эту конфигурацию при запуске и локально оценивает правила конверсий во время выполнения, позволяя вносить изменения в поддерживаемые правила конверсии без необходимости выпускать новый бинарный файл приложения.

Схема значений конверсий SKAdNetwork — это набор правил на уровне вендора или приложения, который связывает поведение пользователей в приложении (например, транзакции с доходами, этапы онбординга или вовлеченность в функции) с 6-битными точными значениями Apple (от 0 до 63) и 3-уровневыми общими значениями (low, medium, high). Архитектуры динамического маппинга распространяют версионированные конфигурационные файлы с облачного бэкенда на клиентский SDK, исключая необходимость жестко зашивать логику конверсий в скомпилированные бинарные файлы приложений для iOS.

Архитектура автоматизированного маппинга значений конверсий SKAdNetwork

Разделение уровня платформы Apple и уровня схем вендора

Для проектирования надежного движка значений конверсий инженерные команды должны отделять правила нативного фреймворка Apple от абстракций схем на стороне вендора:

• Уровень платформы Apple: Регулирует примитивы базовой операционной системы, включая три последовательных окна конверсии (день 0–2, день 3–7, день 8–35 после первого запуска), 6-битные точные значения (0–63), общие значения (low, medium, high), уровни данных постбэков и API SKAdNetwork.updatePostbackConversionValue.
• Уровень схемы вендора: Охватывает бизнес-правила, определенные приложением, такие как распределение доходов по корзинам, прохождение воронок онбординга, распределение побитовых флагов, синхронизация удаленного 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 за техническими рекомендациями по структуре многооконных правил.

Модели кодирования, определяемые вендором: распределение доходов, воронки и побитовая логика

Эти модели кодирования представляют собой паттерны проектирования на уровне вендора и приложения, а не типы схем, предписанные Apple.

Схемы на основе доходов

Схемы доходов распределяют доступные точные значения по накопительным суммам покупок:

• Линейное разбиение по корзинам: Делит диапазон доходов на равные интервалы (например, 64 корзины с шагом $1.50 до $96.00). Идеально подходит для приложений с предсказуемыми размерами транзакций.
• Логарифмическое разбиение по корзинам: Выделяет детальные корзины для недорогих покупок, одновременно расширяя диапазоны корзин для дорогостоящих транзакций (например, значения 1–20 охватывают диапазон $0.99–$19.99; значения 21–50 охватывают $20.00–$100.00; значения 51–63 охватывают $100.00–$1000.00+).
• Разбиение на основе перцентилей: Сопоставляет историческое распределение покупок пользователей с сегментами когорт на основе эмпирических кривых монетизации.

Схемы прогрессии по воронке и направленность значений

В SKAdNetwork 3 и более ранних версиях Apple требовала, чтобы значения конверсий монотонно возрастали. В SKAdNetwork 4.0 Apple сняла это ограничение, разрешив значениям конверсий в Окне 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 атрибуции оценивают правила конверсий локально в среде выполнения приложения:

• Отсутствие синхронной загрузки удаленной конфигурации на пути выполнения событий: Внутриигровые действия вызывают локальную оценку в памяти относительно активного набора правил, немедленно вызывая API StoreKit без блокировки выполнения приложения.
Минимизация данных: Для пути обновления конверсий SKAdNetwork, показанного здесь, входные данные исходных событий могут оцениваться локально, и только результирующие значения конверсий необходимо передавать в StoreKit. Само по себе это не описывает и не ограничивает другие потоки аналитических данных, реализуемые SDK.

Обработка автономного режима (офлайн) и локального хранения

Когда приложение запускается в автономном режиме или в условиях ухудшенного соединения:

1. SDK инициализирует временную метку первого запуска независимо в локальном хранилище.
2. SDK загружает зафиксированную схему конфигурации из постоянного локального хранилища, проверяя, соответствует ли кэшированная полезная нагрузка закрепленной версии схемы.
3. Если внутриигровые события происходят в автономном режиме, SDK оценивает их по кэшированному набору правил и немедленно вызывает API обновления StoreKit.
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

Когда приложение вызывает updatePostbackConversionValue(_:coarseValue:lockWindow:) с параметром lockWindow: true, это обновление становится финальным обновлением значения конверсии для активного окна. Операционная система немедленно готовит постбэк и игнорирует дополнительные обновления значений конверсий до конца этого окна.

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

Стратегические компромиссы при автоматической блокировке окон

• Ускоренная отправка постбэка: Досрочное завершение конверсии позволяет рандомизированной задержке постбэка от Apple начаться немедленно, быстрее доставляя данные конверсий рекламным сетям.
• Независимость окон: Блокировка текущего окна не сдвигает начало следующего окна вперед; Окно 2 все равно начинается на 3-й день независимо от того, когда было заблокировано Окно 1.
• Усечение периода наблюдения: После блокировки окна система игнорирует последующие вызовы обновления значений конверсий до конца этого окна конверсии. Внутриигровые события могут продолжать происходить, но они больше не могут изменить состояние конверсии SKAdNetwork для этого окна.

Координация схем SKAN с AdAttributionKit

Развивающийся стек атрибуции от Apple

Теперь Apple рекомендует использовать AdAttributionKit для рекламных кампаний приложений в App Store и на альтернативных торговых площадках приложений. SKAdNetwork по-прежнему актуален для существующих интеграций и обеспечения совместимости, поэтому движкам динамического маппинга следует отделять уровень бизнес-правил от API конверсий, специфичных для конкретного фреймворка:

• Общие размерности значений: Оба фреймворка оценивают 6-битные точные значения (от 0 до 63) и 3-уровневые общие значения (low, medium, high).
• Различные уровни API: SKAdNetwork использует SKAdNetwork.updatePostbackConversionValue, в то время как AdAttributionKit использует Postback.updateConversionValue.
• Логика сопряжения: Если интеграция поддерживает оба фреймворка, Apple рекомендует вызывать API обновления конверсий для обоих фреймворков, учитывая при этом задокументированное поведение сопряжения между SKAdNetwork и AdAttributionKit.

Сравнительная матрица решений: жестко закодированная клиентская логика против динамической конфигурации

Резюме и фреймворк принятия решений

Автоматизация маппинга значений конверсий SKAdNetwork отделяет эксперименты с ростом от циклов выпуска мобильных бинарных файлов. Распространяя динамические схемы с централизованной панели управления атрибуцией и оценивая их локально внутри SDK, инженерные команды могут точечно настраивать корзины доходов, оптимизировать этапы воронки и конфигурировать автоматическую блокировку окон, позволяя вносить изменения в поддерживаемые правила конверсии без повторной отправки бинарных файлов приложений в App Store Connect.

Маршрутизация диплинков на уровне приложения может работать параллельно с фреймворками конфиденциальной атрибуции от Apple в качестве отдельного слоя измерения и онбординга. Такие платформы, как OpoInstall, предоставляют инфраструктуру для контекстной маршрутизации первой стороны и отложенных диплинков, позволяя командам сохранять намерения пользователей на воронках конверсии из веб-среды в приложение.

Чтобы узнать больше о настройке конфиденциальных пайплайнов атрибуции и диплинков, ознакомьтесь с документацией OpoInstall.

Связанные материалы

• Концепции: Схемы значений конверсий, Динамический маппинг схем, Распределение доходов по корзинам, Блокировка окон, Монотонность

• Технологии: Apple SKAdNetwork, Apple AdAttributionKit, Фреймворк StoreKit, Мобильный SDK OpoInstall

• Стандарты: Спецификация JSON IETF RFC 8259

• API: API updatePostbackConversionValue в StoreKit, API Postback.updateConversionValue в AdAttributionKit

Официальная документация

• Документация для разработчиков Apple по обновлению значений конверсий постбэка

• Документация для разработчиков Apple по SKAdNetwork

• Документация для разработчиков Apple по AdAttributionKit

• Документация для разработчиков Apple по получению постбэков в нескольких окнах конверсии

• Понимание взаимодействия AdAttributionKit и SKAdNetwork