Cordova SDK - 卸载跟踪

关注
Avatar
Jared Ornstead
Updated
文档

卸载跟踪

通过将推送通知服务与 Singular SDK 集成，跟踪应用程序的卸载情况，以衡量用户留存率并优化重新参与活动。

重要：Google 已于 2018 年 4 月弃用 GCM API。 所有 Android 卸载跟踪实施均使用 Firebase Cloud Messaging (FCM)。

卸载跟踪概述

卸载跟踪如何工作

卸载跟踪通过向 Singular 注册推送通知令牌来监控应用程序的删除情况。当设备不再响应推送通知时，Singular 就会将应用识别为已卸载。

  • 安卓：使用 Firebase Cloud Messaging（FCM）令牌检测卸载情况
  • iOS：使用苹果推送通知服务（APNs）令牌检测卸载情况
  • 数据准确性：深入了解用户保留率和长期参与度

安卓卸载跟踪

前提条件

在实施安卓卸载跟踪之前，请按照《安卓卸载跟踪设置指南》在 Singular 平台上配置您的应用程序。

要求

  • 安卓版本：设备必须运行 Android 4.1（API 16）或更高版本
  • Google Play 服务：设备必须安装 Google Play Store 应用程序
  • Firebase 设置：必须在项目中配置 Firebase 云消息服务
  • 权限：Android 13+ 需要明确的通知权限

实施步骤

第 1 步：安装 Firebase 插件

在您的 Cordova 项目中添加 Firebase 插件以支持推送通知。 建议使用cordova-plugin-firebase-messaging插件。

bash 
cordova plugin add cordova-plugin-firebase-messaging

有关 Firebase 的详细设置说明，请参阅插件文档。

第 2 步：配置 Firebase

在您的 Cordova Android 项目中添加 Firebase 配置文件。

  1. 在 Firebase 控制台项目中注册 Android 应用程序
  2. 下载google-services.json 并将其放入项目根目录或platforms/android/app/
  3. 在安装插件时确认 Firebase 消息传递依赖项已添加到您的项目中

第 3 步：申请通知权限

在检索 FCM 令牌之前，向用户申请通知权限（Android 13+ 需要）。

JavaScript 
document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  if (device.platform === 'Android') {
    // Request notification permission (Android 13+)
    requestAndroidNotificationPermission();
  }
}

function requestAndroidNotificationPermission() {
  // Check Android version
  if (device.version >= 13) {
    cordova.plugins.permissions.requestPermission(
      cordova.plugins.permissions.POST_NOTIFICATIONS,
      function(status) {
        if (status.hasPermission) {
          console.log('Notification permission granted');
          retrieveAndRegisterFCMToken();
        } else {
          console.warn('Notification permission denied - uninstall tracking unavailable');
        }
      },
      function(error) {
        console.error('Permission request error:', error);
      }
    );
  } else {
    // Android 12 and below automatically have permission
    retrieveAndRegisterFCMToken();
  }
}

注意：要申请权限，请安装cordova-plugin-android-permissions 插件： 

cordova plugin add cordova-plugin-android-permissions

步骤 4: 获取和注册 FCM 令牌

获取 FCM 设备令牌，并在授予权限后使用setUninstallToken() 方法在 Singular 注册。

JavaScript 
function retrieveAndRegisterFCMToken() {
  // Get FCM token
  cordova.plugins.firebase.messaging.getToken().then(function(token) {
    if (token) {
      console.log('FCM token retrieved:', token);
      
      // Register token with Singular for uninstall tracking
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
      
      console.log('FCM token registered with Singular');
    } else {
      console.warn('No FCM token available');
    }
  }).catch(function(error) {
    console.error('Error retrieving FCM token:', error);
  });
}

有关完整的方法文档，请参阅setUninstallToken 参考资料。

步骤 5：处理令牌刷新

每当刷新FCM令牌时，就用Singular更新令牌，以保持准确的卸载跟踪。

JavaScript 
document.addEventListener('deviceready', setupTokenRefreshListener, false);

function setupTokenRefreshListener() {
  if (device.platform === 'Android') {
    // Listen for FCM token refresh events
    cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
      console.log('FCM token refreshed:', token);
      
      // Update Singular with new token
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
    });
  }
}

最佳做法：FCM 令牌可以随时刷新（应用程序更新、设备还原等）。请始终订阅令牌刷新事件，以便 Singular 随时更新最新令牌。

iOS 卸载跟踪

前提条件

按照《iOS 卸载跟踪设置指南》在 Singular 平台上配置您的 iOS 应用程序。

iOS 卸载跟踪使用苹果推送通知服务（APN）技术。如果您的应用程序不支持推送通知，请参阅 Apple向 APNs 注册应用程序的指南。

实施步骤

步骤 1：请求 iOS 通知授权

向用户请求通知权限并获取 APNS 设备令牌。

JavaScript 
document.addEventListener('deviceready', initializeIOSTracking, false);

function initializeIOSTracking() {
  if (device.platform === 'iOS') {
    requestIOSNotificationPermission();
  }
}

function requestIOSNotificationPermission() {
  // Request iOS notification authorization
  cordova.plugins.firebase.messaging.requestPermission({
    forceShow: true
  }).then(function(hasPermission) {
    if (hasPermission) {
      console.log('iOS notification permission granted');
      retrieveAndRegisterAPNSToken();
    } else {
      console.warn('iOS notification permission denied - uninstall tracking unavailable');
    }
  }).catch(function(error) {
    console.error('Error requesting iOS notification permission:', error);
  });
}

