卸载追踪
通过将 Firebase Cloud Messaging (FCM) 与 Singular SDK 集成,追踪应用卸载情况, 以衡量用户留存并优化再互动活动。
重要: Google 已于 2018 年 4 月弃用 GCM API。所有卸载追踪 的实现都应使用 Firebase Cloud Messaging (FCM)。
前置条件
配置 Singular 平台
在您的应用中实现卸载追踪之前,请先在 Singular 平台中配置您的应用,并完成 设置 Android 卸载追踪 中描述的 Android SDK + FCM 集成步骤。
系统要求
卸载追踪需要 Firebase Cloud Messaging 和特定的设备配置。
FCM 要求 ( 来源 ):
- Android 版本: 设备必须运行 Android 4.1 (API 16) 或更高版本
- Google Play 服务: 设备必须安装 Google Play 商店应用
- 模拟器支持: 支持搭载 Google API 的 Android 4.1+ 模拟器
- 分发: 应用可以在 Google Play 商店之外进行分发,同时仍支持 卸载追踪
注意: 使用不受支持的 Android 版本或没有 Google Play 服务的设备 的用户将不会被纳入卸载追踪。
实现步骤
步骤 1:集成 Firebase Cloud Messaging
如果尚未配置,请在您的应用中设置 Firebase Cloud Messaging。
请遵循 Google 的官方指南 在 Android 上设置 Firebase Cloud Messaging 客户端应用 。这包括:
- 将 Firebase 添加到您的 Android 项目
-
将 FCM SDK 依赖项添加到您的
app/build.gradle - 创建 Firebase Messaging Service 类
- 请求通知权限 (Android 13+)
步骤 2:确认 AndroidManifest.xml 中的 FCM 设置
验证 FCM 服务和权限
确保您的应用已与 Firebase Cloud Messaging 集成,并且 Android 清单中已声明 一个 FirebaseMessagingService 来接收 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>
<!-- 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。
步骤 3:注册 FCM 设备 token
获取 FCM 设备 token 并将其发送给 Singular 以进行卸载追踪。
获取并设置 token
获取 FCM token,并在 SDK 初始化后立即将其注册到 Singular。
import com.google.firebase.messaging.FirebaseMessaging
import com.singular.sdk.Singular
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Initialize Singular SDK
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
Singular.init(applicationContext, config)
// Retrieve and register FCM token
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
if (!task.isSuccessful) {
Log.w("FCM", "Fetching FCM token failed", task.exception)
return@addOnCompleteListener
}
// Get FCM token
val token = task.result
// Register token with Singular
Singular.setFCMDeviceToken(token)
Log.d("FCM", "FCM token registered with Singular: $token")
}
}
}import com.google.firebase.messaging.FirebaseMessaging;
import com.singular.sdk.Singular;
import com.singular.sdk.SingularConfig;
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Initialize Singular SDK
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET");
Singular.init(getApplicationContext(), config);
// Retrieve and register FCM token
FirebaseMessaging.getInstance().getToken()
.addOnCompleteListener(new OnCompleteListener<String>() {
@Override
public void onComplete(@NonNull Task<String> task) {
if (!task.isSuccessful()) {
Log.w("FCM", "Fetching FCM token failed", task.getException());
return;
}
// Get FCM token
String token = task.getResult();
// Register token with Singular
Singular.setFCMDeviceToken(token);
Log.d("FCM", "FCM token registered with Singular: " + token);
}
});
}
}
最佳实践:
在
Singular.init()
之后立即注册 FCM token,以确保从第一次应用会话开始就启用卸载追踪。
Singular.setFCMDeviceToken()
在
Singular.init()
完成之前被调用,或者 token 参数为
null
或为空时,会静默地不执行任何操作。如果您的 token 注册看起来没有效果,
请确认 SDK 已先初始化,并且 Firebase 返回的 FCM token 是非空字符串。
处理 token 刷新
每当 FCM token 刷新时,请在 Singular 中更新 token,以保持卸载追踪的准确性。
import com.google.firebase.messaging.FirebaseMessagingService
import com.singular.sdk.Singular
class MyFirebaseMessagingService : FirebaseMessagingService() {
override fun onNewToken(token: String) {
super.onNewToken(token)
// Send updated token to Singular
Singular.setFCMDeviceToken(token)
Log.d("FCM", "New FCM token registered: $token")
// Also send token to your server if needed
sendTokenToServer(token)
}
private fun sendTokenToServer(token: String) {
// Implement your server communication logic here
}
}import com.google.firebase.messaging.FirebaseMessagingService;
import com.singular.sdk.Singular;
public class MyFirebaseMessagingService extends FirebaseMessagingService {
@Override
public void onNewToken(@NonNull String token) {
super.onNewToken(token);
// Send updated token to Singular
Singular.setFCMDeviceToken(token);
Log.d("FCM", "New FCM token registered: " + token);
// Also send token to your server if needed
sendTokenToServer(token);
}
private void sendTokenToServer(String token) {
// Implement your server communication logic here
}
}
重要:
FCM token 可能随时刷新(应用更新、设备恢复等)。请始终
实现
onNewToken()
,以保持 Singular 的更新。
备用配置方法
在初始化期间设置 token
如果您在 SDK 初始化之前已经获得 FCM token,请在
SingularConfig
对象中进行配置。
// Get token synchronously (if cached)
val cachedToken = getStoredFCMToken() // Your caching logic
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
.withFCMDeviceToken(cachedToken)
Singular.init(applicationContext, config)// Get token synchronously (if cached)
String cachedToken = getStoredFCMToken(); // Your caching logic
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
.withFCMDeviceToken(cachedToken);
Singular.init(getApplicationContext(), config);方法签名:
public SingularConfig withFCMDeviceToken(String fcmDeviceToken);
withFCMDeviceToken
仅用初始化时所拥有的 token 来初始化 SDK,并不订阅 token 刷新。您仍需
实现
FirebaseMessagingService.onNewToken
并在其中调用
Singular.setFCMDeviceToken(newToken)
,以保持 Singular 的记录最新。如果提供的 token 为
null
或为空,此配置方法也会静默地不执行任何操作。
验证和故障排除
验证实现
确认卸载追踪正常工作。
- 检查日志: 验证日志中是否出现 FCM token 注册信息
- 测试 token 生成: 确保在首次启动应用时生成 token
- 监控仪表板: 24-48 小时后在 Singular 仪表板中查看卸载追踪 数据
- 测试 token 刷新: 清除应用数据并验证 token 是否正确更新
常见问题
- 未生成 token: 验证 FCM 依赖项是否已正确添加,并且 Firebase 已在您的项目中配置
-
token 未更新:
检查
onNewToken()回调是否已在您的 FirebaseMessagingService 中实现 - 数据缺失: 确保设备满足 FCM 要求(Android 4.1+,已安装 Google Play 服务)
- 配置错误: 确认在 Singular 平台设置中已启用卸载追踪
其他资源: 有关详细的故障排除,请参阅 卸载追踪设置指南 和 Firebase Cloud Messaging 文档 。