设置Android卸载追踪功能

关注
Avatar
Jivitha Masilamani
Updated
文档

Android卸载跟踪设置

通过Firebase云消息服务与Singular SDK集成，在Android平台追踪应用卸载行为，以衡量用户留存率、识别低质量流量来源并优化营销活动效果。

Firebase迁移要求：Firebase已弃用 旧版HTTP API并于2024年7月22日关闭。 所有实现必须使用 HTTP v1 API。 请参阅下文HTTP v1设置说明。

概述

卸载追踪工作原理

Singular通过Firebase云消息服务发送静默推送通知， 并监测送达响应来检测应用卸载行为，从而判断应用是否仍安装在设备上。

技术流程：

  1. 令牌注册：Singular SDK将FCM令牌 注册至Singular服务器
  2. 静默通知：Singular定期向已注册设备发送 静默推送通知
  3. 投递反馈：FCM报告投递成功或失败状态
  4. 卸载检测：未成功送达即表示应用被卸载
  5. 事件记录：卸载事件归因于原始安装来源

系统要求

  • SDK版本：需Android SDK 7.0+版本支持卸载追踪
  • Firebase配置：需启用云消息服务的 有效Firebase项目
  • Google Play服务：设备必须安装Google Play服务
  • 应用更新：用户必须安装启用卸载跟踪功能的 新版应用
  • 权限要求：Android 13+系统需明确授予通知权限 以生成FCM令牌

重要注意事项

关键要点：

  • 方法论差异：Singular的卸载追踪机制 与Google内置报告存在差异。Google直接从操作系统 获取卸载数据，而Singular基于FCM投递反馈进行统计。 不同平台数据可能存在偏差。
  • 归因保留：卸载事件将作为独立事件追踪， 不影响原始归因链。用户可能多次卸载重装， 可能导致卸载率超过100%。
  • 批量处理：卸载检测基于批处理机制， 依赖FCM响应反馈。卸载数据可能需要长达24小时 才能在Singular仪表盘中显示。
  • 网络依赖性：静默推送通知需保持网络连接。设备长期离线可能延迟卸载检测。

域限制共享

若您的Google组织启用了 域限制共享功能 请授予Singular组织访问权限以启用卸载追踪功能。

必要配置：将Singular的组织ID 添加至您的域限制共享策略的"允许值"列表。

配置步骤：

  1. 访问组织策略：在Google Cloud控制台导航至 组织策略页面
  2. 选择资源：选择配置策略的组织
  3. 查找约束条件：定位"域限制共享"约束项
  4. 管理策略：点击"管理策略"按钮
  5. 添加 Singular 组织：在策略值下， 选择自定义并添加以下内容： 
is:principalSet://iam.googleapis.com/organizations/626787461583

此操作将授予 Singular 服务账户发送 FCM 通知的权限， 用于检测应用卸载情况。

HTTP v1 API 配置（推荐）

通过 Firebase 云消息传递 HTTP v1 API 配置卸载跟踪， 采用 OAuth 2.0 访问令牌提升安全性，并增强跨平台消息支持。

为何选择HTTP v1？v1 API通过短效访问令牌提供更优安全性，支持更高效的跨平台定制，并持续获得Firebase对新功能的支持。旧版HTTP API已于2024年7月22日停用。

步骤 1：集成 Android SDK 7.x+

更新 SDK 版本

确保应用使用 Singular Android SDK 7.0 及以上版本。 若尚未集成 Singular SDK，请先完成 Android SDK 集成指南，再设置卸载跟踪功能。

完整集成指南： Android SDK集成指南

步骤二：确认 AndroidManifest.xml 的 FCM 配置

验证 FCM 服务及权限

确保您的应用已集成Firebase云消息服务， 且Android清单文件声明了FirebaseMessagingService以接收 FCM消息。

XML 
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.your.package">

    <!-- FCM Permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application>

        <!-- App Firebase Messaging Service -->
        <service
            android:name=".MyFirebaseMessagingService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>

    </application>

</manifest>

重要提示：请将.MyFirebaseMessagingService 替换为 您继承自FirebaseMessagingService 类的完整限定类名。 应用中仅应有一个服务处理 com.google.firebase.MESSAGING_EVENT intent。

