如何将跟踪参数从移动网页传递至 App 安装

如何将跟踪参数从移动网页传递至应用商店安装？ 从移动网站到新安装 App 的跟踪参数传递过程，涉及加载 OpoInstall Web JS SDK、捕获已加入白名单的 URL 参数，并在 App 首次启动时通过原生 SDK 还原受支持的归因数据。

跨应用商店下载的参数拼接，是指在用户从移动端落地页跳转至应用商店，并随后启动新安装应用的过程中，保留符合条件的 Web URL 参数。Web SDK 负责捕获活动或引荐上下文，而平台支持的机制或延迟还原服务则使相关参数可被原生 App 获取。还原效果取决于平台、SDK 配置、匹配信号以及隐私合规要求。

从网页到商店的归因鸿沟：各应用商店的平台壁垒

连接阻碍：操作系统沙盒如何隔离浏览器上下文

Web 分析通常使用 URL 查询字符串，包括 UTM 标签（utm_source, utm_medium, utm_campaign）、广告点击标识符（如 gclid 和 fbclid）以及自定义引荐参数。

在参与的网站内，浏览器 API 和第一方分析系统可以捕获这些数值，用于特定的分析与活动工作流。

当访客离开浏览器进入应用商店安装流程时，挑战随之产生。浏览器和新安装的原生应用运行在相互隔离的环境中。浏览器 Cookie、会话存储和页面 URL 参数无法在安装后自动传递到应用内部。

因此，开发者需要借助商店支持的引荐机制或延迟参数还原工作流，将安装前的上下文与安装后的 App 会话进行关联。

平台差异：Apple App Store 与 Google Play Store 的数据获取

移动应用商店支持不同的引荐上下文传递方式。

• Apple App Store (iOS): 标准的应用商店安装流程不会自动将外部 URL 查询参数转发到新安装 App 的首次启动环境中。延迟还原服务或明确的用户触发工作流可以协助恢复符合条件的上下文，前提是必须遵循 Apple 的隐私政策要求。
• Google Play Store (Android): Google 提供了官方的 Google Play Install Referrer API。在正确构建 Google Play 引荐流程的情况下，已安装的 App 可以检索受支持的引荐元数据，包括引荐字符串和相关的时间戳。

这些机制不能互换使用。Google Play 提供了官方的商店级引荐接口，而 iOS 上任何形式的延迟参数还原都需要单独设计并符合合规的机制。

归因丢失对营销 ROI 计算的商业影响

如果活动参数在网页访问和 App 安装之间丢失，分析系统将无法准确地将安装事件与原始活动相关联。

这可能导致安装归因失效、获取报告不全，以及对投资回报率 (ROI) 或获客成本 (CAC) 的计算产生误差。

参数丢失还会影响用户的新手引导体验。例如，网页引荐链接可能包含邀请人 ID 或优惠码：

https://example.com/download?inviter_id=USR_1024
https://example.com/download?promo_code=WELCOME50

如果 App 无法恢复这些数值，用户可能需要手动重新输入。

需要注意的是，恢复引荐或促销数值并不等同于自动授权奖励。应用后端必须独立校验其合规性、兑换限额及相关的业务规则。

商店支持与延迟参数机制：Apple App Store 对比 Google Play

Google Play Store 机制：利用原生 Install Referrer API

在 Android 上，Google Play Install Referrer API 为获取受支持的安装引荐元数据提供了官方机制。

Google Play 下载链接可以包含经过编码的 referrer 参数：

https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dfacebook%26inviter_id%3DUSR_1024

在这个示例 URL 中，编码后的引荐值代表：

utm_source=facebook&inviter_id=USR_1024

安装后，原生 Android 应用可以使用 Install Referrer Client 检索来自 Google Play 的引荐信息。

特定版本的 OpoInstall Web SDK 是否会自动生成、修改或管理此类 URL，必须对照其已部署的文档与行为进行核实。Google 官方 API 的存在并不等同于第三方 SDK 内部的实现逻辑。

Apple App Store 边界：处理标准商店跳转且无原生查询参数的情况

Apple App Store 不会直接将任意 Web 查询参数传递给新安装 App 的首次启动回调。

因此，延迟还原工作流可能涉及在跳转商店前捕获允许的活动信息，并在原生应用启动时请求相关上下文。

对于基于 SDK 的工作流，开发者必须明确厂商提供的功能文档与实际部署的 SDK 版本所使用的匹配方法之间的区别。

任何匹配或数据收集方法必须符合 Apple 的隐私政策。特别是归因实现不得依赖禁止的设备指纹识别，也不应假设 ATT 权限授权即可使原本禁止的匹配方法变得合规。

Universal Links 有助于将链接跳转至已安装的 App，但它们本身不能保证任意 Web 查询参数在经过全新 App Store 安装后依然留存。

跨平台架构分歧：构建统一的参数契约

尽管 Android 和 iOS 使用不同的平台机制，但应用可以将恢复后的数值归一化为共享的应用级架构。

例如：

