Cordova SDK - 设置用户 ID

关注
Avatar
Jared Ornstead
Updated
文档

设置用户 ID

向 Singular 发送内部用户 ID，以实现跨设备跟踪和用户级数据报告。此标识符可跨会话和设备链接用户活动，以进行全面的归因分析。

注：如果使用Singular 的跨设备解决方案，必须使用登录或验证流程在所有平台上收集用户 ID。

用户 ID 要求

隐私和最佳实践

在实施用户 ID 跟踪时，请遵循以下指导原则，以确保隐私合规和正确的跨设备测量。

  • 无 PII：用户 ID 不应暴露个人身份信息 (PII)，如电子邮件地址、用户名或电话号码。使用与第一方数据唯一的散列值。
  • 跨平台一致性：用户 ID 值必须是您在所有平台（网络/移动/PC/控制台/离线）上获取的相同内部标识符，以便进行准确的跨设备测量。
  • 第一方数据：用户 ID 是第一方数据，不会与第三方共享。
  • 持久性：用户 ID 会一直存在，直到使用unsetCustomUserId() 明确取消设置或卸载应用程序。关闭或重启应用程序不会清除用户 ID。

实施概述

何时设置用户 ID

使用setCustomUserId() 设置用户标识符，使用unsetCustomUserId() 注销时清除用户标识符。根据用户 ID 在应用流程中的可用时间选择实施方法。

最佳实践：如果多个用户共用一台设备，请执行注销流程，在登录时调用setCustomUserId() ，在注销时调用unsetCustomUserId() 。

如果您已经知道应用程序打开时的用户 ID（例如，用户已持续登录），请在初始化 Singular SDK 之前使用withCustomUserId() 进行配置。这样可以确保 Singular 从第一次会话中接收到用户 ID。不过，在用户注册或登录之前，用户 ID 通常是不可用的，在这种情况下，请在注册或身份验证流程完成后调用setCustomUserId() 。

SDK 方法

设置自定义用户 ID

向 Singular 发送内部用户 ID，用于跨设备跟踪和用户级报告。认证成功后立即调用此方法，以确保所有后续事件都与用户相关联。

JavaScript 
// Set the user ID after login or registration
cordova.plugins.SingularCordovaSdk.setCustomUserId('user_123456');

方法签名： 

setCustomUserId(customUserId: string): void

示例：登录后设置用户 ID

在用户成功完成身份验证后立即调用setCustomUserId() ，以确保所有后续事件都与其用户 ID 关联。

JavaScript 
function handleUserLogin(email, password) {
  // Your authentication logic
  authenticateUser(email, password)
    .then(function(response) {
      if (response.success) {
        // Set the user ID in Singular after successful login
        cordova.plugins.SingularCordovaSdk.setCustomUserId(response.userId);
        
        console.log('User ID set:', response.userId);
        
        // Navigate to home screen
        navigateToHome();
      }
    })
    .catch(function(error) {
      console.error('Login failed:', error);
    });
}

取消设置自定义用户 ID

在用户注销时清除用户 ID，以确保对多用户设备进行准确的会话跟踪。这可防止后续事件错误地归属于注销用户。

JavaScript 
// Unset the user ID on logout
cordova.plugins.SingularCordovaSdk.unsetCustomUserId();

方法签名： 

unsetCustomUserId(): void

示例：注销时取消设置用户 ID

在注销流程中调用unsetCustomUserId() ，清除用户 ID，防止后续事件的错误归属。

JavaScript 
function handleUserLogout() {
  // Clear app data and user session
  clearUserSession()
    .then(function() {
      // Unset the user ID in Singular
      cordova.plugins.SingularCordovaSdk.unsetCustomUserId();
      
      console.log('User ID cleared');
      
      // Navigate to login screen
      navigateToLogin();
    })
    .catch(function(error) {
      console.error('Logout failed:', error);
    });
}

在初始化过程中设置用户 ID

如果用户 ID 在应用程序启动时可用（例如，用户已通过持久会话登录），可在 SDK 初始化期间使用withCustomUserId() 进行配置。这样可确保首次会话包含用户 ID。

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

function initializeApp() {
  // Check if user is already logged in (e.g., from local storage)
  var userId = localStorage.getItem('user_id');
  
  // Create configuration
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  // If user ID exists, set it during initialization
  if (userId) {
    config.withCustomUserId(userId);
  }
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
  console.log('Singular SDK initialized');
}

配置方法签名： 

withCustomUserId(customUserId: string): SingularConfig

建议：对于具有持久登录会话的应用程序，在初始化过程中使用withCustomUserId()。对于用户必须每次登录的应用程序，请在验证后调用setCustomUserId() 。