步骤 2：检索和注册 APNS 令牌

获取 APNS 设备令牌，并在获得授权后使用setUninstallToken() 方法在 Singular 注册。

JavaScript 
function retrieveAndRegisterAPNSToken() {
  // Get APNS token (iOS)
  cordova.plugins.firebase.messaging.getToken().then(function(token) {
    if (token) {
      console.log('APNS token retrieved:', token);
      
      // Register token with Singular for uninstall tracking
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
      
      console.log('APNS token registered with Singular');
    } else {
      console.warn('No APNS token available');
    }
  }).catch(function(error) {
    console.error('Error retrieving APNS token:', error);
  });
}

令牌格式：从 Firebase Messaging 获取的 APNS 令牌已经为 Singular 正确格式化。无需额外转换。

步骤 3：处理令牌刷新（iOS）

如果 APNS 令牌在应用程序生命周期内发生变化，则使用 Singular 更新令牌。

JavaScript 
document.addEventListener('deviceready', setupIOSTokenRefreshListener, false);

function setupIOSTokenRefreshListener() {
  if (device.platform === 'iOS') {
    // Listen for APNS token refresh events
    cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
      console.log('APNS token refreshed:', token);
      
      // Update Singular with new token
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
    });
  }
}

完整的跨平台实施

统一卸载跟踪设置

通过正确的错误处理和令牌刷新逻辑，为 Android 和 iOS 平台实施卸载跟踪。

JavaScript 
document.addEventListener('deviceready', initializeUninstallTracking, false);

function initializeUninstallTracking() {
  console.log('Initializing uninstall tracking for:', device.platform);
  
  // Setup token refresh listener for both platforms
  setupTokenRefreshListener();
  
  // Platform-specific initialization
  if (device.platform === 'Android') {
    setupAndroidUninstallTracking();
  } else if (device.platform === 'iOS') {
    setupIOSUninstallTracking();
  }
}

function setupAndroidUninstallTracking() {
  // Check Android version for permission requirements
  if (device.version >= 13) {
    // Request notification permission for Android 13+
    cordova.plugins.permissions.requestPermission(
      cordova.plugins.permissions.POST_NOTIFICATIONS,
      function(status) {
        if (status.hasPermission) {
          retrieveAndRegisterToken();
        } else {
          console.warn('Android notification permission denied');
        }
      },
      function(error) {
        console.error('Permission request error:', error);
      }
    );
  } else {
    // Android 12 and below - permission not required
    retrieveAndRegisterToken();
  }
}

function setupIOSUninstallTracking() {
  // Request iOS notification authorization
  cordova.plugins.firebase.messaging.requestPermission({
    forceShow: true
  }).then(function(hasPermission) {
    if (hasPermission) {
      retrieveAndRegisterToken();
    } else {
      console.warn('iOS notification permission denied');
    }
  }).catch(function(error) {
    console.error('Error requesting iOS permission:', error);
  });
}

function retrieveAndRegisterToken() {
  // Get push notification token (FCM for Android, APNS for iOS)
  cordova.plugins.firebase.messaging.getToken()
    .then(function(token) {
      if (token) {
        console.log('Token retrieved for ' + device.platform + ':', token);
        
        // Register token with Singular
        cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
        
        console.log('Token registered with Singular successfully');
      } else {
        console.warn('No token available for ' + device.platform);
      }
    })
    .catch(function(error) {
      console.error('Error retrieving token:', error);
    });
}

function setupTokenRefreshListener() {
  // Listen for token refresh events on both platforms
  cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
    console.log('Token refreshed for ' + device.platform + ':', token);
    
    // Update Singular with new token
    cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
  });
}

验证和故障排除

验证实施

在部署到生产环境之前，确认卸载跟踪工作正常。

  1. 检查日志：验证令牌注册是否以正确格式出现在控制台日志中
  2. 测试令牌生成：确保在授予权限后首次启动应用程序时生成令牌
  3. 监控仪表板：在 24-48 小时后检查 Singular 仪表板上的卸载跟踪数据
  4. 测试令牌刷新：清除应用程序数据并验证重新启动应用程序时令牌更新是否正确

常见问题

  • 令牌未生成：验证 Firebase 插件是否正确安装，Firebase 是否配置在 Cordova 项目中
  • 权限被拒绝：检查用户是否授予了通知权限（Android 13+ 和所有 iOS 版本都需要
  • 令牌未更新：确保您已订阅两个平台的onTokenRefresh 事件
  • 数据缺失：确认设备符合平台要求（Android 4.1+ 支持 Google Play 服务，iOS 支持 APNs
  • 配置错误：确认已在应用程序的 Singular 平台设置中启用卸载跟踪功能
  • Firebase 设置：对于 Android，确保google-services.json 位于正确位置。对于 iOS，请确保GoogleService-Info.plist 已添加到 Xcode 项目中。

其他资源：有关详细的故障排除，请参阅《Android 卸载跟踪设置指南》、《iOS 卸载跟踪设置指南》和Firebase 消息插件文档。

最佳实践

  • 尽早申请权限：在入职时或用户价值确定后请求通知权限
  • 优雅地处理拒绝：在权限被拒绝时提供明确的信息，并向用户解释其好处
  • 测试两个平台：验证在不同操作系统版本的 Android 和 iOS 上的实施效果
  • 监控令牌刷新：始终实施令牌刷新监听器，自动处理令牌更新
  • 日志调试：在开发过程中启用详细日志记录，以跟踪令牌生成和注册情况