{
  "utm_source": "facebook",
  "utm_medium": "paid_social",
  "utm_campaign": "summer_sale",
  "inviter_id": "USR_1024",
  "promo_code": "WELCOME50"
}

该 JSON 对象代表了应用定义的归一化参数契约，而非每一版 OpoInstall SDK 的固定响应格式。

应用应将这些字段分为两类：

• 营销归因: utm_source, utm_medium 和 utm_campaign。
• 引荐与促销动作: inviter_id 和 promo_code。

营销归因数据可提交至授权的分析管道。引荐与促销动作则需要独立的服务器端授权，App 才能授予任何权益。

上下文载荷缓存的作用及其在商店跳转中的应用

延迟还原服务通常要求为安装上下文设置有限的保留期限。

适用的保留窗口、还原行为和匹配可用性取决于已部署的服务、SDK 配置、网络状况、平台限制及隐私要求。

工程团队应基于自身的安装队列来评估还原效果，而非盲目采纳不受支持的准确率宣称。

关注隐私的延迟上下文架构与平台边界

iOS 系统粘贴板边界：透明度横幅与 UIPasteControl 意图机制

一些旧式的延迟链接实现会利用系统粘贴板在 App 间携带临时上下文。

然而，iOS 会限制并向用户展示跨应用粘贴板的访问行为。

• iOS 14: 读取从其他 App 复制的内容可能会触发粘贴板访问通知。
• iOS 16 及更高版本: 某些编程读取操作可能会触发权限提示。诸如 UIPasteControl 之类的控件支持用户发起的粘贴互动。

因此，粘贴板访问不得被视为一种隐形或不受限制的安装参数传输通道。

使用粘贴板相关功能的 App 应确保交互符合用户预期，并妥善处理拒绝授权或内容缺失的情况。

Android 前台剪贴板限制：导航约束与自动清除

Android 对剪贴板访问同样实施了限制。

• Android 10 及更高版本: 对处于非前台状态的 App 访问剪贴板实施限制，平台预定义的例外情况除外。
• Android 13 及更高版本: Android 为剪贴板内容提供了 UI 反馈和自动清除机制。

App 不应假设剪贴板数据可以静默检索或长期留存。

剪贴板访问应作为可选项，并仅用于适宜的用户交互场景，而非作为默认的归因核心渠道。

严格遵守 Apple 用户隐私与数据使用政策：禁止设备指纹识别

Apple 禁止通过结合设备及环境特征来识别用户或设备的指纹技术。

实现过程中，不得构建基于 IP 地址、User Agent 信息、显示属性或其他设备信号的持续性或概率性标识符，以免违反 Apple 政策。

获得 App Tracking Transparency (ATT) 权限并不能使被禁止的指纹识别方法变得合规。

对于任何第三方延迟参数还原服务，开发者应审查已部署 SDK 的实际数据收集与匹配行为、隐私披露条款以及平台策略要求。

追求隐私合规的集成方案应优先考虑数据最小化、透明的用户交互以及受支持的平台原生机制。

安全与信任边界：参数生命周期管理与服务端授权

所有恢复后的参数均需被视为不可信输入。

营销标签和引荐令牌可能来源于可编辑的 URL 或不受信任的客户端请求。它们的存在本身并不能证明活动合法或用户拥有奖励领取资格。

App 开发应遵循以下原则：

• 白名单校验： 仅接受明确支持的 Key 和限定范围的数值。
• 分离归因与授权： UTM 值可用于描述流量来源；它们绝不能独立用于授权促销福利。
• 限时记录： 仅保留处理所需的信息，并设置应用定义的过期窗口。
• 受保护的存储： 对敏感的待处理令牌使用安全存储，例如在有必要时使用 Android Keystore 或 iOS Keychain Services。
• 独立的结果交付： 对于包含营销与奖励双重参数的记录，App 必须独立跟踪所需的结果。
• 服务端奖励校验： 引荐奖励、促销折扣及类似权益必须经由经过认证的 App 后端确认后方可授予。
• 幂等奖励申请： 后端应强制执行交易级幂等性及业务级唯一性限制，防止重复请求导致一次性奖励被滥领。

下述代码展示了参数边界以及宿主应用的集成责任。它不试图提供一套完整的生产级存储、分析或奖励交易系统。

端到端实现：从网页参数捕获到原生还原

清洗 Web 查询参数：HTML Bootstrap、白名单解析与 Web JS SDK 设置

落地页可以捕获明确支持的查询参数，并将它们作为受控载荷传递给 Web SDK。

下例展示了：

• 从配置的来源加载 SDK。
• 保留正常的 HTTPS 下载兜底链接。
• 仅接受受支持的参数 Key。
• 拒绝超出严格字符长度政策的数值。
• 将 SDK 下载动作绑定到页面的下载按钮。

SDK 构造函数、配置 Key 和方法均为参考示例。在发布或部署前，请务必核对具体部署的 OpoInstall Web SDK 版本的签名。

