文档

安卓卸载跟踪设置

使用与 Singular SDK 集成的 Firebase Cloud Messaging 跟踪 Android 上的应用程序卸载情况，以衡量用户保留率、识别低质量流量来源并优化营销活动性能。

需要进行 Firebase 迁移：Firebase 废弃了传统的 HTTP API，并于2024 年 7 月 22 日关闭。所有实施都必须使用HTTP v1 API。请参阅下面的HTTP v1 设置说明。

概述

卸载跟踪如何工作

Singular通过Firebase云消息发送静默推送通知，并监控推送响应，以确定应用程序是否仍安装在设备上，从而检测应用程序的卸载情况。

技术流程：

令牌注册：Singular SDK 向 Singular 服务器注册 FCM 令牌
静默通知：Singular定期向注册设备发送静默推送通知
交付反馈：FCM 报告交付成功或失败
卸载检测：发送失败表示应用程序已卸载
事件记录：卸载事件归因于原始安装源

要求

SDK 版本：卸载跟踪需要 Android SDK 7.0 以上版本
Firebase 设置：启用云消息的活动 Firebase 项目
Google Play 服务：设备必须安装 Google Play 服务
应用程序更新：用户必须安装启用卸载跟踪功能的更新版应用程序
权限：Android 13+ 需要明确的通知权限才能生成 FCM 令牌

重要注意事项

要点

方法差异：Singular的卸载跟踪与谷歌的内置报告不同。谷歌直接从操作系统报告卸载情况，而 Singular 则使用 FCM 交付反馈。不同平台的数据可能有所不同。
归因保存：卸载作为事件进行跟踪，不会删除原始归属链接。用户可能会多次卸载和重新安装，可能导致卸载率超过 100%。
批量处理：卸载检测基于批处理，依赖于 FCM 的响应反馈。卸载数据将在 24 小时内出现在 Singular 面板中。
网络依赖性：静默推送通知需要激活的网络连接。设备长时间离线可能会延迟卸载检测。

域限制共享

如果您的 Google 组织已启用域限制共享，请授予 Singular 组织访问权限，以启用卸载跟踪功能。

所需配置：将 Singular 的组织 ID 添加到 "域限制共享 "策略的 "允许值 "列表中。

配置步骤：

访问组织策略：导航至 Google 云控制台中的 "组织策略 "页面
选择资源：选择配置策略的组织
查找约束：找到 "域限制共享 "约束
管理策略：单击 "管理策略 "按钮
添加单一组织：在 "策略值 "下，选择 "自定义 "并添加以下内容：

is:principalSet://iam.googleapis.com/organizations/626787461583

这将授予 Singular 的服务账户访问权限，以发送用于卸载检测的 FCM 通知。

HTTP v1 API 设置（推荐）

使用 Firebase Cloud Messaging HTTP v1 API 配置卸载跟踪，该 API 通过 OAuth 2.0 访问令牌和增强的跨平台消息支持提高了安全性。

为什么选择 HTTP v1？HTTP v1 API 可通过短期访问令牌提供更好的安全性、更高效的跨平台定制以及 Firebase 对新功能的持续支持。传统 HTTP API 已于 2024 年 7 月 22 日关闭。

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

更新 SDK 版本

升级到 Android SDK 7.0 或更高版本，以启用卸载跟踪功能。

Gradle 配置：

dependencies {
    // Singular Android SDK 7.x+
    implementation("com.singular.sdk:singular_sdk:12.6.2")
}

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

第 2 步：配置 AndroidManifest.xml

添加 FCM 接收器

配置 Android 清单以接收用于卸载检测的 FCM 通知。

<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>
        
        <!-- Singular FCM Receiver Service -->
        <service
            android:name="com.singular.sdk.SingularFcmService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>

    </application>

</manifest>

详细清单配置：Android SDK 卸载跟踪指南

第 3 步：创建 Firebase 项目

初始化 Firebase

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

打开 Firebase 控制台：导航至Firebase 控制台
创建项目：为您的应用程序选择或创建一个新的 Firebase 项目
找到项目设置：单击齿轮图标 → 项目设置
复制项目 ID：从 "常规 "选项卡中复制项目 ID（稍后将在 Singular 中输入该 ID

Firebase Project Settings

Firebase Project ID

第4步：启用Firebase云消息API

激活 HTTP v1 API

为您的项目启用 Firebase 云消息 API (v1)，以使用现代 HTTP v1 协议。

导航至云消息：在 Firebase 控制台中，转到 "项目设置"→"云消息 "选项卡
启用 API：单击 Firebase 云消息 API (V1) 旁的 "启用
验证激活：确认 API 状态显示为 "已启用

Enable FCM API

重要：Firebase 云消息 API (V1) 不同于传统的云消息 API。确保启用正确的 V1 版本。

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

配置服务帐户权限

创建具有特定权限的自定义 IAM 角色，以便 Singular 发送用于卸载检测的 FCM 通知。

访问 IAM：在 Firebase 项目设置 → 服务账户 → 管理服务账户权限
打开角色：在左侧导航菜单中选择 "角色
创建角色：单击 "创建角色 "按钮
配置角色详细信息：
- 标题Singular Uninstall Tracking
- ID：singular_uninstalls
- 角色启动阶段：General Availability

Create Custom Role

添加所需权限

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

添加权限：单击 "添加权限 "按钮
筛选权限：搜索 "Firebase 云消息 API 管理员
选择权限：选中cloudmessaging.messages.create
添加到角色：单击 "添加 "按钮
创建角色：单击 "创建 "完成角色创建

Add Permission

步骤 6：分配 Singular 服务账户

授予 Singular 访问权限

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

