2026年Google Play Install Referrer API教程：归因数据与连接状态

只要花钱买量，安装归因就是唯一撑得住的度量；而在 Google Play 上，它来自一个很小的接口：Install Referrer API。它不是后台报表，也不会给你发邮件——它只在安装时把 Play 记录下来的归因内容交给你的应用一次，之后的存储与对账都是你的责任。本教程把整条链路走完：接口返回什么、怎么连接、怎么读响应、绝大多数团队发现得太晚的 90 天规则，以及每种连接状态该怎么处理。

以下内容全部以 Google 官方两页参考文档为准：Install Referrer API 与 Play Install Referrer Client Library，均于 2026-10-27 核对。

该接口取回的是 Play 商店应用记录的归因内容，官方列明的字段很少、也很具体：

• 已安装包的 referrer 链接；
• 点击时间的秒级时间戳（客户端与服务端都可取）；
• 开始安装时间的秒级时间戳（同样客户端与服务端都可取）；
• 首次安装时的应用版本号；
• 用户在过去 7 天内是否与你的 instant 体验有过交互。

两个硬性前提：该接口由设备上的 Play 商店应用提供，Play 商店版本 8.3.73 及以上的设备自动具备访问能力；你还需要一个 Google Play Console 账号。接口底层是 AIDL，Kotlin 与 Java 开发者应按官方建议使用客户端库封装，而不是直接对接 AIDL。

由此得出的设计结论：这是首次安装归因，带点击时间戳与开始安装时间戳。响应里没有多触点链路、没有曝光归因、也没有跨设备图谱。若你的报表模型依赖其中任何一项，数据必须另找来源。

在 app 模块的 build.gradle 里加依赖，文档给出的版本是 2.2：

dependencies {
    ...
    implementation "com.android.installreferrer:installreferrer:2.2"
}

若模块使用 Kotlin DSL，写法为 implementation("com.android.installreferrer:installreferrer:2.2")。除此之外不需要别的：不用注册清单里的 receiver、不用申请权限、Play Console 也没有开关。这个库替代的正是旧的广播接收器方案——两条链路不要同时留。

连接是异步的，绝大多数写坏的实现都从这一步开始。官方流程是：用 InstallReferrerClient.newBuilder(this).build() 创建客户端，调用 startConnection()，并传入一个 InstallReferrerStateListener 接收结果。

referrerClient = InstallReferrerClient.newBuilder(this).build()
referrerClient.startConnection(object : InstallReferrerStateListener {
    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        when (responseCode) {
            InstallReferrerResponse.OK -> { /* 连接建立 */ }
            InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> { /* 该 Play 商店应用不支持此接口 */ }
            InstallReferrerResponse.SERVICE_UNAVAILABLE -> { /* 连接无法建立 */ }
        }
    }
    override fun onInstallReferrerServiceDisconnected() {
        /* 下次请求前重新调用 startConnection() */
    }
})

按字面读这份回调契约。OK 表示连接成功，可以继续。FEATURE_NOT_SUPPORTED 表示该设备的 Play 商店应用不具备此接口——是商店版本的问题，不是你代码的 bug。SERVICE_UNAVAILABLE 表示连接根本没建立起来，这是时机问题，不是结论。

断连是常态而非异常：Google 明确说明，Play 商店服务在后台更新时客户端可能丢失连接，客户端必须在下次请求前重新调用 startConnection() 重启连接。所以这个监听器不是一次性用的，它是一台需要你驱动的状态机。

连接建立后，getInstallReferrer() 是同步调用，返回 ReferrerDetails 对象，字段与第一步列的载荷一一对应：

val response: ReferrerDetails = referrerClient.installReferrer
val referrerUrl: String = response.installReferrer
val referrerClickTime: Long = response.referrerClickTimestampSeconds
val appInstallTime: Long = response.installBeginTimestampSeconds
val instantExperienceLaunched: Boolean = response.googlePlayInstantParam