<!-- CODE_BLOCK_01: 示例 HTML Bootstrap 与 Web SDK 集成 -->
<!-- 文件: landing_page.html -->

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>下载 App</title>
</head>
<body>
    <!-- 请替换为实际的 HTTPS 下载链接或商店跳转 URL。 -->
    <a
        id="download-app-btn"
        href="https://app.example.com/store-download"
    >
        下载 App
    </a>

    <!-- 请核对 CDN URL 与已部署的 SDK 版本。 -->
    <script src="https://web.cdn.opoinstallcloud.com/openinstall.js"></script>

    <script>
    (function () {
        "use strict";

        function getSanitizedQueryParams() {
            var allowedKeys = new Set([
                "utm_source",
                "utm_medium",
                "utm_campaign",
                "inviter_id",
                "promo_code"
            ]);

            var validPattern = /^[A-Za-z0-9_.-]{1,64}$/;
            var result = Object.create(null);

            try {
                var query = new URLSearchParams(window.location.search);

                query.forEach(function (value, key) {
                    if (
                        allowedKeys.has(key) &&
                        validPattern.test(value) &&
                        !Object.prototype.hasOwnProperty.call(result, key)
                    ) {
                        result[key] = value;
                    }
                });
            } catch (error) {
                console.warn("无法解析 URL 参数。");
                return Object.create(null);
            }

            return result;
        }

        var downloadButton = document.getElementById(
            "download-app-btn"
        );

        // 保持 anchor href 作为浏览器的正常兜底链接。
        if (!downloadButton) {
            return;
        }

        if (typeof OpenInstall === "undefined") {
            console.warn(
                "Web SDK 不可用；使用下载链接。"
            );
            return;
        }

        var customParams = getSanitizedQueryParams();

        try {
            new OpenInstall({
                appKey: "OPOINSTALL_APPKEY_PLACEHOLDER",
                data: customParams,

                onready: function () {
                    var sdkClient = this;

                    downloadButton.addEventListener(
                        "click",
                        function (event) {
                            try {
                                // 示例 SDK 方法。
                                // 请根据部署版本确认其行为和异步错误处理。
                                sdkClient.wakeupOrInstall();
                                event.preventDefault();
                            } catch (error) {
                                console.warn(
                                    "SDK 操作失败；浏览器将使用兜底链接。"
                                );

                                // 不要阻止默认的 anchor 点击行为。
                            }
                        }
                    );
                }
            });
        } catch (error) {
            console.warn(
                "Web SDK 初始化失败；使用兜底链接。"
            );
        }
    })();
    </script>
</body>
</html>

数值校验策略仅允许字母、数字、下划线、短横线和点，最大长度为 64 个字符。

包含空格或其他字符的数值在此参考实现中被排除在外。有更广泛 UTM 命名要求的团队，应定义并测试适用于字段的特定 Schema，而不是盲目假设所有 URL 值都受到支持。

同样地，诸如 gclid 和 fbclid 等广告点击标识符虽是常见的 Web 归因概念，但未包含在此示例白名单中。支持它们需要额外的数据收集、保留期规定和隐私审查。

当 SDK 无法加载或初始化时，兜底链接依旧可用。由于 SDK 操作可能异步失败，生产环境的集成必须额外遵循 SDK 文档说明的错误处理和重定向逻辑；仅靠同步的 try/catch 并非完整的异步兜底策略。

Android 原生实现：SDK 设置、参数校验与宿主应用契约

安装后，Android 应用可以从原生 SDK 请求受支持的参数，并将它们归一化为应用定义的记录。

下述示例特意将职责进行了解耦：

1. OpoInstall SDK 在应用主进程中初始化。
2. 原生回调提供候补载荷。
3. App 对载荷进行校验和归一化处理。
4. App 通过宿主提供的存储接口保存记录。
5. 宿主提供的处理组件协调营销归因与奖励授权。
6. App 仅在组件报告处理结果已确认后才将记录标记为完成。

重要提示： 宿主接口是应用定义的契约，而非 OpoInstall API。本示例要求宿主应用提供实现。它不包含不安全的兜底存储、模拟的分析上报或奖励授权响应。

// CODE_BLOCK_02: Android 集成示例 (Kotlin)
// 文件: CustomApplication.kt 和 MainActivity.kt
//
// 请核对 OpoInstall 导入项和回调方法与已部署的 AAR 文件。
// 在参数处理前必须先提供宿主实现。

package com.example.app

import android.app.ActivityManager
import android.app.Application
import android.content.Context
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.os.Process
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.opoinstall.api.OpoInstall
import com.opoinstall.api.OpoData
import com.opoinstall.api.OpoError
import com.opoinstall.api.ResultCallBack
import org.json.JSONObject
import java.util.UUID

enum class ParamFetchState {
    NOT_STARTED,
    FETCHING,
    RECEIVED,
    APPLIED,
    REJECTED,
    NO_MATCH,
    RETRYABLE_FAILURE
}