打开 IAM 页面：在左侧导航菜单中选择 "IAM
授予访问权限：点击权限选项卡中的 "授予访问权限 "按钮

添加负责人：在 "新负责人 "字段下输入

singular-uninstall-tracking@singular-uninstall-tracking.iam.gserviceaccount.com

Grant Access

Add Principal

分配自定义角色

选择之前步骤中创建的 "单一卸载跟踪 "角色。

选择角色：在 "分配角色 "下，搜索并选择 "Singular Uninstall Tracking"。
验证配置：确认设置与下面的截图一致
保存：单击 "保存 "按钮应用权限

Assign Role

最终配置：

Final IAM Configuration

第7步：配置Singular应用程序设置

为Singular添加项目ID

在Singular应用程序配置中输入您的Firebase项目ID，以启用卸载跟踪。

打开 Singular 应用程序：导航至Singular 应用程序页面
选择应用程序：从列表中选择您的安卓应用程序
高级设置：滚动到高级设置部分
卸载跟踪：找到 "卸载跟踪 "配置
输入项目 ID：粘贴步骤 3 中的 Firebase 项目 ID
保存：单击保存应用配置

Singular Project ID Configuration

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

测试卸载跟踪

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

测试步骤

验证步骤

安装测试构建：在测试设备上部署启用卸载跟踪功能的应用程序
启动应用程序：打开应用程序以触发 SDK 初始化和 FCM 令牌注册
验证令牌注册：检查 SDK 日志，确认 FCM 令牌与 Singular 成功注册
等待批处理：等待 24-48 小时，让 Singular 发送第一份无声通知
卸载应用程序：从测试设备中删除应用程序
监控仪表板：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 卸载跟踪 "角色
令牌未到达 Singular	网络连接或 SDK 未初始化	在 FCM 令牌注册之前，确保应用程序具有互联网权限，且 Singular SDK 已初始化
卸载未显示在仪表板中	批处理延迟或时间不足	卸载应用程序后等待 48 小时再做进一步调查
Singular 中的 API 验证失败	Firebase 未启用 HTTP v1 API	验证 Firebase 云消息设置中是否启用了 Firebase 云消息 API (V1)

传统 HTTP API（已停用）

传统 HTTP API 已于 2024 年 7 月 22 日关闭。所有实施都必须迁移到 HTTP v1 API。

已停用：如果您正在使用传统的服务器密钥配置，请按照上述说明立即迁移到 HTTP v1 API。

需要迁移

如果您的应用程序当前使用带有服务器密钥和发件人 ID 配置的传统 HTTP API，请按照以下步骤进行迁移：

查看当前配置：检查 Singular 应用程序设置是否显示 "服务器密钥 "字段而非 "项目 ID
遵循 HTTP v1 设置：完成HTTP v1 API 设置部分的所有步骤
更新应用程序配置：在 Singular 设置中用 Firebase 项目 ID 替换服务器密钥
测试实施：验证卸载跟踪是否能与新的 v1 API 配置一起工作
发布更新：向生产用户部署更新后的应用程序

迁移指南：Firebase HTTP v1 API 迁移

HTTP v1 API 的优势

增强安全性：使用短期 OAuth 2.0 访问令牌而不是静态服务器密钥
更好的跨平台支持：适用于 Android、iOS 和 Web 的统一消息结构
特定平台重写：在单个请求中自定义每个平台的通知行为
面向未来：持续的 Firebase 支持和仅在版本 1 中提供的新功能
改进的错误处理：更详细的错误响应，以便排除故障

分析卸载数据

在 Singular 报告中使用卸载数据来优化营销活动性能并识别流量质量问题。

可用指标

卸载跟踪指标

卸载次数：检测到的卸载应用程序总数
卸载率：导致卸载的安装百分比
卸载天数：安装与卸载事件之间的平均时间
按来源分类的卸载：按营销活动、出版商和创意分列的卸载情况
群组分析：不同用户群的卸载模式

使用案例

营销活动优化：

识别卸载率高的低质量流量营销活动
比较不同流量来源的卸载率
根据预测的用户保留率优化竞价策略

欺诈检测：

检测显示安装欺诈的异常卸载模式
标记具有可疑高卸载率的发布商
监控卸载时间，查找僵尸流量迹象

用户保留分析：

跟踪一段时间内的应用粘性和参与度
将卸载与应用程序更新或功能发布联系起来
确定导致用户流失的因素

最佳实践

优化策略

设定基准：为不同类型的营销活动设定可接受的卸载率阈值
监控趋势：跟踪一段时间内的卸载率，以识别季节性模式或异常情况
细分分析：比较不同用户人口、地域和设备的卸载率
归因窗口：在评估营销活动绩效时考虑卸载时机
质量评分：将卸载率纳入流量质量评分模型

设置 Android 卸载跟踪

安卓卸载跟踪设置

概述

卸载跟踪如何工作

要求

重要注意事项

域限制共享

HTTP v1 API 设置（推荐）

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

更新 SDK 版本

第 2 步：配置 AndroidManifest.xml

添加 FCM 接收器

第 3 步：创建 Firebase 项目

初始化 Firebase

第4步：启用Firebase云消息API

激活 HTTP v1 API

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

配置服务帐户权限

添加所需权限

步骤 6：分配 Singular 服务账户

授予 Singular 访问权限

分配自定义角色

第7步：配置Singular应用程序设置

为Singular添加项目ID

测试卸载跟踪

测试步骤

验证步骤

SDK 日志验证

常见问题

传统 HTTP API（已停用）

需要迁移

HTTP v1 API 的优势

分析卸载数据

可用指标

卸载跟踪指标

使用案例

最佳实践

优化策略