其中两个字段比看上去更有用。referrerClickTimestampSeconds 与 installBeginTimestampSeconds 让你按渠道算出「点击到开始安装」的间隔——间隔偏大通常说明丢人的是商店页，不是广告。googlePlayInstantParam 指示这次安装是否在过去 7 天内来自 instant 体验，这是响应里唯一的 instant 归因信号。

就是这句话让很多团队丢掉历史数据：安装归因信息可用期为 90 天，且除非应用被重新安装，该值不会变化。紧接着的官方建议同样直接——为避免不必要的接口调用，只应在安装后的首次执行时调用一次。

90 天不是存储许可，而是「值仍可从 Play 取回」的窗口；只在某次后续会话里懒加载读取的应用，等于给自己设了一个硬截止日。正确做法是首次运行即读取并落库。又因为除非重装否则值不变，任何刷新循环都换不来新信息，只是徒增调用。

读完之后关闭连接：在客户端上调用 endConnection()。Google 给出的理由很明确——关闭连接可以避免设备上的泄漏与性能问题。

首次启动的归因读取处在用户体验的关键路径上，所以失败策略和代码本身一样重要。一份可落地的映射：

• OK —— 读取、落库、endConnection()。后续启动不再读。
• SERVICE_UNAVAILABLE —— 当作「现在不行」。不写入任何值、不阻塞首屏，在 90 天窗口内的后续启动里重试。
• FEATURE_NOT_SUPPORTED —— 该设备上没有这个接口。改用你自己链接携带的渠道标识兜底，并把「不支持」这一状态记下来，否则报表会把它静默算成自然量。
• 已断连 —— 下次请求前用 startConnection() 重启，不要假设客户端还活着。

这四种之上还有一条工程铁律：归因绝不能阻塞首次使用，读取失败也绝不能写入一行假的「自然量」归因。报表对不上账，问题几乎都出在「没有数据」被当成了「自然量」。

客户端库把 referrer 以字符串形式返回。它由平台传递，但内容终究源自你的应用之外，因此对外部输入的常规卫生处理一样适用：防御式地解析成键值对、限制长度、绝不未经校验地拼进 URL、深链路由或数据库查询。

实操上就是：解码、按官方分隔符切分、只保留你确实认识的渠道键，其余全部丢弃；然后在它变成计费或收入依据之前，用你自己的服务端事件复核一遍。归因数据决定预算分配给谁——一个未经校验的字符串不应该具备「挪动钱」的能力。

如果这个字符串还要转交给广告网络或 MMP，请在链路交付之前——而不是审计之后——核对 Play 的 Data safety 声明与隐私政策是否已覆盖这项共享。归因链路本身就是数据收集，声明必须如实描述它。

归因争议大多不是因为响应错了，而是因为期待错了。按官方两页文档，诚实的边界是：

• Play 商店低于 8.3.73 的设备根本没有这个接口——必须准备兜底，FEATURE_NOT_SUPPORTED 是真实结果，不是记一行日志就能忘的异常。
• 值在首次安装时固化，除非重装否则不变——它表达不了再互动、升级或后续的渠道触碰。
• 超过 90 天不再可取——在这个窗口内没有落库的信息就永久丢失。
• instant 体验标记只覆盖 7 天回看。
• 它是来自 Play 安装的设备与账号级信号，不是用户身份，也不会跨设备去重。

把这五条写进与归因表结构同一份文档里。当投放报表和收入报表打架时，矛盾多半是这五句话里的某一句，而不是客户端有 bug。

资料来源：Android Developers —— Google Play Install Referrer API（developer.android.com/google/play/installreferrer）：返回字段、Play 商店 8.3.73+ 要求、AIDL 接口、Play Console 账号要求。Android Developers —— Play Install Referrer Library（developer.android.com/google/play/installreferrer/library，页面更新于 2026-10-23）：依赖版本 2.2、连接流程与响应码、getInstallReferrer() 与 ReferrerDetails 字段、90 天可用期说明、每次安装仅调用一次的建议，以及 endConnection()。两页均于 2026-10-27 核对。Google 未公布各渠道归因率或商店侧延迟数据，本文不作推断。