data class PendingAttributionRecord(
    val utmSource: String?,
    val utmMedium: String?,
    val utmCampaign: String?,
    val inviterId: String?,
    val promoCode: String?,
    val idempotencyKey: String,
    val createdAt: Long,
    val expiresAt: Long
) {
    val hasAttributionData: Boolean
        get() = listOf(
            utmSource, utmMedium, utmCampaign
        ).any { !it.isNullOrEmpty() }

    val hasRewardData: Boolean
        get() = !inviterId.isNullOrEmpty() ||
                !promoCode.isNullOrEmpty()

    val hasAnyData: Boolean
        get() = hasAttributionData || hasRewardData

    fun isValid(): Boolean {
        val now = System.currentTimeMillis()
        val pattern = Regex("^[A-Za-z0-9_.-]{1,64}$")

        val values = listOf(
            utmSource, utmMedium, utmCampaign,
            inviterId, promoCode
        )

        val validFields = values.all {
            it == null || pattern.matches(it)
        }

        val validWindow =
            expiresAt > createdAt &&
            expiresAt - createdAt <= 48L * 60 * 60 * 1000 &&
            now >= createdAt &&
            now <= expiresAt

        val validId = try {
            UUID.fromString(idempotencyKey)
            true
        } catch (_: IllegalArgumentException) {
            false
        }

        return hasAnyData &&
               validFields &&
               validWindow &&
               validId
    }
}

// 宿主定义的受保护持久化契约。
// 实现应区分数据丢失与存储故障，并按需处理账号绑定。
interface PendingTransactionStore {
    fun save(record: PendingAttributionRecord): Boolean
    fun load(): PendingAttributionRecord?
    fun clear(): Boolean
}

// 宿主定义的协调器。实现负责独立的遥测/奖励确认、
// 幂等性、重试处理及交易身份核对。
interface InstallParameterProcessor {
    fun process(
        record: PendingAttributionRecord,
        onComplete: (ProcessingOutcome) -> Unit
    )
}

enum class ProcessingOutcome {
    COMPLETED,
    REJECTED,
    RETRYABLE_FAILURE
}

// 这些是应用依赖，而非 OpoInstall SDK API。
object HostAppDependencies {
    var transactionStore: PendingTransactionStore? = null
    var parameterProcessor: InstallParameterProcessor? = null

    val isConfigured: Boolean
        get() = transactionStore != null &&
                parameterProcessor != null
}

class CustomApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        if (isMainProcess()) {
            OpoInstall.initialize(this)

            // 宿主应用在此配置依赖
            // 使用其内部的 DI/Bootstrap 机制。
            //
            // HostAppDependencies.transactionStore =
            //     hostProvidedProtectedStore
            //
            // HostAppDependencies.parameterProcessor =
            //     hostProvidedInstallParameterProcessor
        }
    }

    private fun isMainProcess(): Boolean {
        val manager = getSystemService(
            Context.ACTIVITY_SERVICE
        ) as ActivityManager

        val currentPid = Process.myPid()

        return manager.runningAppProcesses?.any {
            it.pid == currentPid &&
            it.processName == packageName
        } == true
    }
}

class MainActivity : AppCompatActivity() {

    private val mainHandler = Handler(Looper.getMainLooper())

    private var state = ParamFetchState.NOT_STARTED
    private var activeRecord: PendingAttributionRecord? = null
    private var processingInFlight = false

