Android SDK - 设置全局属性

关注
Avatar
Jared Ornstead
Updated
文件

设置全局属性

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

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

属性规格

限制和持久性

了解全局属性的限制和持久性行为。

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

在初始化时设置全局属性

通过 SingularConfig 配置

在调用Singular.init() 之前，使用withGlobalProperty 方法在 SDK 初始化过程中设置全局属性。

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

KotlinJava 
// Set global properties during initialization
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("MyProperty", "MyValue", true)
    .withGlobalProperty("AnotherProperty", "AnotherValue", true)

Singular.init(applicationContext, config)

方法签名： 

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting)

参数：

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

初始化后管理属性

设置全局属性

在应用程序运行期间的任何时候添加或更新全局属性。

KotlinJava 
// Set a global property after initialization
val result = Singular.setGlobalProperty("MyProperty", "MyValue", true)
if (result) {
    Log.d("Singular", "Property set successfully")
} else {
    Log.e("Singular", "Failed to set property")
}

方法签名： 

public static boolean setGlobalProperty(String key, String value, boolean overrideExisting)

Returns: true if the property was set successfully,false otherwise

重要：

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

获取全局属性

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

KotlinJava 
// Retrieve all global properties
val properties: Map<String, String> = Singular.getGlobalProperties()

// Iterate through properties
properties.forEach { (key, value) ->
    Log.d("Singular", "Property: $key = $value")
}

方法签名： 

public static Map<String, String> getGlobalProperties()

返回值：包含所有全局属性键值对的 Map

取消设置全局属性

通过键值移除特定全局属性。

KotlinJava 
// Remove a specific global property
Singular.unsetGlobalProperty("MyProperty")

方法签名： 

public static void unsetGlobalProperty(String key)

参数：

  • key：要移除的属性名称

清除所有全局属性

一次性删除所有全局属性。

KotlinJava 
// Remove all global properties
Singular.clearGlobalProperties()

方法签名： 

public static void clearGlobalProperties()

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

实现示例

完整使用模式

在整个应用程序生命周期内跟踪应用程序级和用户特定属性。

KotlinJava 
// Initialize SDK with app-level global properties
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("app_version", BuildConfig.VERSION_NAME, true)

Singular.init(applicationContext, config)

// Set third-party identifier on login
fun onUserLogin(thirdPartyUserId: String) {
    val success = Singular.setGlobalProperty("third_party_identifier", thirdPartyUserId, true)
    if (success) {
        Log.d("Singular", "Third-party identifier set")
    }
}

// Clear third-party identifier on logout
fun onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    Log.d("Singular", "Third-party identifier cleared")
}

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