Cordova SDK - 设置全局属性

关注
Avatar
Jared Ornstead
Updated
文件

设置全局属性

定义自定义属性，这些属性会自动附加到应用程序发送的每个会话和事件，从而在报告中实现详细的数据细分。

全局属性可让您跟踪任何用户、应用模式或您需要的上下文信息。例如，在一个游戏应用程序中，创建一个初始化为 "0 "的 "级别 "属性，该属性会随着用户的进度而更新。所有会话和事件都包含该属性，这样就可以按用户级别分析会话、事件计数和收入。

属性规格

限制和持久性

在实施前了解全局属性的限制和持久性行为。

  • 最大属性数：每个应用程序安装最多可定义 5 个全局属性
  • 持久性：属性会在应用程序启动之间以最新值持续存在，直到明确取消设置或卸载应用程序为止
  • 字符限制：属性名称和值最长可达 200 个字符。较长的值将自动截断为 200 个字符
  • 数据可用性：全局属性可在用户级导出和回传中访问。请联系您的 Singular 客户成功经理，了解有关汇总报告支持的最新信息。

在初始化时设置全局属性

在 SDK 初始化前配置

在 SDK 初始化之前使用withGlobalProperty() 设置全局属性，以确保它们包含在初始会话中。

由于全局属性会在应用程序启动之间持续存在，因此可能已经存在不同值的属性。使用overrideExisting参数可控制新值是否覆盖现有值。

JavaScript 
// Initialize SDK with global properties
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Set app-level global properties before initialization
config.withGlobalProperty('app_version', '1.2.3', true);
config.withGlobalProperty('user_type', 'free', true);

// Initialize SDK with global properties
cordova.plugins.SingularCordovaSdk.init(config);

方法签名： 

withGlobalProperty(key: string, value: string, overrideExisting: boolean): SingularConfig

参数：

  • key：属性名称（最多 200 个字符）
  • value：属性值（最多 200 个字符属性值（最多 200 个字符）
  • overrideExisting（覆盖现有属性是否覆盖具有相同键的现有属性

初始化后管理属性

设置全局属性

在应用程序运行期间的任何时刻，使用setGlobalProperty() 添加或更新全局属性。

JavaScript 
// Set a global property after initialization
function updatePlayerLevel(level) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    level.toString(),
    true,
    function(success) {
      if (success) {
        console.log('Global property set successfully');
      } else {
        console.error('Failed to set property - may have reached 5 property limit');
      }
    }
  );
}

方法签名： 

setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void

参数：

  • key：属性名称（最多 200 个字符）
  • value：属性值（最多 200 个字符属性值（最多 200 个字符）
  • overrideExisting（覆盖现有属性是否覆盖具有相同键的现有属性
  • success：成功：回调函数，如果属性设置成功，则接收true ，否则接收false

重要：

  • 如果已存在 5 个属性，而您试图添加一个新属性，则回调函数将收到false
  • overrideExisting 参数决定是否替换现有属性值
  • 始终检查返回值以确认属性已成功设置

获取全局属性

以对象形式读取当前设置的所有全局属性及其值。

JavaScript 
// Retrieve all global properties
function displayGlobalProperties() {
  cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    // Iterate through properties
    for (var key in properties) {
      if (properties.hasOwnProperty(key)) {
        console.log('Property: ' + key + ' = ' + properties[key]);
      }
    }
  });
}

方法签名： 

getGlobalProperties(success: Function): void

参数：

  • 成功：回调函数，接收包含所有全局属性键值对的对象

取消设置全局属性

当不再需要跟踪特定全局属性时，通过键值删除该属性。

JavaScript 
// Remove a specific global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');

方法签名： 

unsetGlobalProperty(key: string): void

参数：

  • key：要移除的属性名称

清除所有全局属性

一次性删除所有全局属性，通常是在用户注销或需要重置所有跟踪属性时。

JavaScript 
// Remove all global properties
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();

方法签名： 

clearGlobalProperties(): void

最佳实践：当用户注销或需要将所有自定义跟踪属性重置为默认状态时，请使用clearGlobalProperties()。

实现示例

完整使用模式

通过适当的错误处理和登录/注销管理，在整个应用程序生命周期内跟踪应用程序级和用户特定属性。

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

function initializeApp() {
  // Set app-level global properties before initialization
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  config.withGlobalProperty('app_version', '1.2.3', true);
  config.withGlobalProperty('platform', 'cordova', true);
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

// Set user-specific properties on login
function handleUserLogin(userId, userTier) {
  // Set third-party identifier
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'third_party_id',
    userId,
    true,
    function(success) {
      if (success) {
        // Set user tier property
        cordova.plugins.SingularCordovaSdk.setGlobalProperty('user_tier', userTier, true, function(tierSuccess) {
          if (tierSuccess) {
            console.log('User properties set successfully');
          }
        });
      } else {
        console.error('Failed to set user properties');
      }
    }
  );
}

// Update dynamic properties during gameplay
function handleLevelUp(newLevel) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    newLevel.toString(),
    true,
    function(success) {
      if (success) {
        // Track level up event
        cordova.plugins.SingularCordovaSdk.eventWithArgs('level_up', {
          new_level: newLevel
        });
      }
    }
  );
}

// Clear user-specific properties on logout
function handleUserLogout() {
  // Remove user-specific properties
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('third_party_id');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('user_tier');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');
  
  console.log('User properties cleared');
}

最佳实践：将第三方分析标识符（如 Mixpanel distinct_id、Amplitude user_id）同步到 Singular 全局属性，以实现统一的跨平台跟踪。登录时设置特定于用户的标识符，注销时使用unsetGlobalProperty() 清除这些标识符。应用程序级属性（如app_version ）可跨会话持续存在。

属性限制管理：全局属性最多为 5 个，可优先选择对分析最有价值的跟踪维度。如果达到限制，可考虑先删除不那么重要的属性，然后再添加新属性。上面的示例展示了如何通过检查返回值从容应对 5 个属性限制。