    private val transactionTtlMs =
        24L * 60 * 60 * 1000

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        startParameterFlow()
    }

    private fun startParameterFlow() {
        val store = HostAppDependencies.transactionStore
        val processor = HostAppDependencies.parameterProcessor

        if (store == null || processor == null) {
            Log.w(
                "OpoInstall",
                "宿主依赖不可用；处理已挂起"
            )
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        // 示例记录恢复。
        // 生产环境存储应区分“读取失败”与“确认无记录”。
        val existingRecord = try {
            store.load()
        } catch (error: Exception) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (existingRecord != null) {
            if (existingRecord.isValid()) {
                activeRecord = existingRecord
                state = ParamFetchState.RECEIVED
                processRecord(existingRecord)
            } else {
                // 无效或过期记录不再处理。
                if (!store.clear()) {
                    state = ParamFetchState.RETRYABLE_FAILURE
                    return
                }

                requestInstallParameters()
            }
        } else {
            requestInstallParameters()
        }
    }

    private fun requestInstallParameters() {
        if (!HostAppDependencies.isConfigured) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (state == ParamFetchState.FETCHING ||
            state == ParamFetchState.APPLIED ||
            state == ParamFetchState.NO_MATCH ||
            processingInFlight
        ) {
            return
        }

        state = ParamFetchState.FETCHING

        // 示例 SDK 回调。
        // 对照部署的 AAR 核对签名。
        OpoInstall.getInstance().getInstallParam(
            object : ResultCallBack<OpoData> {

                override fun onResult(opoData: OpoData?) {
                    mainHandler.post {
                        if (state != ParamFetchState.FETCHING) {
                            return@post
                        }

                        val rawData: Any? = opoData?.data

                        val payload = when (rawData) {
                            is String -> rawData
                            is JSONObject -> rawData.toString()
                            is Map<*, *> -> try {
                                JSONObject(rawData).toString()
                            } catch (_: Exception) {
                                null
                            }
                            else -> null
                        }

                        val record = payload?.let {
                            parseAndSanitizeRawPayload(it)
                        }

                        if (record == null) {
                            // 未恢复有效数据。
                            // 这并不代表是自然安装。
                            state = ParamFetchState.NO_MATCH
                            return@post
                        }

                        val store =
                            HostAppDependencies.transactionStore

                        if (store == null ||
                            !HostAppDependencies.isConfigured
                        ) {
                            state = ParamFetchState.RETRYABLE_FAILURE
                            return@post
                        }

                        activeRecord = record

                        // 如果保存失败，不要声称已持久化。
                        val saved = try {
                            store.save(record)
                        } catch (_: Exception) {
                            false
                        }

                        if (!saved) {
                            Log.w(
                                "OpoInstall",
                                "待处理记录未能持久化"
                            )
                            state = ParamFetchState.RETRYABLE_FAILURE
                            return@post
                        }

                        state = ParamFetchState.RECEIVED
                        processRecord(record)
                    }
                }

                override fun onError(error: OpoError?) {
                    mainHandler.post {
                        if (state == ParamFetchState.FETCHING) {
                            Log.w(
                                "OpoInstall",
                                "安装参数检索失败"
                            )
                            state = ParamFetchState.RETRYABLE_FAILURE
                        }
                    }
                }
            }
        )
    }

    private fun parseAndSanitizeRawPayload(
        rawJson: String
    ): PendingAttributionRecord? {
        return try {
            if (rawJson.length > 4096) return null

            val json = JSONObject(rawJson)
            val pattern = Regex("^[A-Za-z0-9_.-]{1,64}$")

            fun field(key: String): String? =
                (json.opt(key) as? String)?.takeIf {
                    pattern.matches(it)
                }

            val now = System.currentTimeMillis()

            val record = PendingAttributionRecord(
                utmSource = field("utm_source"),
                utmMedium = field("utm_medium"),
                utmCampaign = field("utm_campaign"),
                inviterId = field("inviter_id"),
                promoCode = field("promo_code"),
                idempotencyKey = UUID.randomUUID().toString(),
                createdAt = now,
                expiresAt = now + transactionTtlMs
            )

            record.takeIf { it.isValid() }
        } catch (_: Exception) {
            null
        }
    }

    private fun processRecord(
        record: PendingAttributionRecord
    ) {
        val processor = HostAppDependencies.parameterProcessor
        val store = HostAppDependencies.transactionStore

        if (processor == null || store == null ||
            !record.isValid()
        ) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (processingInFlight) return

        processingInFlight = true

        // 宿主处理器在确认所有特定渠道结果前，不得报告 COMPLETED。
        processor.process(record) { outcome ->
            mainHandler.post {
                // 忽略被取代或过期的交易。
                if (activeRecord?.idempotencyKey !=
                    record.idempotencyKey
                ) {
                    return@post
                }

                processingInFlight = false

                when (outcome) {
                    ProcessingOutcome.COMPLETED -> {
                        finalizeRecord(
                            record,
                            ParamFetchState.APPLIED
                        )
                    }

                    ProcessingOutcome.REJECTED -> {
                        finalizeRecord(
                            record,
                            ParamFetchState.REJECTED
                        )
                    }

                    ProcessingOutcome.RETRYABLE_FAILURE -> {
                        state =
                            ParamFetchState.RETRYABLE_FAILURE
                    }
                }
            }
        }
    }

    private fun finalizeRecord(
        record: PendingAttributionRecord,
        terminalState: ParamFetchState
    ) {
        val store = HostAppDependencies.transactionStore
            ?: run {
                state = ParamFetchState.RETRYABLE_FAILURE
                return
            }

        if (activeRecord?.idempotencyKey !=
            record.idempotencyKey
        ) {
            return
        }

        // 本例故意将持久化终端归档和原子清理留给宿主存储。
        // clear() 必须报告清理是否成功。
        val cleared = try {
            store.clear()
        } catch (_: Exception) {
            false
        }

        if (!cleared) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        activeRecord = null
        state = terminalState

        Log.i(
            "OpoInstall",
            "安装参数处理已完成"
        )
    }
}

Android 示例未包含 PendingTransactionStore 或 InstallParameterProcessor 的默认实现。

宿主应用必须在调用工作流前提供上述接口。

特别地，处理器不得仅仅因为运行了日志语句或启动了异步请求就返回 COMPLETED。完成结果必须对应实际载荷的处理要求：

• 纯 UTM 载荷： 所需归因事件已被配置的分析系统可靠接收或进入持久化队列。
• 纯奖励载荷： 经身份验证的 App 后端返回了接受的终端授权结果。
• 混合 UTM 与奖励载荷： 两个渠道都必须各自达成预期的结果，且任一渠道不得提前移除另一渠道所需的工作状态。

