设置全局归因

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

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

归因规范

限制和持久性

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

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

在初始化时设置全局归因

通过SingularConfig进行配置

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

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

func getConfig() -> SingularConfig? {
    // Create config with API credentials
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Set global properties during initialization
    config.setGlobalProperty("MyProperty", withValue: "MyValue", overrideExisting: true)
    config.setGlobalProperty("AnotherProperty", withValue: "AnotherValue", overrideExisting: true)

    return config
}

// Initialize SDK with config
if let config = getConfig() {
    Singular.start(config)
}

- (SingularConfig *)getConfig {
    // Create config with API credentials
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Set global properties during initialization
    [config setGlobalProperty:@"MyProperty" withValue:@"MyValue" overrideExisting:YES];
    [config setGlobalProperty:@"AnotherProperty" withValue:@"AnotherValue" overrideExisting:YES];

    return config;
}

// Initialize SDK with config
SingularConfig *config = [self getConfig];
[Singular start:config];

方法签名:

- (void)setGlobalProperty:(NSString *)key withValue:(NSString *)value overrideExisting:(BOOL)overrideExisting;

参数:

key: 归因名称(最多200个字符)
value: 归因值(最多200个字符)
overrideExisting: 是否覆盖具有相同键的现有归因

初始化后管理归因

设置全局归因

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

// Set a global property after initialization
let result = Singular.setGlobalProperty("MyProperty",
    andValue: "MyValue",
    overrideExisting: true)

if result {
    print("Property set successfully")
} else {
    print("Failed to set property")
}

// Set a global property after initialization
BOOL result = [Singular setGlobalProperty:@"MyProperty"
    andValue:@"MyValue"
    overrideExisting:YES];

if (result) {
    NSLog(@"Property set successfully");
} else {
    NSLog(@"Failed to set property");
}

方法签名:

+ (BOOL)setGlobalProperty:(NSString *)key andValue:(NSString *)value overrideExisting:(BOOL)overrideExisting;

返回值: true 如果归因设置成功,否则返回 false

重要 — 运行时 +setGlobalProperty:andValue:overrideExisting: 返回 NO 的情况:

key 为 nil 或为空
SDK尚未启动 (+start: 未运行)
已存在5个归因,并且您尝试添加新归因
具有相同键的归因已存在,且 overrideExisting 为 NO — 值不会被替换

在假定归因已存储之前,请始终检查返回值。

配置时与运行时行为: 配置时的实例方法 -setGlobalProperty:withValue:overrideExisting: 在 SingularConfig 上返回 void — 如果达到5个归因的限制或键为空,它会静默地不执行任何操作。运行时的类方法在 Singular 上返回 BOOL 并暴露失败。如果可以,优先在配置时设置归因; 当您需要失败反馈时,使用运行时方法。

获取全局归因

以Dictionary的形式检索当前所有已设置的全局归因及其值。

// Retrieve all global properties
let properties = Singular.getGlobalProperties()

// Iterate through properties
if let properties = properties as? [String: String] {
    for (key, value) in properties {
        print("Property: \(key) = \(value)")
    }
}

// Retrieve all global properties
NSDictionary *properties = [Singular getGlobalProperties];

// Iterate through properties
for (NSString *key in properties) {
    NSString *value = properties[key];
    NSLog(@"Property: %@ = %@", key, value);
}

方法签名:

+ (NSDictionary *)getGlobalProperties;

返回值: 一个包含所有全局归因键值对的Dictionary

取消设置全局归因

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

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

// Remove a specific global property
[Singular unsetGlobalProperty:@"MyProperty"];

方法签名:

+ (void)unsetGlobalProperty:(NSString *)key;

参数:

key: 要移除的归因的名称

清除所有全局归因

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

// Remove all global properties
Singular.clearGlobalProperties()

// Remove all global properties
[Singular clearGlobalProperties];

方法签名:

+ (void)clearGlobalProperties;

最佳实践: 当用户注销或您需要将所有自定义追踪归因重置为默认状态时,使用 clearGlobalProperties() 。

实现示例

完整使用模式

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

// Initialize SDK with app-level global properties
func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Set app version as a global property
    if let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String {
        config.setGlobalProperty("app_version", withValue: appVersion, overrideExisting: true)
    }

    return config
}

// Set third-party identifier on login
func onUserLogin(thirdPartyUserId: String) {
    let success = Singular.setGlobalProperty("third_party_identifier",
        andValue: thirdPartyUserId,
        overrideExisting: true)

    if success {
        print("Third-party identifier set")
    }
}

// Clear third-party identifier on logout
func onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    print("Third-party identifier cleared")
}

// Initialize SDK with app-level global properties
- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Set app version as a global property
    NSString *appVersion = [[NSBundle mainBundle] infoDictionary][@"CFBundleShortVersionString"];
    if (appVersion) {
        [config setGlobalProperty:@"app_version" withValue:appVersion overrideExisting:YES];
    }

    return config;
}

// Set third-party identifier on login
- (void)onUserLogin:(NSString *)thirdPartyUserId {
    BOOL success = [Singular setGlobalProperty:@"third_party_identifier"
        andValue:thirdPartyUserId
        overrideExisting:YES];

    if (success) {
        NSLog(@"Third-party identifier set");
    }
}

// Clear third-party identifier on logout
- (void)onUserLogout {
    [Singular unsetGlobalProperty:@"third_party_identifier"];
    NSLog(@"Third-party identifier cleared");
}

最佳实践: 将第三方分析标识符 (例如, Mixpanel distinct_id、Amplitude user_id)同步到Singular全局归因, 以实现统一的跨平台追踪。在登录时设置用户特定标识符,并在注销时使用 unsetGlobalProperty() 清除它们。诸如 app_version 之类的应用级别归因会在会话之间持久存储。

iOS SDK - 设置全局归因

设置全局归因

归因规范

限制和持久性

在初始化时设置全局归因

通过SingularConfig进行配置

初始化后管理归因

设置全局归因

获取全局归因

取消设置全局归因

清除所有全局归因

实现示例

完整使用模式