简易用户关联（iOS）

概览

在简易用户关联中，神策会通过匿名 ID 和登录 ID 来标识访问 App 的用户。并根据上报事件中携带的信息，将用户的匿名 ID 与登录 ID 进行关联，从而将用户登录前后的行为数据串联起来。

匿名 ID（anonymous_id）默认由神策 SDK 通过自动采集或生成；登录 ID （login_id）需要您通过主动调用登录接口进行记录；
匿名 ID 和登录 ID 会被 SDK 持久化存储，并随着每次事件一并上报。

例如，一个用户首次打开 App，此时触发了一个启动事件（$AppStart），此事件除了包含事件相关的属性信息外，还会携带一个匿名 ID（ SDK 默认采集的值一般为 IDFV ）：

{
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",  //匿名 ID
    "distinct_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",   //神策用户标识 distinct_id，在匿名状态下就是匿名 ID
    "event": "$AppStart",                                    //事件名
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F"             //SDK 默认采集的 IDFV
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "autoTrack"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}

后续用户进行注册登录时，通过主动调用神策 SDK 提供的登录接口，会触发神策预置的 $SignUp 事件，该事件将记录登录 ID（login_id）等其相关信息。同时在之后的事件中都携带该登录 ID：

{
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F", //匿名 ID
    "distinct_id": "your_customer_id",            //神策用户标识 distinct_id，在登录状态下就是登录 ID，即为“your_customer_id” 
    "login_id": "your_customer_id",               //登录 ID，此用户登录时的 ID 为您传入的值，此处传入的为示例信息 “your_customer_id”
    "original_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",     
    "event": "$SignUp",                                    //神策的预置事件，通过主动调用 login 接口触发
    "time": 1710407424971,
    "type": "track_signup",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV
        "$identity_login_id": "your_customer_id"  
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple",
        "age": 18 
    }
}

接口介绍

更改匿名 ID

调用时机

匿名 ID 默认由神策 SDK 自动采集或生成。绝大多数场景下，您无需主动更改匿名 ID 的值。

在 iOS 下，匿名 ID 的取值一般为 IDFV。若您需要自定义匿名 ID 的值，则可通过调用此接口来实现。

使用准备

使用该接口前，请确保您对于神策的接口与用户关联概念有深入的了解。

接口说明

- (void)identify:(NSString *)anonymousId;

参数名称	类型	是否必须	说明
anonymousId	NSString	是	匿名用户 ID，非空字符串，且长度 <= 8192，另外，需要保证唯一性，不然会影响用户关联

使用示例：

Objective-C

[[SensorsAnalyticsSDK sharedInstance] identify:@"your_customized_anonymous_id"];

Swift

SensorsAnalyticsSDK.sharedInstance()?.identify("your_new_anonymous_id")

[[SensorsAnalyticsSDK sharedInstance] identify:@"your_customized_anonymous_id"];

SensorsAnalyticsSDK.sharedInstance()?.identify("your_new_anonymous_id")

调用此接口后后续的事件数据中的匿名 ID 都会更改，事件示例如下：

{
    "anonymous_id": "your_customized_anonymous_id",
    "distinct_id": "your_customized_anonymous_id",
    "event": "SampleEvent",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",    //更改后的匿名 ID
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV 
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}

用户登录

调用时机

当用户进行登录时，您需主动调用此接口，将用户的注册信息（一般为用户在您业务系统中的唯一身份标识）传入。

使用准备

登录 ID 在神策的用户关联体系中非常重要，因此，强烈建议您在用户发生注册或登录时调用此接口来记录用户的登录 ID。

接口说明

- (void)login:(NSString *)loginId withProperties:(NSDictionary * _Nullable )properties;

参数名称	类型	是否必须	说明
loginId	NSString	是	用户登录 ID，非空字符串，且长度 <= 8192
properties	NSDictionary	否	用户登录时传入的属性，可以为 nil

使用示例：

Objective-C

[[SensorsAnalyticsSDK sharedInstance] login:@"your_customer_id" withProperties:@{@"age":@18}];

Swift

SensorsAnalyticsSDK.sharedInstance()?.login("your_customer_id", withProperties: ["age":18])

[[SensorsAnalyticsSDK sharedInstance] login:@"your_customer_id" withProperties:@{@"age":@18}];

SensorsAnalyticsSDK.sharedInstance()?.login("your_customer_id", withProperties: ["age":18])

调用此接口后，SDK 会自动触发神策预置的 $SignUp 事件，事件上报信息示例如下：