如果宿主应用需要跨进程恢复，处理器和受保护存储必须额外记录足够的各渠道进度，并保留稳定的交易标识符。

上述代码展示了集成边界，不能替代针对特定应用的逻辑实现。

iOS 原生实现：SDK 还原与应用集成契约

iOS 的集成遵循相同的边界原则。

原生 SDK 提供候补安装参数。App 进行载荷校验，通过宿主提供的存储组件持久化待处理记录，并将业务处理委托给应用所属的协调器。

代码为参考示例，必须根据已安装 OpoInstall iOS SDK 版本的模块名、代理协议和回调签名进行适配。

// CODE_BLOCK_03: iOS 集成示例 (Swift)
// 文件: AppDelegate.swift
//
// 核对模块和 SDK 方法与部署的 OpoInstall 框架版本。

import UIKit
import libOpoInstallSDK

enum ParamFetchState: String {
    case notStarted = "NOT_STARTED"
    case fetching = "FETCHING"
    case received = "RECEIVED"
    case applied = "APPLIED"
    case rejected = "REJECTED"
    case noMatch = "NO_MATCH"
    case retryableFailure = "RETRYABLE_FAILURE"
}

struct PendingAttributionRecord: Codable {
    let utmSource: String?
    let utmMedium: String?
    let utmCampaign: String?
    let inviterId: String?
    let promoCode: String?
    let idempotencyKey: String
    let createdAt: TimeInterval
    let expiresAt: TimeInterval

    var hasAttributionData: Bool {
        return [
            utmSource, utmMedium, utmCampaign
        ].contains { !$0.isNilOrEmpty }
    }

    var hasRewardData: Bool {
        return !inviterId.isNilOrEmpty ||
               !promoCode.isNilOrEmpty
    }

    var hasAnyData: Bool {
        return hasAttributionData || hasRewardData
    }

    var isValid: Bool {
        let now = Date().timeIntervalSince1970
        let window = expiresAt - createdAt

        let pattern = "^[A-Za-z0-9_.-]{1,64}$"

        let fields = [
            utmSource, utmMedium, utmCampaign,
            inviterId, promoCode
        ]

        let validFields = fields.allSatisfy { field in
            guard let field = field else { return true }
            return field.range(
                of: pattern,
                options: .regularExpression
            ) != nil
        }

        return hasAnyData &&
               validFields &&
               UUID(uuidString: idempotencyKey) != nil &&
               window > 0 &&
               window <= 48 * 60 * 60 &&
               now >= createdAt &&
               now <= expiresAt
    }
}

private extension Optional where Wrapped == String {
    var isNilOrEmpty: Bool {
        return self?.isEmpty ?? true
    }
}

// 宿主提供的受保护持久化契约。
protocol PendingTransactionStore {
    func save(_ record: PendingAttributionRecord) -> Bool
    func load() throws -> PendingAttributionRecord?
    func clear() -> Bool
}

enum ProcessingOutcome {
    case completed
    case rejected
    case retryableFailure
}

// 宿主提供用于分析与奖励处理的协调器。
protocol InstallParameterProcessor {
    func process(
        record: PendingAttributionRecord,
        completion: @escaping (ProcessingOutcome) -> Void
    )
}

// 这些是应用契约，而非 OpoInstall API。
struct HostAppDependencies {
    static var transactionStore: PendingTransactionStore?
    static var parameterProcessor: InstallParameterProcessor?

    static var isConfigured: Bool {
        return transactionStore != nil &&
               parameterProcessor != nil
    }
}