详细清单配置： Firebase FCM Android清单指南。

步骤 3：创建 Firebase 项目

初始化 Firebase

创建 Firebase 项目并获取 Singular 配置所需的项目 ID。

  1. 打开 Firebase 控制台：导航至 Firebase 控制台
  2. 创建项目：为您的应用选择或创建新的 Firebase 项目
  3. 定位项目设置：点击齿轮图标 → 项目设置
  4. 复制项目ID：从常规选项卡复制项目ID （稍后需在Singular中输入此ID）

Firebase Project Settings

Firebase Project ID

步骤 4：启用 Firebase 云消息传递 API

激活 HTTP v1 API

为项目启用 Firebase 云消息传递 API（v1），以便使用现代的 HTTP v1 协议。

  1. 导航至云消息传递：在 Firebase 控制台中， 前往项目设置 → 云消息传递选项卡
  2. 启用API：点击Firebase云消息传递API（V1）旁的"启用"按钮
  3. 验证激活状态：确认 API 状态显示为"已启用"

Enable FCM API

重要提示：Firebase 云消息传递 API (V1) 与旧版云消息传递 API 不同。请确保启用 正确的 v1 版本。

步骤 5：创建自定义 IAM 角色

配置服务账户权限

创建自定义 IAM 角色，授予 Singular 发送 FCM 通知以检测卸载行为的特定权限。

  1. 访问 IAM：进入 Firebase 项目设置 → 服务账户 → 管理服务账户权限
  2. 打开角色：在左侧导航菜单中选择"角色"
  3. 创建角色：点击"创建角色"按钮
  4. 配置角色详情：
    • 标题：Singular Uninstall Tracking
    • ID：singular_uninstalls
    • 角色启动阶段：General Availability

Create Custom Role

添加所需权限

授予自定义角色发送FCM消息的权限。

  1. 添加权限：点击“添加权限”按钮
  2. 筛选权限：搜索"Firebase云消息传递 API管理员"
  3. 选择权限：勾选 cloudmessaging.messages.create
  4. 添加到角色：点击“添加”按钮
  5. 创建角色：点击"创建"完成角色创建

Add Permission

步骤6：分配Singular服务账户

授予 Singular 访问权限

将自定义角色分配给Singular的服务账户，以授权卸载 跟踪操作。

  1. 打开IAM页面：在左侧导航菜单选择"IAM"
  2. 授予访问权限：在权限选项卡中点击"授予访问权限"按钮 添加主体：在"新建主体"字段中输入：
  3. 添加主体：在"新建主体"字段中输入： 
    singular-uninstall-tracking@singular-uninstall-tracking.iam.gserviceaccount.com

Grant Access

Add Principal

分配自定义角色

选择前一步创建的"Singular卸载跟踪"角色。

  1. 选择角色：在"分配角色"区域搜索并 选择"Singular卸载追踪"
  2. 验证配置：确认设置与下方截图一致
  3. 保存：点击"保存"按钮应用权限

Assign Role

最终配置：

Final IAM Configuration

步骤7：配置Singular应用设置

向Singular添加项目ID

在Singular应用配置中输入Firebase项目ID以启用 卸载跟踪功能。

  1. 打开Singular应用：导航至 Singular应用页面
  2. 选择应用：从列表中选择您的Android应用
  3. 高级设置：滚动至高级设置区域
  4. 卸载跟踪：定位卸载跟踪配置
  5. 输入项目ID：粘贴步骤3中获取的Firebase项目ID
  6. 保存：点击保存应用配置

Singular Project ID Configuration

验证：保存后，Singular将验证 项目ID和IAM权限。若验证失败，请重新检查 Firebase中的服务账户配置。

测试卸载跟踪

在将更新后的应用发布到生产环境前，请验证卸载跟踪是否配置正确。

测试流程

验证步骤

  1. 安装测试版本：在启用卸载跟踪功能的设备上部署应用
  2. 启动应用：打开应用以触发SDK初始化 及FCM令牌注册
  3. 验证令牌注册：检查SDK日志确认 FCM令牌已在Singular平台成功注册
  4. 等待批量处理：等待24-48小时，待Singular 发送首条静默通知
  5. 卸载应用：从测试设备移除应用
  6. 监控仪表盘：24-48小时后查看Singular仪表盘 确认卸载事件是否触发

