AppsFlyer / Firebase Android SDK 接入需求文档
1. 背景与目标
我司为现金贷类 Android App，需要接入 AppsFlyer，用于海外投放归因、安装统计、关键业务漏斗事件统计、收益/金额类事件统计、卸载统计，以及将 AppsFlyer ID 与我司后端用户/设备体系关联。同时需要接入 Firebase，支持 Push 消息触达和 Crash 崩溃采集，满足海外投放后的召回、运营通知、问题定位和版本质量监控需求。
本需求文档面向研发评审，范围聚焦 Android 端：AppsFlyer Install SDK、Integrate SDK、In-app Event、Uninstall Measurement、getAppsFlyerUID，以及 Firebase Analytics、Firebase Cloud Messaging、Firebase Crashlytics。
2. 接入范围
| 模块 | 是否必须 | 说明 |
|---|---|---|
| AppsFlyer SDK 安装 | 必须 | 通过 Gradle 接入 SDK，保证安装、会话和事件可上报 |
| SDK 初始化与启动 | 必须 | 在全局 Application 初始化并启动 SDK |
| AppsFlyer UID 获取与后端关联 | 必须 | 获取 appsFlyerId 后传给后端，和用户、设备、订单、风控链路关联 |
| 应用内事件上报 | 必须 | 覆盖注册、提交申请、授信通过、首贷、借贷等现金贷核心漏斗 |
金额字段 af_revenue、af_currency | 必须 | 涉及金额/收益类事件必须按 AppsFlyer 规则上报 |
| 卸载统计 | 建议必须 | 用于分析获客质量、贷后触达、召回和渠道质量 |
| Firebase Push | 必须 | 通过 Firebase Cloud Messaging 支持运营通知、系统通知和召回触达 |
| Firebase 归因 | 必须 | 通过 Firebase Analytics/GA4 记录安装来源、营销活动和核心漏斗，作为 AppsFlyer 的补充分析口径 |
| Firebase Crash | 必须 | 通过 Firebase Crashlytics 采集崩溃、非致命异常和版本质量数据 |
| 测试设备白名单 | 必须 | 使用 GAID 加白，支持反复安装测试 |
3. 前置条件
- AppsFlyer 后台已创建 Android App，App ID 与 Android
applicationId保持一致。 - 产品/运营提供 AppsFlyer Dev Key、App ID、投放渠道、默认币种、后台时区。
- 本期投放国家为尼日利亚，默认币种采用奈拉，币种代码为
NGN。 - 测试设备 GAID 已加入 AppsFlyer 测试设备白名单。
- 研发确认当前 App 是否已接入 Firebase Cloud Messaging；该结论影响卸载统计方案。
- Firebase 项目已创建 Android App，Android 包名、SHA-1/SHA-256 证书指纹、环境区分方式已确认。
- 产品/运营确认 Push 使用场景、消息类型、跳转规则、默认渠道和用户退订/关闭通知后的产品策略。
- 研发确认 Crashlytics 是否按环境区分上报，Debug 包默认不进入正式质量报表。
- 产品/运营确认 Firebase 归因是否用于 Google Ads 关联、渠道补充分析和漏斗分析；AppsFlyer 仍作为付费投放归因主口径。
- 法务/合规确认隐私政策中已覆盖归因 SDK、广告 ID、设备标识、Push token、崩溃日志和事件数据上报说明。
4. SDK 安装需求
4.1 Gradle 依赖
研发需在项目仓库声明 mavenCentral()，并在 App 模块添加 AppsFlyer Android SDK 依赖。
建议版本策略：
| 项 | 要求 |
|---|---|
| SDK 版本 | 优先评估接入 Maven 最新版本 7.0.0；如项目需沿用 6.x 稳定 API，则至少使用 6.18.1 并单独评估后续 v7 迁移 |
| 依赖方式 | 使用 Gradle 依赖，不建议手动放置 aar |
| Google Play Install Referrer | 必须接入 com.android.installreferrer:installreferrer:2.2，提升安装归因准确性 |
| Meta Install Referrer | 如投放 Facebook/Instagram，需配置 Facebook App ID 供 SDK 读取 |
| Firebase BoM | 必须接入 Firebase BoM，统一管理 Firebase Messaging、Crashlytics 等依赖版本 |
| Firebase Messaging | 必须接入，用于 Push token 获取、前台/后台消息接收和 AppsFlyer 卸载统计 token 上报 |
| Firebase Analytics | 必须 |
| Firebase Crashlytics | 必须接入，用于采集崩溃、非致命异常、版本号和设备环境信息 |
Firebase Gradle 接入要求：
- 项目级 Gradle 需添加 Google Services 插件和 Crashlytics Gradle 插件。
- App 模块需应用
com.google.gms.google-services和com.google.firebase.crashlytics插件。 - App 模块需添加
google-services.json，并按开发、测试、生产环境区分配置文件或构建变体。 - Firebase 依赖版本统一由 Firebase BoM 管理，避免各 SDK 版本手动混配。
4.2 Android 权限
AndroidManifest.xml 必须包含：
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />Push 权限说明：
- Android 13 及以上必须在运行时申请
POST_NOTIFICATIONS权限。 - 未授权通知权限时，不得阻断 App 核心流程；客户端需记录授权状态，供运营判断可触达用户规模。
- Android 12 及以下无需运行时申请通知权限，但仍需支持系统通知开关关闭后的降级处理。
广告 ID 权限说明：
- SDK
6.8.0及以上会自动合并com.google.android.gms.permission.AD_ID。 - 我司现金贷 App 非儿童类应用，不需要移除 AD_ID。
- 若后续存在儿童/家庭政策适配包，需单独评估并移除 AD_ID。
4.3 备份规则
AppsFlyer SDK 会通过 Manifest 规则避免 appsflyer-data 被系统备份，以免卸载重装后复用旧计数器和旧 AppsFlyer ID，影响新安装/重装识别。若我司 App 自定义了 allowBackup、fullBackupContent 或 dataExtractionRules，研发需处理 Manifest merge 冲突，并保证 appsflyer-data 被排除备份。
5. SDK 初始化与启动需求
5.1 初始化位置
必须在全局 Application.onCreate() 中初始化 SDK，确保冷启动、深链、后台拉起等场景均可触发 SDK。
基础流程：
class App : Application() {
override fun onCreate() {
super.onCreate()
AppsFlyerLib.getInstance().init(AF_DEV_KEY, null, this)
AppsFlyerLib.getInstance().start(this)
}
}要求：
AF_DEV_KEY不得硬编码在业务代码散落位置，需通过统一配置管理。- Release 包不得开启 AppsFlyer debug log。
- Debug/测试包可开启
AppsFlyerLib.getInstance().setDebugLog(true)，用于 Logcat 搜索AppsFlyer_排查。 - 如因隐私同意弹窗需要延迟
start，init仍需在 Application 执行；start延迟后必须传入 Activity Context，否则可能丢失归因和事件。
5.2 启动回调
建议研发在测试包或灰度阶段使用 AppsFlyerRequestListener 监听 start 成功/失败，便于定位 Dev Key、网络、配置问题。生产环境可保留轻量错误日志，但不得记录敏感用户信息。
6. AppsFlyer UID 获取与后端关联
6.1 获取方式
Android 端必须在 SDK 初始化后获取 AppsFlyer UID：
val appsFlyerId = AppsFlyerLib.getInstance().getAppsFlyerUID(context)AppsFlyer UID 是 SDK 为安装生成的唯一 ID。卸载重装后该 ID 可能变化，因此不能作为我司永久用户 ID 使用，只能作为归因/安装维度 ID。
6.2 后端关联要求
客户端需在以下时机把 appsFlyerId 传给后端：
| 时机 | 是否必须 | 说明 |
|---|---|---|
| 用户登录成功后 | 必须 | 关联我司 user_id 与 appsFlyerId |
| 额度申请提交后 | 必须 | 关联 application_id，用于渠道质量和放款 ROI 分析 |
| 借款申请提交后 | 必须 | |
| 每次进入首页 | 必须 |
后端建议保存字段：
| 字段 | 说明 |
|---|---|
appsflyer_id | AppsFlyer UID |
user_id | 我司用户 ID，登录后必填 |
device_id | 我司设备 ID，如已有 |
gaid | Android Advertising ID，如合规允许获取 |
app_version | App 版本 |
package_name | Android 包名 |
install_time_client | 客户端首次获取时间 |
last_seen_time | 最近一次上报时间 |
7. 应用内事件需求
7.1 上报方式
AppsFlyer 事件支持两类命名：
| 类型 | 说明 | 本期使用 |
|---|---|---|
| 官方预置事件 | AppsFlyer 已定义的推荐事件名，通常以 af_ 开头，例如 af_complete_registration、af_login | 注册使用官方预置事件 |
| 自定义事件 | 我司按业务自定义的事件名，例如 apply、approved、loan | 贷款申请、授信通过、放款等现金贷业务事件使用自定义事件 |
上报通道分为 Android SDK 上报和后端 S2S 上报：
| 通道 | 适用场景 | 要求 |
|---|---|---|
| Android SDK 上报 | App 端可准确感知且不涉及资金最终状态的行为，例如注册成功、提交额度申请 | Android 端使用 logEvent |
| 后端 S2S 上报 | 以后端最终状态为准的事件，例如授信通过、首次成功放款、成功放款 | 后端调用 AppsFlyer S2S Events API，并必须携带 appsflyer_id |
Android 端使用 logEvent 上报事件：
AppsFlyerLib.getInstance().logEvent(
context,
eventName,
eventValues
)事件上报要求：
- 事件名必须稳定，不得随版本、语言、页面文案变化。
- 参数值不得包含手机号、身份证号、银行卡号、通讯录、精确地址等高敏感信息。
- 同一业务动作只上报一次，避免 10 秒内重复触发导致去重或数据偏差。
- 离线场景 SDK 会缓存事件，网络恢复后发送；关键风控/账务事件仍以我司后端为准。
- 涉及金额的事件必须同时上报
af_revenue和af_currency。 - 后端 S2S 上报必须基于业务幂等键去重，例如
loan_order_id + event_name，避免重复放款事件导致收入重复。
7.2 时效性说明
| 数据类型 | 预期时效 | 说明 |
|---|---|---|
| SDK Live Events | 近实时 | 用于联调验证事件是否到达 AppsFlyer |
| 安装归因面板 | 通常 15-30 分钟 | 白名单测试设备完成非自然安装后等待面板更新 |
| 应用内事件面板 | 通常 30-60 分钟 | 事件报表和看板存在处理延迟 |
| 后端 S2S 事件 | 取决于后端触发和 AppsFlyer 处理 | 授信通过、首贷、放款类事件以后端状态流转时间为准 |
| 卸载统计 | 最长可能 24-48 小时 | 卸载统计依赖 FCM 和 AppsFlyer 后台处理 |
7.3 现金贷核心事件表
| 业务事件 | 业务 event | AppsFlyer 实际上报事件名 | 事件类型 | 上报方 | 释义 | 必传字段 | 金额字段 |
|---|---|---|---|---|---|---|---|
| 注册 | register | af_complete_registration | 官方预置 | 后端 S2S | 用户注册成功 | af_registration_method、user_id_hash | 无 |
| 提交申请 | apply | apply | 自定义 | 后端 S2S | 用户提交额度申请 | application_id | 无 |
| 授信通过 | approved | approved | 自定义 | 后端 S2S | 额度申请通过 | application_id、`user_credit_level“—— ADLEVEL:A/B/C/D | 无 |
| 首贷 | first_loan | first_loan | 自定义 | 后端 S2S | 用户首次成功放款 | loan_order_id、first_loan_value、af_revenue、af_currency=NGN、user_credit_level | 必须上报，af_revenue=first_loan_value |
| 借贷 | loan | loan | 自定义 | 后端 S2S | 用户成功放款 | loan_order_id、loan_value、af_revenue、af_currency=NGN、user_credit_level | 必须上报，af_revenue=loan_value |
字段说明：
| 字段 | 是否必须 | 释义 | 示例 |
|---|---|---|---|
user_credit_level | 如有则传 | 用户额度等级，根据用户提交申请信息给用户分级额度标记 | A、B、C、D |
first_loan_value | 首贷事件必传 | 用户首次获得的借贷金额 | 50000 |
loan_value | 借贷事件必传 | 用户本次成功放款金额 | 50000 |
金额口径评审结论：
| 项 | 结论 |
|---|---|
| 金额上报事件 | 只在放款成功相关事件上报金额：first_loan、loan |
af_revenue 口径 | 放款本金金额；首贷为 first_loan_value，普通放款为 loan_value |
af_currency | 固定传 NGN |
| 非放款事件 | register、apply、approved 不上报 af_revenue |
7.4 金额与币种规则
af_revenue必须为纯数字，不得包含逗号、币种符号或文本，例如1234.56。af_currency必须固定传NGN，代表尼日利亚奈拉。- AppsFlyer 后台默认币种需配置为
NGN，并与我司 BI/数仓口径保持一致。 - 退款、冲正、撤销等负向收益本期不启用，不上报负数
af_revenue。
8. 卸载统计需求
8.1 接入方案
AppsFlyer Android 卸载统计依赖 Firebase Cloud Messaging。
| 当前 App 状态 | 接入要求 |
|---|---|
| 已接入 FCM | 在 FirebaseMessagingService.onNewToken() 中调用 updateServerUninstallToken(context, token) |
| 未接入 FCM | 新增 Firebase 配置、google-services.json、Firebase Messaging 依赖，并按官方方案接入卸载统计 |
已接入 FCM 的示例：
override fun onNewToken(token: String) {
super.onNewToken(token)
AppsFlyerLib.getInstance().updateServerUninstallToken(applicationContext, token)
}8.2 卸载测试与验收
- 安装测试包。
- 打开 App，确保 SDK 初始化并上传 FCM token。
- 卸载 App。
- 等待 AppsFlyer 面板出现卸载数据；官方说明最长可能需要 48 小时。
- 如果用户在处理周期内重装 App，可能不会记录卸载事件。
9. Firebase 接入需求
9.1 Firebase 基础配置
Firebase 接入需满足以下基础要求：
| 配置项 | 是否必须 | 要求 |
|---|---|---|
| Firebase 项目 | 必须 | 生产环境使用正式 Firebase 项目；测试环境建议独立项目或独立 App 配置 |
google-services.json | 必须 | 包名必须与 Android applicationId 匹配，不得把生产配置误放到测试包 |
| SHA 证书指纹 | 必须 | Firebase 后台需配置发布证书和调试证书，用于后续能力扩展和问题排查 |
| 构建环境隔离 | 必须 | Debug、Staging、Release 的 Push 和 Crash 数据需可区分 |
| 隐私合规 | 必须 | Push token、崩溃堆栈、设备信息和用户标识需纳入隐私政策与 SDK 清单 |
9.2 Push 需求
Firebase Push 基于 Firebase Cloud Messaging 接入，需支持运营通知、系统通知、召回通知和后续贷后触达。
功能要求：
- 客户端需继承
FirebaseMessagingService，处理onNewToken()、onMessageReceived()。 - FCM token 获取或刷新后必须上报后端，并同步调用 AppsFlyer
updateServerUninstallToken(context, token)。 - 后端需保存 FCM token 与
user_id、device_id、appsflyer_id、App 版本、语言、国家、通知授权状态的关系。 - 同一用户多设备、多 token 需保留有效 token 列表；发送失败或 token 失效时需支持后端清理。
- Push 消息需支持通知标题、正文、图片、业务类型、跳转目标、透传参数、过期时间和去重 ID。
- 前台收到 Push 时由客户端按产品规则展示站内提醒或系统通知；后台收到 Push 时由系统通知栏展示。
- Push 点击后需按 deep link 或业务参数打开指定页面；参数异常时回退到首页。
- Android 8.0 及以上需配置通知渠道，至少区分营销通知、系统通知、还款/账务通知。
- Android 13 及以上需按指定节点页面申请通知权限，并向后端同步授权结果。
- Push 内容不得包含身份证号、银行卡号、完整手机号、通讯录、精确地址等高敏感明文。
9.2.1 通知权限申请节点页面
Android 13 及以上系统需申请 POST_NOTIFICATIONS 运行时权限。本期通知权限申请不在 App 首次启动立即弹出，避免影响新用户首屏和注册转化；应在用户完成基础身份识别或进入强 Push 相关业务节点时触发。
UI 设计图：
| 节点页面 | 是否必须 | 触发时机 | 申请策略 | 说明 |
|---|---|---|---|---|
| 登录成功后首页 | 必须 | 用户登录成功并进入首页后，且当前未授权通知权限；同一用户首次登录当天优先不弹窗，除非用户直接进入消息中心或关键业务节点 | 可弹出业务说明弹窗，引导用户授权系统通知权限 | 用于覆盖老用户、重装用户和已登录用户；避免新用户刚登录即被权限打断 |
| 提交额度申请成功页 | 必须 | 用户提交额度申请成功后，且未授权通知权限 | 引导用户开启通知权限 | 审核结果、补件、额度结果依赖 Push 触达 |
| 放款申请/提现提交成功页 | 必须 | 用户提交放款或提现申请成功后，且未授权通知权限 | 引导用户开启通知权限 | 放款成功、放款失败、银行卡异常等结果通知依赖 Push |
| 还款结果页 | 建议 | 用户完成主动还款后，且未授权通知权限 | 可引导开启通知权限 | 用于还款结果、失败重试、后续账单提醒 |
| 消息中心页 | 建议 | 用户主动进入消息中心且未授权通知权限 | 展示开启通知入口；用户点击后再展示业务说明弹窗或跳转系统设置 | 作为用户主动开启通知的补充入口 |
| 我的/设置页 | 建议 | 用户进入设置或通知设置页面 | 提供系统通知设置跳转 | 用于用户拒绝后自行恢复权限 |
权限申请规则：
- 不在 App 首次启动、启动页、注册手机号输入页、验证码页、基础信息填写过程中主动弹出通知权限，避免影响首屏、注册和身份信息提交转化。
- 同一自然日内首页最多触发 1 次业务说明弹窗；同一用户 7 个自然日内最多触发 2 次主动弹窗。
- 各页面只在自身节点达成后判断是否展示权限说明弹窗，例如额度申请成功页只处理额度申请成功后的提示，放款/提现提交成功页只处理放款/提现提交后的提示；首页仅作为登录后老用户或重装用户的兜底入口，不集中补弹其他业务节点的提示。
- 客户端需记录本次会话是否已展示过强业务节点说明弹窗，以及最近展示时间、最近拒绝时间、授权状态；进入任一节点时先检查这些状态，命中频控或冷却规则则不弹窗，因此同一会话内即使用户连续经过多个节点，也只会出现一次主动提示。
- 用户点击业务说明弹窗的“开启通知”后，再调起系统权限弹窗；未点击“开启通知”时不得直接调起系统权限弹窗。
- 用户关闭业务说明弹窗但未触发系统权限弹窗时，记为
soft_dismissed，冷却 7 个自然日后才可在强业务节点再次主动提示。 - 用户拒绝系统权限后，不得阻断注册、申请、放款、还款等核心流程；拒绝后 30 个自然日内不再主动弹业务说明弹窗。
- 用户拒绝后需记录本地状态和后端状态，后续仅在消息中心、我的/设置页提供二次引导入口；用户主动点击入口不受 30 天冷却限制。
- 用户重新安装 App 后，以当前设备的通知授权状态和本地频控状态重新判断是否需要弹出；不得仅因重装就绕过拒绝后的冷却规则。
- 当客户端判断系统权限弹窗不会再展示时，不再重复调用权限申请；仅在用户主动点击消息中心或设置页的开启入口后，引导用户前往系统通知设置页。
- 消息中心和我的/设置页可提供固定的“开启通知”入口；是否展示只依赖当前通知授权状态，不要求根据审核、放款、还款等业务状态动态判断。
- Android 12 及以下无需运行时申请通知权限，但仍需记录系统通知开关状态（如可获取）。
- 后端需保存通知权限状态，用于判断 Push 可触达用户规模和发送策略。
建议的权限引导文案原则：
- 说明必须贴近现金贷业务结果通知，不使用“获得优惠”“重要福利”等泛营销理由作为主文案。
- 主文案建议覆盖审核结果、放款结果、还款提醒和异常处理，不承诺用户一定会提额或放款成功。
- 业务说明弹窗需提供“稍后再说”和“开启通知”两个操作；关闭或稍后不影响当前流程继续。
- 已拒绝系统权限后的二次引导文案应说明“可在系统设置中开启”，避免让用户误以为 App 内可直接恢复权限。
后端 token 建议保存字段：
| 字段 | 说明 |
|---|---|
fcm_token | Firebase Push token |
user_id | 我司用户 ID，登录后必填 |
device_id | 我司设备 ID，如已有 |
appsflyer_id | AppsFlyer UID，如已获取 |
app_version | App 版本 |
package_name | Android 包名 |
country | 国家，例如 NG |
language | App 或系统语言 |
notification_permission | 通知权限状态 |
last_token_refresh_time | 最近一次 token 更新时间 |
last_push_open_time | 最近一次 Push 点击时间 |
9.3 Firebase 归因需求
Firebase 归因基于 Firebase Analytics（Google Analytics for Firebase）实现，用于补充 Firebase/GA4 侧的安装来源、营销活动、用户行为和漏斗分析。Firebase 归因不替代 AppsFlyer：付费媒体安装归因、AppsFlyer ID 关联、放款 ROI 和最终业务状态仍以 AppsFlyer 与我司后端为主口径。
接口与上报方式：
| 场景 | 使用接口 | 上报方 | 说明 |
|---|---|---|---|
| 初始化 Analytics | FirebaseAnalytics.getInstance(context) | Android 客户端 | 初始化 Firebase Analytics，建立 Firebase 安装实例和自动事件采集能力 |
| 获取并上报安装实例标识 | getAppInstanceId() | Android 客户端 + 后端 | 客户端获取 app_instance_id 后上报后端；后端使用该标识关联 Measurement Protocol 业务事件 |
后台事件上报要求：
- 正式上报地址：
https://www.google-analytics.com/mp/collect。 - 参数要求：请求 URL 必须包含
firebase_app_id、api_secret；请求体必须包含app_instance_id、events。 events中每个事件必须包含name，业务参数放入params；单次请求最多 25 个事件，请求体小于 130KB。app_instance_id必须由 Android Firebase Analytics SDK 的getAppInstanceId()获取；不得使用appsflyer_id、FCM token 或 Advertising ID 替代。api_secret只能保存在后端，不得下发到 App；后端必须使用业务幂等键避免重复上报。- 测试校验地址：
https://www.google-analytics.com/debug/mp/collect。校验请求不会进入正式报表。 - Google 官方文档：
功能要求：
- Firebase Analytics SDK 自动记录安装、首次打开、会话和 App 更新事件；客户端不主动调用
logEvent()上报现金贷业务事件。 - 后端必须通过 Measurement Protocol 上报以下 5 个业务事件：
sign_up、apply、credit_approved、first_loan、loan。 - 5 个业务事件必须按照“Firebase MVP 事件映射”表中的触发时机和参数上报；不得新增其他 Firebase 业务事件。
- 业务事件中的
application_id、loan_order_id和用户标识必须使用不可逆哈希或脱敏值；金额事件使用value和currency，金额以我司后端最终财务口径为准。 - 业务事件使用后端业务幂等键去重；Firebase 上报失败最多重试 3 次，仍失败记录失败日志，不阻断核心业务。
Firebase MVP 事件映射：
| 业务事件 | Firebase 事件名 | 触发方 | 关键参数 | 口径 |
|---|---|---|---|---|
| 安装/首次打开 | Firebase 自动事件 | Firebase SDK | SDK 自动采集 | 用于安装量和首次打开分析，不与 AppsFlyer 安装数强行相等 |
| 注册 | sign_up | 后端确认注册成功后 | method、user_id_hash | 与 AppsFlyer af_complete_registration 表示同一业务结果 |
| 提交申请 | apply | 后端确认申请提交后 | application_id_hash | 仅表示申请提交，不表示授信通过 |
| 授信通过 | credit_approved | 后端确认最终结果后 | application_id_hash | 最终状态以后端为准 |
| 首贷成功 | first_loan | 后端确认首次放款成功后 | loan_order_id_hash、value、currency | 金额以后端财务口径为准 |
| 放款成功 | loan | 后端确认非首贷放款成功后 | loan_order_id_hash、value、currency | 金额以后端财务口径为准 |
Firebase MVP 归因字段必须保存：
| 字段 | 来源 | 说明 |
|---|---|---|
firebase_app_instance_id | Firebase Analytics | Firebase 安装实例标识，不作为永久用户 ID |
firebase_source | Firebase/深链/Install Referrer | Firebase 侧来源；缺失时保存为空，不自行推断 |
firebase_medium | Firebase/深链/Install Referrer | Firebase 侧媒介；缺失时保存为空 |
firebase_campaign | Firebase/深链/Install Referrer | Firebase 侧活动名称；缺失时保存为空 |
firebase_first_open_time | Firebase | 首次打开时间 |
9.4 Crash 需求
Firebase Crash 基于 Firebase Crashlytics 接入，用于采集线上崩溃、非致命异常和版本质量数据。
功能要求：
- Release 包必须开启 Crashlytics 崩溃采集；Debug 包默认关闭或进入独立测试项目。
- 崩溃日志需包含 App 版本、build number、Android 版本、设备型号、线程、堆栈和崩溃时间。
- 客户端可设置低敏用户标识，例如
user_id_hash；不得上传手机号、身份证号、银行卡号等明文敏感信息。 - 关键业务异常可使用 non-fatal exception 上报，例如 Push 解析失败、关键页面初始化失败、SDK 初始化异常。
- 关键状态可通过 custom keys 上报，例如
appsflyer_id_exist、login_status、country、app_channel，但不得包含高敏感信息。 - Native 崩溃、混淆映射文件、R8/ProGuard mapping 上传需按项目技术栈确认并纳入构建流程。
- Crashlytics 数据需按版本维度用于发布质量评估；严重崩溃需支持回溯到版本、设备和页面路径。
建议上报的 custom keys：
| Key | 示例 | 说明 |
|---|---|---|
login_status | guest / login | 用户登录状态 |
country | NG | 当前业务国家 |
app_channel | google_play | 安装渠道或包渠道 |
appsflyer_id_exist | true / false | 是否已获取 AppsFlyer UID |
push_permission | granted / denied | 通知权限状态 |
10. 测试与验收
研发和 QA 测试前需先阅读飞书接入指南文件，用于理解测试设备加白、归因链接、事件验证和排查流程：https://lianlian-tech.feishu.cn/file/UiHobClfJoJOQBxsfZBcjVfdngc
10.1 测试设备白名单
Android 测试前必须在 AppsFlyer 后台添加测试设备：
- 使用 AppsFlyer Device ID App 或系统方式获取 GAID。
- 在 AppsFlyer 后台添加测试设备，Device Type 选择
AID。 - 测试前卸载待测 App。
- 使用带
advertising_id={GAID}的测试归因链接或 AppsFlyer SDK 对接测试功能进行验证。
10.2 测试场景
| 场景 | 前置条件 | 操作 | 预期结果 |
|---|---|---|---|
| SDK 初始化 | Debug 包开启 AppsFlyer debug log | 首次安装并打开 App | Logcat 可看到 AppsFlyer 初始化、launch 请求和返回 |
| 非自然安装归因 | 测试设备 GAID 已加白 | 卸载 App，点击测试归因链接，安装并首次打开 | 15-30 分钟内 AppsFlyer 后台可看到 Non-organic install |
| AppsFlyer UID 关联 | SDK 初始化成功 | 打开 App、注册、提交额度申请 | 后端可查询到 appsflyer_id 与 user_id、application_id 的关联 |
| Android SDK 事件 | 设备已加白 | 触发注册、提交额度申请 | Live Events 可看到 af_complete_registration、apply；参数不包含敏感明文 |
| 后端 S2S 事件 | 后端已保存 appsflyer_id | 触发授信通过、首贷、借贷 | AppsFlyer 可收到 approved、first_loan、loan，且后端幂等不重复上报 |
| 放款金额事件 | 后端放款成功 | 触发 first_loan 或 loan | 首贷传 af_revenue=first_loan_value，普通放款传 af_revenue=loan_value，af_currency=NGN |
| 重复放款防重 | 同一 loan_order_id 重放消息或重复回调 | 重复触发放款成功逻辑 | AppsFlyer 只产生一条有效放款事件 |
| 离线缓存 | 测试机断网 | 断网触发 Android SDK 事件，恢复网络 | 网络恢复后事件补发；关键金额事件仍以后端为准 |
| 卸载统计 | FCM token 已上传给 AppsFlyer | 打开 App 后卸载 | 24-48 小时内 AppsFlyer 后台出现卸载数据 |
| Firebase 初始化 | App 已集成 google-services.json | 安装并启动 App | Firebase 初始化成功，无配置缺失或包名不匹配错误 |
| Firebase Analytics 归因 | Firebase Analytics 已接入，测试来源参数已准备 | 通过 Google Play 测试安装或带 UTM/深链参数打开 App | Firebase/GA4 可看到首次打开、来源、媒介、活动及时间；非法参数不阻断启动 |
| Firebase 核心事件 | Analytics 已开启且用户已同意分析采集 | 触发注册、申请、授信、首贷、放款 | Firebase/GA4 可看到对应事件和低敏参数；事件语义与 AppsFlyer 对齐 |
| Firebase 归因边界 | AppsFlyer 与 Firebase 均已接入 | 对比同一测试安装和业务事件 | AppsFlyer 作为付费投放主归因，Firebase 作为补充分析；两者字段不互相覆盖 |
| FCM token 获取 | 网络正常 | 首次启动或清除数据后打开 App | 客户端可获取 FCM token，后端可查询 token 记录 |
| FCM token 刷新 | 触发 token 更新 | 重新打开 App 或模拟刷新 | 新 token 上报后端，并同步给 AppsFlyer 用于卸载统计 |
| Android 13 通知权限 | Android 13 及以上设备 | 在提交额度申请成功页、放款申请/提现提交成功页、登录成功后首页、还款结果页触发授权流程 | 用户授权结果被客户端记录并同步后端，拒绝后不阻断核心流程 |
| 通知权限频次控制 | Android 13 及以上设备，用户未授权通知权限 | 同一自然日和 7 日周期内多次进入触发节点 | 同一自然日最多 1 次业务说明弹窗，同一用户 7 个自然日内最多 2 次主动弹窗；同一会话不重复弹出 |
| 通知权限拒绝冷却 | Android 13 及以上设备，用户拒绝系统通知权限 | 30 个自然日内再次进入触发节点 | 不再主动弹出业务说明弹窗，仅在消息中心页或我的/设置页保留用户主动开启入口 |
| 通知权限二次引导 | Android 13 及以上设备，用户已拒绝通知权限 | 进入消息中心页或我的/设置页，并主动点击开启入口 | 展示开启通知说明或跳转系统通知设置页；不阻断当前页面使用 |
| 前台 Push | App 在前台 | 后台发送测试 Push | 客户端按产品规则展示站内提醒或系统通知 |
| 后台 Push | App 在后台 | 后台发送测试 Push | 系统通知栏展示标题、正文，点击后进入目标页面 |
| Push 跳转 | Push 携带业务参数 | 点击通知 | 正确打开业务页面；参数异常时回退首页 |
| Push 内容合规 | 测试不同消息模板 | 查看通知栏和日志 | 不展示或记录高敏感明文 |
| Crash 采集 | Release 或测试 Crash 项目开启采集 | 触发测试崩溃 | Firebase Crashlytics 后台可看到崩溃记录、版本和堆栈 |
| Non-fatal 上报 | 客户端触发可恢复异常 | 上报 non-fatal exception | Crashlytics 后台可看到非致命异常记录 |
| Mapping 上传 | Release 开启混淆 | 构建并触发崩溃 | Crashlytics 后台堆栈可读，不出现大面积混淆不可定位问题 |
| 数仓回流（P2） | AppsFlyer 数据回流任务已配置 | 后续 P2 阶段验证，本期不阻塞上线 | 数仓可查询安装、事件、归因、放款金额数据 |
10.3 验收标准
| 验收项 | 标准 |
|---|---|
| SDK 初始化 | 首次启动 Logcat 可看到 AppsFlyer 初始化和 launch 请求 |
| 非自然安装 | 白名单测试设备通过测试链接安装后，AppsFlyer 后台可看到 Non-organic install |
| AppsFlyer UID | 客户端可获取 appsFlyerId，后端可查询到与用户/订单的关联 |
| 注册事件 | 注册成功后 AppsFlyer Live Events 可看到 af_complete_registration |
| 申请事件 | 提交额度申请后 AppsFlyer Live Events 可看到 apply |
| 授信事件 | 额度申请通过后 AppsFlyer 可看到后端 S2S 上报的 approved |
| 放款事件 | 放款成功后可看到 first_loan 或 loan，金额和币种字段符合口径 |
| 金额字段 | 仅放款成功相关事件包含 af_revenue；af_revenue 为数字，af_currency=NGN |
| 卸载统计 | 卸载测试后 24-48 小时内后台出现卸载数据 |
| Firebase Push | 客户端可获取 FCM token，后端可发送 Push，通知点击可按参数跳转 |
| Firebase 归因 | Firebase/GA4 可记录首次打开、来源、媒介、活动和核心漏斗事件；归因字段与 AppsFlyer 分开保存，AppsFlyer 仍为付费投放主口径 |
| 通知权限申请 | Android 13 及以上按指定节点页面触发通知权限申请；满足单日、7 日、拒绝后 30 日冷却和同一会话不重复弹出规则；拒绝后不阻断核心流程，并支持消息中心页或我的/设置页二次引导 |
| Firebase Crash | Crashlytics 可采集 Release 崩溃和 non-fatal，堆栈可定位到业务代码 |
| 数仓回流（P2） | 后续 P2 阶段验收，本期不作为上线准入标准 |
| Release 安全 | Release 包未开启 debug log，未上报敏感个人信息 |
11. 数据回流数仓需求（P2）
优先级：P2。本能力不作为本期 AppsFlyer SDK 接入上线阻塞项，可在后续阶段补充，用于渠道 ROI、漏斗转化、放款金额、卸载率和用户质量分析。
11.1 回流范围
| 数据 | P2 范围 | 说明 |
|---|---|---|
| 安装归因数据 | 建议纳入 | 包含 install、media source、campaign、adset、ad、国家、设备标识、appsflyer_id |
| Firebase 归因数据 | 必须纳入 | 包含 Firebase 首次打开、来源、媒介、活动、App 实例和五个 MVP 业务事件；与 AppsFlyer 字段分开保存 |
| 应用内事件数据 | 建议纳入 | 包含注册、提交申请、授信通过、首贷、借贷等事件 |
| 放款金额数据 | 建议纳入 | first_loan、loan 的 af_revenue 和 af_currency=NGN |
| 卸载数据 | 建议纳入 | 用于渠道质量和召回分析 |
| 原始回调或 Data Locker | 待技术选型 | 根据 AppsFlyer 套餐和权限选择 Pull API、Push API 或 Data Locker |
11.2 数仓关联键
| 关联键 | 来源 | 用途 |
|---|---|---|
appsflyer_id | Android SDK / AppsFlyer 原始数据 | 连接归因安装与事件 |
firebase_app_instance_id | Firebase Analytics | 连接 Firebase 安装实例与事件，不作为永久用户 ID |
user_id_hash | 我司后端 | 连接用户维度，禁止使用明文手机号或证件号 |
application_id | 我司后端 | 连接额度申请和授信链路 |
loan_order_id | 我司后端 | 连接首贷和借贷放款链路 |
gaid | 设备侧，合规允许时采集 | 辅助排查测试和归因匹配 |
11.3 时效要求
| 数据链路 | 时效要求 |
|---|---|
| AppsFlyer 面板联调 | 近实时到 60 分钟内验证 |
| 数仓日常报表 | T+1 可用 |
| 放款 ROI 分析 | 放款事件进入数仓后可按渠道、广告系列、日期聚合 |
12. 分工
| 角色 | 职责 |
|---|---|
| 产品/运营 | 确认事件清单、金额口径、币种、投放渠道、AppsFlyer 后台配置、Push 场景和消息模板 |
| Android 研发 | SDK 接入、初始化、AppsFlyer/Firebase 事件埋点、Firebase 归因参数解析、FCM Push、FCM 卸载统计、Crashlytics、测试日志 |
| 后端研发 | 接收并存储 appsflyer_id、fcm_token，完成后端 S2S 事件上报、Push 发送和幂等控制 |
| 数据/BI | 定义 AppsFlyer 主归因口径、Firebase 补充归因口径、事件看板、渠道分析报表、Push 触达和打开数据分析；P2 阶段补充数仓回流表结构 |
| QA | 白名单设备测试、安装归因测试、SDK 事件测试、S2S 事件测试、金额测试、卸载测试、Push 测试、Crash 测试；P2 阶段补充数仓验收 |
| 合规 | 隐私政策、SDK 清单、广告 ID、设备标识、Push token 和崩溃日志采集说明 |
13. 评审待确认问题
- AppsFlyer SDK 版本最终采用
7.0.0还是6.18.1。 - 后端是否已有匿名设备 ID；如有，需和
appsflyer_id建立多对多历史关系。 - P2 阶段确认 AppsFlyer 数据回流采用 Pull API、Push API 还是 Data Locker，需由数据/后端根据套餐权限确认。
- Firebase 是否按开发、测试、生产拆分项目或 App 配置。
- Push 发送由现有后端系统承接，还是需要新增消息平台/运营后台。
- Android 13 通知权限申请节点页面的最终 UI、业务说明弹窗文案和消息中心/设置页入口样式需由产品确认；触发频次、冷却和拒绝后处理按 9.2.1 执行。
- Crashlytics Debug、Staging、Release 数据是否进入同一个 Firebase 项目，是否需要环境隔离。
- Firebase 归因是否需要关联 Google Ads；如需关联，需确认 Google Ads 账号、Firebase 项目、转化事件和归因窗口配置。
14. 已确认结论
| 项 | 结论 |
|---|---|
| 投放国家 | 尼日利亚 |
| 默认币种 | 奈拉，NGN |
| 金额上报口径 | 只在放款成功相关事件上报 af_revenue |
af_revenue 含义 | 放款本金金额；首贷为 first_loan_value，普通放款为 loan_value |
| 数据回流 | P2 后续考虑，不作为本期上线阻塞项 |
| Firebase 能力 | 本期需支持 Analytics 归因、Push 和 Crash |
| Push 基础方案 | 使用 Firebase Cloud Messaging |
| Firebase 归因基础方案 | 使用 Firebase Analytics/GA4 作为 AppsFlyer 的补充分析口径 |
| Crash 基础方案 | 使用 Firebase Crashlytics |
15. 参考资料
- AppsFlyer Android SDK 文档：https://dev.appsflyer.com/hc/docs/android-sdk
- Install SDK：https://dev.appsflyer.com/hc/docs/install-android-sdk
- Integrate SDK：https://dev.appsflyer.com/hc/docs/integrate-android-sdk
- In-app events：https://dev.appsflyer.com/hc/docs/in-app-events-android
- Uninstall measurement：https://dev.appsflyer.com/hc/docs/uninstall-measurement-android
- AppsFlyerLib / getAppsFlyerUID：https://dev.appsflyer.com/hc/docs/android-sdk-reference-appsflyerlib
- 飞书接入指南文件：https://lianlian-tech.feishu.cn/file/UiHobClfJoJOQBxsfZBcjVfdngc
- Firebase Cloud Messaging 文档：https://firebase.google.com/docs/cloud-messaging/android/client
- Firebase Analytics 文档：https://firebase.google.com/docs/analytics
- Firebase Crashlytics 文档：https://firebase.google.com/docs/crashlytics/get-started?platform=android