@UIApplicationMain
class AppDelegate:
    UIResponder,
    UIApplicationDelegate,
    OpoInstallDelegate {

    var window: UIWindow?

    private var state: ParamFetchState = .notStarted
    private var activeRecord: PendingAttributionRecord?
    private var processingInFlight = false

    private let transactionTTL: TimeInterval =
        24 * 60 * 60

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions:
            [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        // 示例 SDK 初始化。
        OpoInstallSDK.initWith(self)

        // 宿主应用必须在开始处理前注册依赖。
        //
        // HostAppDependencies.transactionStore =
        //     hostProvidedProtectedStore
        //
        // HostAppDependencies.parameterProcessor =
        //     hostProvidedInstallParameterProcessor

        startParameterFlow()
        return true
    }

    private func startParameterFlow() {
        guard HostAppDependencies.isConfigured,
              let store = HostAppDependencies.transactionStore
        else {
            print(
                "OpoInstall: 宿主依赖不可用"
            )
            state = .retryableFailure
            return
        }

        do {
            if let saved = try store.load() {
                if saved.isValid {
                    activeRecord = saved
                    state = .received
                    processRecord(saved)
                    return
                }

                guard store.clear() else {
                    state = .retryableFailure
                    return
                }
            }
        } catch {
            // 读取错误不代表存储空间为空。
            state = .retryableFailure
            return
        }

        requestInstallParameters()
    }

    private func requestInstallParameters() {
        guard HostAppDependencies.isConfigured,
              state != .fetching,
              state != .applied,
              state != .noMatch,
              !processingInFlight
        else {
            return
        }

        guard let manager = OpoInstallSDK.defaultManager()
        else {
            state = .retryableFailure
            return
        }

        state = .fetching

        // 示例回调签名。
        manager.getInstallParmsCompleted({
            [weak self] (appData: OpoinstallData?) in

            DispatchQueue.main.async {
                guard let self = self,
                      self.state == .fetching
                else {
                    return
                }

                let rawData: Any? = appData?.data

                guard let record =
                    self.parseAndSanitizeRawPayload(rawData)
                else {
                    // 未恢复有效自定义参数。
                    // 这不代表是自然流量。
                    self.state = .noMatch
                    return
                }

                guard HostAppDependencies.isConfigured,
                      let store =
                          HostAppDependencies.transactionStore
                else {
                    self.state = .retryableFailure
                    return
                }

                self.activeRecord = record

                guard store.save(record) else {
                    // 持久化失败时不要声称已确认。
                    self.state = .retryableFailure
                    return
                }

                self.state = .received
                self.processRecord(record)
            }
        })
    }

    private func parseAndSanitizeRawPayload(
        _ rawData: Any?
    ) -> PendingAttributionRecord? {

        guard let rawData = rawData else {
            return nil
        }

        var dictionary: [String: Any]?

        if let map = rawData as? [String: Any] {
            dictionary = map
        } else if let jsonString = rawData as? String,
                  jsonString.count <= 4096,
                  let data = jsonString.data(using: .utf8),
                  let parsed = try? JSONSerialization.jsonObject(
                      with: data
                  ) as? [String: Any] {
            dictionary = parsed
        }

        guard let payload = dictionary else {
            return nil
        }

        let pattern = "^[A-Za-z0-9_.-]{1,64}$"

        func field(_ key: String) -> String? {
            guard let value = payload[key] as? String,
                  value.range(
                    of: pattern,
                    options: .regularExpression
                  ) != nil
            else {
                return nil
            }

            return value
        }

        let now = Date().timeIntervalSince1970

        let record = PendingAttributionRecord(
            utmSource: field("utm_source"),
            utmMedium: field("utm_medium"),
            utmCampaign: field("utm_campaign"),
            inviterId: field("inviter_id"),
            promoCode: field("promo_code"),
            idempotencyKey: UUID().uuidString,
            createdAt: now,
            expiresAt: now + transactionTTL
        )

        return record.isValid ? record : nil
    }

    private func processRecord(
        _ record: PendingAttributionRecord
    ) {
        guard record.isValid,
              let processor =
                  HostAppDependencies.parameterProcessor
        else {
            state = .retryableFailure
            return
        }

        guard !processingInFlight else {
            return
        }

        processingInFlight = true

        // 宿主处理器需独立确认归因与奖励结果。
        processor.process(record: record) {
            [weak self] outcome in

            DispatchQueue.main.async {
                guard let self = self,
                      self.activeRecord?.idempotencyKey ==
                          record.idempotencyKey
                else {
                    return
                }

                self.processingInFlight = false

                switch outcome {
                case .completed:
                    self.finalizeRecord(
                        record,
                        terminalState: .applied
                    )

                case .rejected:
                    self.finalizeRecord(
                        record,
                        terminalState: .rejected
                    )

                case .retryableFailure:
                    self.state = .retryableFailure
                }
            }
        }
    }

    private func finalizeRecord(
        _ record: PendingAttributionRecord,
        terminalState: ParamFetchState
    ) {
        guard activeRecord?.idempotencyKey ==
                  record.idempotencyKey,
              let store =
                  HostAppDependencies.transactionStore
        else {
            state = .retryableFailure
            return
        }

        // 宿主存储需协调持久化完成与清理。
        guard store.clear() else {
            state = .retryableFailure
            return
        }

        activeRecord = nil
        state = terminalState

        print(
            "OpoInstall: 安装参数处理已完成"
        )
    }
}

iOS 示例未提供基于 UserDefaults 的待处理交易存储或自动上报结果的遥测客户端。

宿主应用必须根据安全、分析及账号管理要求，提供存储实现与参数处理器。

当 App 处理奖励参数时，处理器不得在服务端授权完成前返回 .completed。

当载荷仅包含营销数据时，完成状态应反映 App 定义的分析接收或队列可靠性要求。

对于混合记录，处理器需维护各渠道未决的任务，确保过期回调不会终结错误的交易。

本示例故意省略了完整的重试调度器和持久化多渠道交易日志。这些问题属于宿主应用实现的范畴，必须对照实际生命周期与后端进行测试。

生产环境集成边界与校验清单

在部署移动端代码前，工程团队应确认以下条件。

以上为集成验收标准，而非参考代码已通过生产测试的声明。

参数传递策略对比矩阵

参数恢复策略的方法论分析

移动获客系统采用不同方法在网页访问与原生应用间保持引荐与归因上下文。

具体的适用策略取决于目标平台、所需参数类型、允许的用户交互门槛、数据敏感度及可用的平台机制。