测试时间线：卸载追踪采用批处理机制， 可能需要长达48小时才能检测并报告卸载行为。 此延迟属于预期现象。

SDK日志验证

检查 Android logcat 中的 Singular SDK 消息，确认配置正确。

预期日志信息： 

D/SingularSDK: FCM token registered successfully
D/SingularSDK: Uninstall tracking enabled
D/SingularSDK: Token sent to Singular servers

常见问题

问题 原因 解决方案
未生成FCM令牌 Firebase 配置错误 请确认google-services.json 文件位于app/目录下， 并在build.gradle文件中应用Firebase插件
日志中出现权限拒绝错误 IAM角色分配错误 请确认Singular服务账户在Firebase IAM中拥有"Singular Uninstall Tracking"角色
令牌未送达 Singular 网络连接问题或SDK未初始化 确保应用具备互联网权限，且在FCM令牌注册前完成Singular SDK初始化
卸载记录未显示在仪表盘 批量处理延迟或时间不足 应用卸载后请等待满48小时再进行排查
Singular API验证失败 Firebase中未启用HTTP v1 API 请在云消息设置中确认已启用 Firebase 云消息 API (V1)

旧版HTTP API（已弃用）

旧版HTTP API已于2024年7月22日关闭。所有实现必须迁移至HTTP v1 API。

已停用：旧版HTTP API已停止服务。 若您仍在使用旧版服务器密钥配置，请立即参照上述说明迁移至HTTP v1 API。

必须迁移

若您的应用当前使用旧版HTTP API并配置了服务器密钥和发送者ID，请遵循以下迁移步骤：

  1. 检查当前配置：确认Singular应用设置中显示的是"服务器密钥"字段而非"项目ID"
  2. 遵循HTTP v1设置：完成上述HTTP v1 API设置章节中的所有步骤
  3. 更新应用配置：在Singular设置中用Firebase项目ID替换服务器密钥
  4. 测试实现：验证新v1 API配置下的卸载追踪功能
  5. 发布更新：将更新后的应用部署给生产环境用户

迁移指南： Firebase HTTP v1 API 迁移

HTTP v1 API优势

  • 增强安全性：采用短效OAuth 2.0访问令牌替代静态服务器密钥
  • 更优跨平台支持：统一Android、iOS及Web端 消息结构
  • 平台特定覆盖：通过单次请求按平台自定义通知行为
  • 未来兼容性：仅v1版本提供持续的Firebase支持 及新功能
  • 改进的错误处理：提供更详细的错误响应 便于故障排查

分析卸载数据

利用Singular报告中的卸载数据优化活动效果 并识别流量质量问题。

可用指标

卸载追踪指标

  • 卸载次数：检测到的应用总卸载次数
  • 卸载率：导致卸载的安装占比 （百分比）
  • 卸载耗时：安装事件与卸载事件 之间的平均时长
  • 来源卸载分析：按活动、发布商、创意 分类的卸载数据
  • 用户群组分析：不同用户群组的卸载模式

应用场景

活动优化：

  • 识别带来低质量流量且卸载率高的营销活动
  • 比较不同流量来源的卸载率
  • 基于预测用户留存率优化竞价策略

欺诈检测：

  • 检测异常卸载模式以识别安装欺诈
  • 标记卸载率异常偏高的发布商
  • 监控卸载耗时以识别机器人流量迹象

用户留存分析：

  • 追踪应用粘性与用户参与度随时间变化
  • 关联卸载行为与应用更新或功能发布
  • 识别导致用户流失的关键因素

最佳实践

优化策略

  • 设定基准：为不同活动类型建立可接受的卸载率阈值 监控趋势：追踪卸载率随时间的变化 识别季节性模式或异常情况
  • 趋势监测：追踪随时间变化的卸载率 识别季节性规律或异常情况
  • 分群分析：比较不同用户群体、地域及设备间的卸载率
  • 归因窗口：评估活动成效时需考量卸载时间节点
  • 质量评分：将卸载率纳入流量质量评分模型