设置全局归因

定义自动附加到从您的应用发送的每个会话和事件的自定义归因，从而在报告中实现详细的数据分段。

全局归因允许您追踪所需的任何用户、应用模式或上下文信息。例如，在游戏应用中，创建一个初始化为"0"的"Level"归因，并随着用户的进展而更新。所有会话和事件都会包含此归因，从而允许您按用户级别分析会话、事件计数和收入。

归因规范

限制和持久性

了解全局归因的约束和持久性行为。

• 最大归因数： 每次应用安装最多可定义 5 个全局归因
• 持久性： 归因在应用启动之间保留其最新值，直到被显式取消或应用被卸载
• 字符限制： 归因名称和值最多可包含 200 个字符。超长值会自动截断为 200 个字符
• 数据可用性： 全局归因可在用户级导出和回传中访问。请联系您的 Singular 客户成功经理以获取聚合报告支持的更新信息

在初始化时设置全局归因

通过 SingularConfig 配置

在调用 Singular.init() 之前，使用 withGlobalProperty 方法在 SDK 初始化期间设置全局归因。

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

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

Singular.init(applicationContext, config)

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

Singular.init(getApplicationContext(), config);

方法签名：

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

参数：

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

初始化后管理归因

设置全局归因

在应用运行时的任何时候添加或更新全局归因。

// 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")
}

// Set a global property after initialization
boolean 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)

返回值： true 如果归因已成功设置，否则返回 false

获取全局归因

将当前设置的所有全局归因及其值作为 Map 检索。

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

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

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

// Iterate through properties
for (Map.Entry<String, String> entry : properties.entrySet()) {
    Log.d("Singular", "Property: " + entry.getKey() + " = " + entry.getValue());
}

方法签名：

public static Map<String, String> getGlobalProperties()

返回值： 包含所有全局归因键值对的 Map

取消全局归因

通过键删除特定的全局归因。

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

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

方法签名：

public static void unsetGlobalProperty(String key)

参数：

• key： 要删除的归因的名称

清除所有全局归因

一次性删除所有全局归因。

// Remove all global properties
Singular.clearGlobalProperties()

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

方法签名：

public static void clearGlobalProperties()

实现示例

完整使用模式

在整个应用程序生命周期中追踪应用级和用户特定的归因。

// 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")
}

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

Singular.init(getApplicationContext(), config);

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

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