评估准确性、隐私合规、交互阻力与安全边界

人工输入优惠码方案在技术上易于理解，但增加了用户操作成本。

Google Play Install Referrer 提供了原生、由商店支持的 Android 引荐通道。

第三方参数还原 SDK 可为符合条件的延迟上下文提供应用级集成层。但其覆盖范围、技术实现及隐私特性必须根据已部署的版本进行评估。

无论采用何种还原方法，App 必须严格区分“参数接收”与“业务动作授权”。

排查参数还原、状态管理与 SDK 集成错误

客户端状态转换管理：处理无匹配、重试与终端结果

参数还原工作流可由七个逻辑状态描述：

上述状态描述的是应用级结果。它们不能取代宿主应用在分析、奖励、存储及重试方面的持久化协调逻辑。

特别地，纯营销记录无需奖励授权即可完成，而涉及奖励的记录必须获取适当的服务端响应。

NO_MATCH 结果不应被解读为安装是自然来源的最终证据。

优雅处理参数请求超时与网络延迟

参数还原可能受网络连接、回调时机、App 启动顺序或后端服务不可用的影响。

App 应该：

• 保持网络操作异步化。
• 避免在安装参数检索期间阻塞主用户界面。
• 区分 SDK 管理器不可用与参数结果为空的情况。
• 将本地持久化错误视为处理失败，而非确认无记录的证据。
• 按受限策略重试，而不是在每次前台转换时重复请求。
• 在必须重试操作时保留现有的待处理记录。

任何自动重试机制都应防止并发请求，并拒绝属于被取代交易的回调。

管理应用覆盖安装与过期参数缓冲区

参数还原通常针对符合安装条件的首次启动，但应用升级与重复启动可能会暴露此前存储的本地状态。

工程团队应定义还原尝试的触发时机、已消费记录的识别方法及待处理数据的过期逻辑。

对于涉及奖励的参数，服务端幂等性至关重要。仅靠客户端标志位无法有效防止重复奖励。

当 App 本地维护待处理交易时，仅在处理要求均已持久化解决后才可删除记录。

预防 Android 多进程初始化问题

具有多个进程的 Android 应用可能会多次执行 Application.onCreate()。

如果原生 SDK 仅需在主应用进程初始化，开发者应在执行初始化前校验当前进程名。

Android 示例演示了一种进程名比较策略。生产环境应用应核实该方法与其支持的 Android 版本及进程架构的匹配度。

调试客户端回调签名失配与代码压缩混淆规则

第三方 SDK 的包名、回调接口和类声明可能会随版本更新而变动。

当集成失败时，开发者应核实已部署的 SDK 实际代码，而非假设示例接口保持不变。

针对 Android 生产包构建：

• 优先使用 SDK 产物随附的 consumer R8/ProGuard 规则。
• 除非有明确证据，否则避免盲目添加宽泛的 -keep 或 -dontwarn 规则。
• 在添加补丁规则前，检查实际的反射需求。
• 在混淆后的 Release 配置中测试安装参数回调。

本指南中的代码仅为集成参考，若未经对应的构建与运行时验证，不可视为已通过发布认证。

总结与决策框架

将网页点击与移动应用商店安装进行关联，需要一套能够兼顾浏览器、应用商店与原生应用间技术边界的参数还原方案。

对于 Android，Google Play Install Referrer API 为支持的安装流提供了官方引荐机制。对于 iOS，任意 Web 参数不会自动通过 App Store 传递，因此延迟还原方案需要经过独立验证且关注隐私。

一个实用的 OpoInstall 集成方案应能够捕获白名单落地页参数，并经由原生 SDK 请求获取符合条件的上下文。随后，App 必须在将数据应用于营销归因、导航跳转或促销工作流前，对其进行归一化与校验。

核心工程决策在于区分参数还原与应用侧处理。成功恢复参数并不代表归因数据已生效、用户具备奖励资格或处理已成功授权。

本文提供的参考代码展示了 SDK 集成边界及应用定义的契约。生产环境团队必须提供自有的受保护存储、可靠的分析处理、服务端权益校验及生命周期协调机制。

欲了解厂商集成要求，请查阅 OpoInstall SDK 文档 或访问 OpoInstall 开发者注册页面。

相关资料

概念: App 参数安装, Google Play Install Referrer, 延迟参数还原, 归因遥测, 服务端授权边界。

技术: Web JS SDK, 原生移动 SDK, URL 查询参数, Android Keystore, iOS Keychain Services。

标准: IETF RFC 3986 URI 语法, OWASP 移动应用安全验证标准, W3C 剪贴板 API 与事件。

API: OpoInstall 原生安装参数 API, Google Play Install Referrer API, Apple UIPasteboard API, Android 剪贴板 API。

官方文档与引用:

• Apple Developer — 用户隐私与数据使用

• Android Developers — Google Play Install Referrer API

• W3C — 剪贴板 API 与事件规范

• OpoInstall — SDK 集成文档