设置全局属性
定义自定义属性，这些属性会自动附加到应用程序发送的每个会话和事件，从而在报告中实现详细的数据细分。
全局属性可让您跟踪任何用户、应用模式或您需要的上下文信息。例如，在一个游戏应用程序中，创建一个初始化为 "0 "的 "级别 "属性，该属性会随着用户的进度而更新。所有会话和事件都包含该属性，这样就可以按用户级别分析会话、事件计数和收入。
属性规格
限制和持久性
了解全局属性的限制和持久性行为。
- 最大属性数：每个应用程序安装最多可定义 5 个全局属性
- 持久性：属性会在应用程序启动之间以最新值持续存在，直到明确取消设置或卸载应用程序为止
- 字符限制：属性名称和值最长可达 200 个字符。较长的值将自动截断为 200 个字符
- 数据可用性：全局属性可在用户级导出和回传中访问。 请联系您的 Singular 客户成功经理，了解有关汇总报告支持的最新信息。
在初始化时设置全局属性
在 SDK 初始化前配置
在 SDK 初始化之前使用SetGlobalProperty() 设置全局属性，以确保它们包含在初始会话中。
由于全局属性会在应用程序启动之间持续存在，因此可能已经存在不同值的属性。
使用overrideExisting 参数可控制新值是否覆盖现有值。
重要提示：如果希望在首次会话中包含全局属性，请禁用 SingularSDKObject 检查器中的 "唤醒时初始化"标志，并在设置属性后手动初始化 SDK。
using UnityEngine;
using Singular;
public class SingularInitializer : MonoBehaviour
{
void Awake()
{
// Set global properties before SDK initialization
SingularSDK.SetGlobalProperty("app_version", Application.version, true);
SingularSDK.SetGlobalProperty("user_type", "free", true);
// Manually initialize SDK to ensure properties are in first session
SingularSDK.InitializeSingularSDK();
}
}方法签名：
public static bool SetGlobalProperty(string key, string value, bool overrideExisting)参数：
- 键：属性名称（最多 200 个字符）
- value：属性值（最多 200 个字符属性值（最多 200 个字符）
- overrideExisting（覆盖现有属性是否覆盖具有相同键的现有属性
初始化后管理属性
设置全局属性
在应用程序运行期间的任何时候添加或更新全局属性。
// Set a global property after initialization
bool result = SingularSDK.SetGlobalProperty("player_level", "5", true);
if (result)
{
Debug.Log("Property set successfully");
}
else
{
Debug.LogError("Failed to set property - may have reached 5 property limit");
}方法签名：
public static bool SetGlobalProperty(string key, string value, bool overrideExisting)
Returns: true if the property was set successfully,false otherwise
重要：
-
如果已存在 5 个属性，而您试图添加一个新属性，该方法将返回
false -
overrideExisting参数决定是否替换现有属性值 - 检查返回值以确认属性已成功设置
获取全局属性
以字典形式读取当前设置的所有全局属性及其值。
// Retrieve all global properties
Dictionary<string, string> properties = SingularSDK.GetGlobalProperties();
// Iterate through properties
foreach (KeyValuePair<string, string> property in properties)
{
Debug.Log($"Property: {property.Key} = {property.Value}");
}方法签名：
public static Dictionary<string, string> GetGlobalProperties()返回值：包含所有全局属性键值对的 dictionary
取消设置全局属性
通过键值删除特定全局属性。
// Remove a specific global property
SingularSDK.UnsetGlobalProperty("player_level");方法签名：
public static void UnsetGlobalProperty(string key)参数：
- key：要移除的属性名称
清除所有全局属性
一次性删除所有全局属性。
// Remove all global properties
SingularSDK.ClearGlobalProperties();方法签名：
public static void ClearGlobalProperties()
最佳实践：在用户注销或需要将所有自定义跟踪属性重置为默认状态时使用ClearGlobalProperties()。
实现示例
完整使用模式
在整个应用程序生命周期内跟踪应用程序级和用户特定属性。
using UnityEngine;
using Singular;
public class GlobalPropertiesManager : MonoBehaviour
{
void Awake()
{
// Set app-level global properties before initialization
SingularSDK.SetGlobalProperty("app_version", Application.version, true);
// Initialize SDK
SingularSDK.InitializeSingularSDK();
}
// Set third-party identifier on login
public void OnUserLogin(string thirdPartyUserId)
{
bool success = SingularSDK.SetGlobalProperty("third_party_identifier", thirdPartyUserId, true);
if (success)
{
Debug.Log("Third-party identifier set");
}
}
// Clear third-party identifier on logout
public void OnUserLogout()
{
SingularSDK.UnsetGlobalProperty("third_party_identifier");
Debug.Log("Third-party identifier cleared");
}
}
最佳实践：将第三方分析标识符（如 Mixpanel distinct_id、Amplitude user_id）同步到 Singular 全局属性，以实现统一的跨平台跟踪。在登录时设置特定于用户的标识符，并在注销时使用UnsetGlobalProperty() 清除这些标识符。应用程序级属性（如app_version ）可跨会话持续存在。
属性限制管理：全局属性最多为 5 个，可优先选择对分析最有价值的跟踪维度。如果达到上限，可考虑先删除不那么重要的属性，然后再添加新属性。上面的示例展示了如何从容应对 5 个属性限制。