{
    "anonymous_id": "your_customized_anonymous_id",
    "distinct_id": "your_customer_id",
    "login_id": "your_customer_id",
    "original_id": "your_customized_anonymous_id",
    "event": "$SignUp",
    "time": 1710407424971,
    "type": "track_signup",
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV
        "$identity_login_id": "your_customer_id"  
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple",
        "age": 18   //调用 login 接口时传入的属性
    }
}

调用此接口后，SDK 会缓存 login_id 信息，并将 distinct_id 的信息修改为 login_id，后续触发的所有事件都将携带 login_id 的信息，并且 distinct_id 的值为 login_id。例如登录后又触发了一次点击事件（buttonClick），其事件数据示例如下：

{
    "anonymous_id": "your_customized_anonymous_id",
    "distinct_id": "your_customer_id",
    "login_id": "your_customer_id",
    "event": "buttonClick",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV
        "$identity_login_id": "your_customer_id"  
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}

用户登出

调用时机

此接口为高阶接口，绝大多数情况下，您无需调用此接口。

如果同一台设备上，先后会登录多个账号，且希望账号 A 退出登录后的所有行为信息都归属于后面登录的账号 B。那么基于神策 SDK 会持久化记录匿名 ID 和登录 ID 的设计。此时您可在账号 A 退出登录时可先调用 用户登出 接口，然后再调用 更改匿名 ID 为匿名 ID 赋予新的值，随后在账号 B 登录时主动调用 用户登录 接口来实现。

使用准备

此接口为高阶接口，需要配合多个接口，并按照特定的顺序调用，才可产生正确效果。因此建议您在使用前，对于神策的接口与用户关联概念有深入的了解，并对于你的业务场景有深入的了解后再进行使用。

接口说明

- (void)logout;

使用示例：

Objective-C

[[SensorsAnalyticsSDK sharedInstance] logout];

Swift

SensorsAnalyticsSDK.sharedInstance()?.logout()

[[SensorsAnalyticsSDK sharedInstance] logout];

SensorsAnalyticsSDK.sharedInstance()?.logout()

调用此接口后，SDK 会将持久化存储中 login_id 信息删除，且不会触发任何神策系统的预置事件。后续该设备上，用户产生的事件，在上报时将不再带有 login_id 信息。

此时，事件数据中的 distinct_id 的值将和 anonymous_id 相同。

例如，用户登录后触发了一个页面浏览事件 “pageView”，此时的事件示例如下：

{
    "anonymous_id": "your_customized_anonymous_id",
    "distinct_id": "your_customer_id",
    "login_id": "your_customer_id",
    "event": "pageView",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV
        "$identity_login_id": "your_customer_id"  
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}

调用 logout（用户登出） 接口后，用户在当前设备上有进行了浏览，触发了 “SampleEvent” 事件，此时事件示例如下：

{
    "anonymous_id": "your_customized_anonymous_id",
    "distinct_id": "your_customized_anonymous_id",
    "event": "SampleEvent",
    "time": 1710407424977,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}

重置匿名 ID

调用时机

绝大多数场景下，您无需调用此接口。

仅当调用 更改匿名ID 接口为匿名 ID 进行赋值后，需要将匿名 ID 的取值恢复为神策 SDK 默认采集 / 生成的值时，可调用此接口实现。

使用准备

此接口并非常用接口，使用前请确保对接口的功能已有深入的了解。

接口说明

- (void)resetAnonymousId;

使用示例：

Objective-C

[[SensorsAnalyticsSDK sharedInstance] resetAnonymousId];

Swift

SensorsAnalyticsSDK.sharedInstance()?.resetAnonymousId()

[[SensorsAnalyticsSDK sharedInstance] resetAnonymousId];

SensorsAnalyticsSDK.sharedInstance()?.resetAnonymousId()

调用此接口后，SDK 会将匿名 ID 重置回 SDK 默认采集的值，在 iOS 侧，默认采集的匿名 ID 为 IDFV 的值。例如，我们已经将匿名 ID 修改为 “匿名 ID”，调用此接口之前的事件数据如下：

{
    "anonymous_id": "your_customized_anonymous_id",
    "distinct_id": "your_customized_anonymous_id",
    "event": "SampleEvent",
    "time": 1710407424987,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}

在调用此接口后，后续的事件数据示例如下：

{
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",   //SDK 默认采集的 IDFV 值
    "distinct_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "event": "SampleEvent",
    "time": 1710407424987,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",    //SDK 默认采集的匿名 ID，一般为 IDFV
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",             //SDK 默认采集的 IDFV 
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}