1. 介绍

相较于简易用户关联模式只能使用 2 个业务 ID 参与用户关联,在此模式下,若您的实际业务与场景需要区别多个用户业务 ID 的实际语义,则可通过自定义业务 ID 并赋值上传参与用户关联。

2. 接口介绍

2.1. 更改匿名 ID

2.1.1. 调用时机

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

在 微信小程序下,匿名 ID 的取值一般为 UUID。若您需要自定义匿名 ID 的值,则可通过调用此接口来实现。

2.1.2. 使用准备

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

2.1.3. 接口说明

使用示例:

sensors.identify('your_customized_anonymous_id');
JS

版本

微信小程序 SDK 版本 >= 1.20.3

低版本需要使用  sensors.identify('your_customized_anonymous_id', true);

调用此接口后,神策 SDK 将会修改事件上报数据中的 “anonymous_id”、“$identity_anonymous_id” 的值。

若在未调用 用户登录 接口前,即还未对 “login_id” 和 “$identity_login_id” 赋值时(一般称这类用户为匿名状态用户)。SDK 还会同步修改 “distinct_id” 的值。

例如,调用此接口前,一个处于匿名状态的用户触发了页面浏览事件($MPViewScreen),则事件上报数据示例如下:

{
  anonymous_id: "1712042794795-4430041-097b46dd83f7da8-29832842",          //匿名 ID 默认是 UUID   
  distinct_id: "1712042794795-4430041-097b46dd83f7da8-29832842",           //神策用户标识 distinct_id,在匿名状态下就是匿名 ID
  identities: {
    $identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842",      //微信小程序默认采集的 UUID
    $identity_anonymous_id: "1712042794795-4430041-097b46dd83f7da8-29832842"   //匿名 ID 默认是 UUID   
  },
  event: "$MPViewScreen", 
  properties: {
    $referrer: "直接打开", 
    $referrer_title: "", 
    $title: "", 
    $url_path: "pages/index/index"
  },
  type: "track"
 }
JS

若此时,调用 更改匿名 ID 接口传入一个自定义的匿名 ID 值,例如 “your_customized_anonymous_id” ,则后续发生的事件 $MPViewScreen 数据中的匿名 ID 都会更改,事件上报数据示例如下:

{
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id", 
  identities: { 
    $identity_anonymous_id: "your_customized_anonymous_id",
    $identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842"
  },  
  event: "$MPViewScreen",  
  properties: {
    $referrer: "直接打开", 
    $referrer_title: "", 
    $title: "", 
    $url_path: "pages/index/index"
  },
  type: "track"
}
JS

2.2. 用户登录

2.2.1. 调用时机

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

2.2.2. 使用准备

  • 登录 ID 在神策的用户关联体系中非常重要,因此,强烈建议您在用户发生注册或登录时调用此接口来记录用户的 登录 ID。
  • 登录 ID ,一般当用户注册后,由您的业务系统自动生成,用于标识用户在业务中的唯一身份,通常是一个持久的、不可变的 ID。绝大多数的情况下,企业用户系统中的注册 ID、Passport ID、会员 ID 等都会是一个很好的选择,注意一般情况下不要选择手机号这种可变信息作为登录 ID。

2.2.3. 接口说明

使用示例:

sensors.login('your_customer_id');
JS

调用 用户登录 接口后,神策 SDK 会触发神策系统预置的 “$SignUp” 事件,事件数据中会带有 “login_id” 和 “$identity_login_id”。且 “distinct_id” 的值修将被改为传入的登录 ID。

与此同时,神策 SDK 会将 “login_id” 和 “$identity_login_id” 的信息缓存在当前微信小程序 storage 中。这样后续当前小程序上触发的所有事件中都会带有 “login_id” 和 “$identity_login_id” 信息。

例如,在调用 login(用户登录) 接口前,用户在当前小程序上触发的一个页面浏览事件($MPViewScreen)时,事件上报信息示例如下:

{
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",   
  identities: { 
    $identity_anonymous_id: "your_customized_anonymous_id",
    $identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842"
  },
  event: "$MPViewScreen",  
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
}
JS

调用 login(用户登录) 接口后,神策 SDK 会自动触发神策预置的 $SignUp 事件,记录了用户登录 ID 和其他 业务 ID 的信息。事件上报信息示例如下:

{
  anonymous_id: "your_customized_anonymous_id",  
  distinct_id: "your_customer_id",  
  login_id: "your_customer_id",      // 登录 ID
  original_id: "your_customized_anonymous_id", 
  identities: {
	$identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842",
	$identity_login_id: "your_customer_id",  // 登录 ID
 	$identity_anonymous_id: "your_customized_anonymous_id"
  },   
  event: "$SignUp",     
  properties: {
    $referrer: "直接打开"
  },  
  type: "track_signup"
}
JS

如前文所诉,神策 SDK 将在当前微信小程序 storage 缓存 “$identity_login_id” 的信息。因此 后续在此小程序上触发的所有事件都会带上 “$identity_login_id” 的信息。

若此时用户在当前小程序上手动触发了一个事件(buttonClick),则事件数据示例如下:

{     
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customer_id",
  login_id: "your_customer_id", 
  identities: {
    $identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842",
    $identity_login_id: "your_customer_id", 
    $identity_anonymous_id: "your_customized_anonymous_id"
  },
  event: "buttonClick",    
  properties: {
    $referrer: "直接打开"
  }, 
  type: "track"
}
JS

2.3. 绑定业务 ID

2.3.1. 调用时机

该接口用于为您自定义的业务 ID 进行赋值。当得您的系统获取到或用户填写了对应业务 ID 的值时,您可通过调用此接口,将对应业务 ID 的值传入。

例如,业务需要使用用户的邮箱进行用户关联。则可在用户完成邮箱验证后,通过调用此接口,将邮箱信息传入 $identity_email 中。

2.3.2. 使用准备

  • 使用该接口前,请确保您对于神策的接口与用户关联概念有深入的了解。
  • 神策系统中的字段遵循先声明后上报的规则。因此,若您需要使用自定义业务 ID 进行用户关联时,请确保您已在神策系统中完成了您所需的业务 ID 的定义。

2.3.3. 标准接口说明 bind

使用示例:

sensors.bind("$identity_mobile","187****8991");
JS

调用 绑定业务 ID 接口后,神策 SDK 会触发神策预置的 “$BindID” 事件,并在该事件数据中记录接口调用时传入的业务 ID 的信息。同时 神策 SDK 会将接口中传入的业务 ID 信息缓存到当前小程序 storage,后续触发的所有事件都将携带此业务 ID 相关信息。

例如,调用 bind(绑定业务 ID) 接口前,用户触发了一个按钮点击事件(buttonClick)时,事件示例数据如下:

{     
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customer_id",
  login_id: "your_customer_id",    
  event: "buttonClick",
  identities: {
    $identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842",
    $identity_login_id: "your_customer_id",   
    $identity_anonymous_id: "your_customized_anonymous_id"
  },    
  event: "buttonClick",
  properties: {$referrer: "直接打开"}, 
  type: "track" 
 }
JS

此时,调用 bind(绑定业务 ID) 接口,会触发神策预置的 “$BindID” 事件,事件信息中会记录接口中传入的业务 ID 的相关信息,事件数据信息示例如下:

{    
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customer_id",
  login_id: "your_customer_id", 
  identities: {
    $identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842",
    $identity_login_id: "your_customer_id",
    $identity_mobile: "187****8991",      // bind 传入的 ID
    $identity_anonymous_id: "your_customized_anonymous_id"
  },
  event: "$BindID",    
  properties: {
    $referrer: "直接打开"
  },
  type: "track_id_bind"
}
JS

如前文所述,神策 SDK 会在 bind (绑定业务 ID) 接口被调用后,将接口中的业务 ID 信息缓存在本地,这样续触发的所有事件都会带上此次接口携带的业务 ID 信息。

例如,此时用户又在当前小程序上触发了一个页面浏览事件($MPViewScreen),则事件数据示例如下:

{        
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customer_id",
  login_id: "your_customer_id", 
  event: "$MPViewScreen",
  identities: {      
    $identity_mp_id: "1712042794795-4430041-097b46dd83f7da8-29832842",
    $identity_login_id: "your_customer_id",
    $identity_mobile: "187****8991", 
    $identity_anonymous_id: "your_customized_anonymous_id"    
  },
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
}
JS

2.3.4. 快捷接口 bindOpenid

使用示例:

sensors.bindOpenid("openid-xxx");
JS

如果想要绑定微信的 OpenID,可以直接通过上面的 bind('openid','openid-xx') 的形式自定义来实现,此时如果有多个微信小程序的时候,你可能无法区分 openid 这个 key 是哪个微信小程序的。

此时使用 SDK 提供的 bindOpenid 方法会把小程序的 AppID 和 OpenID 组合在一起成为一个新的 key 名。

在没有调用 bindOpenid 接口前,假设有页面浏览事件($MPViewScreen)如下:

{          
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",   
  identities: {       
    $identity_anonymous_id: "your_customized_anonymous_id",
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623"
  },
  event: "$MPViewScreen",   
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
 }
JS

在调用 bindOpenid 接口后,仍然跟 bind 一样会发送 $BindID 事件,着重看下此时的 key 是 $identity_mp_wxe02ae7c2f21d1006_openid: 

{        
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",   
  identities: {       
    $identity_anonymous_id: "your_customized_anonymous_id",
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623",
    $identity_mp_wxe02ae7c2f21d1006_openid: "openid-xxx"
  },
  event: "$BindID", 
  properties: {
    $referrer: "直接打开"
  },    
  type: "track_id_bind"
}
JS

这里的 $identity_mp_openid 是固定的预置的 key,wxe02ae7c2f21d1006 是当前小程序的 AppID。通过这个组合可以实现区分是哪个小程序的 OpenID。

此时如果再触发一条页面浏览事件

{          
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",   
  identities: {       
    $identity_anonymous_id: "your_customized_anonymous_id",
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623",
    $identity_mp_wxe02ae7c2f21d1006_openid: "openid-xxx" 
  },
  event: "$MPViewScreen",    
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
}
JS

2.4. 解绑业务 ID

2.4.1. 调用时机

解绑接口可将指定的业务 ID 下的值从对应的用户属性中移除。一般可在用户已有业务 ID 值不再使用,且需要更换时使用。比如更换绑定的手机号或邮箱账号。

需要注意的是此接口为高阶能力,且 对于性能影响较大 ,强烈建议您在使用前认真细阅使用准备章节中的内容。

2.4.2. 使用准备

  • 使用该接口前,请确保您对于神策的接口与用户关联概念有深入的了解。
  • 该接口能力,仅在动态可变关联策略下可用。您可进入神策系统,数据接入 → 用户表 → 配置用户关联 页面查看您当前正在使用的用户关联策略。
  • 该接口 对于性能有着非常大的影响,且 高度依赖解绑事件的上报时序,故在一些极端情况下,会发生数据不及预期的情况,故在使用该接口前建议同神策工作人员进行详细评估。

2.4.3. 标准接口 unbind

使用示例:

sensors.unbind("$identity_mobile","187****8991");
JS

调用 unbind(解绑业务 ID) 接口后,神策 SDK 会触发神策预置的 “$UnbindID” 事件,事件中将记录 解绑业务 ID 接口中所传入的业务 ID 相关信息。同时神策 SDK 会将本地缓存中对应的业务 ID 信息删除,后续触发的事件数据中将不再带有相应的业务 ID 信息。

例如,调用此接口前,有 $MPViewScreen 的事件示例数据如下:

{        
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",
  identities: {
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623", 
    $identity_mobile: "187****8991", 
    $identity_anonymous_id: "your_customized_anonymous_id"
  },
  event: "$MPViewScreen", 
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
}
JS

此时调用 unbind(解绑业务 ID) 接口后,会触发神策预置的 “$UnbindID” 事件,事件中将带有 解绑业务 ID 接口中所传入的业务 ID 相关信息,神策系统解绑该预置事件后,将按照事件信息,把对应业务 ID 值从相关用户的用户图谱中移除。事件数据示例如下:

{
  anonymous_id: "your_customized_anonymous_id",      
  distinct_id: "your_customized_anonymous_id",
  event: "$UnbindID",
  identities: {
    $identity_mobile: "187****8991"
  },
  properties: {
    $referrer: "直接打开"
  },
  type: "track_id_unbind"
}
JS

如前文所述,神策 SDK 会在 unbind(解绑业务 ID) 接口被调用后,会将本地缓存中对应的业务 ID 信息删除。从而后续用户在此小程序上再触发的所有事件将不再带有调用 unbind(解绑业务 ID) 时传入的业务 ID 信息,

例如,紧接着上文调用完 unbind(解绑业务 ID) 接口后,若此时用户在当前小程序触发了页面浏览事件($MPViewScreen),则事件的示例数据如下:

{        
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",
  identities: {
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623", 
    $identity_anonymous_id: "your_customized_anonymous_id"
  },
  event: "$MPViewScreen", 
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
}
JS

2.4.4. 快捷接口 unbindOpenid

使用示例:

sensors.unbindOpenid("openid-xx")
JS

通过 unbindOpenid 解绑 OpenID,unbindOpenid 跟 unbind 的唯一区别在于:

  • unbindOpenid 会拼接出 bindOpenid 中的 key (类似 $identity_mp_wxe02ae7c2f21d1006_openid )

假设我们调用过 bindOpenid 此时的数据如下:

{          
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",   
  identities: {       
    $identity_anonymous_id: "your_customized_anonymous_id",
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623",
    $identity_mp_wxe02ae7c2f21d1006_openid: "openid-xxx" 
  },
  event: "$MPViewScreen", 
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
}
JS

下面是调用 unbindOpenid 之后的数据示例:

{   
  anonymous_id: "your_customized_anonymous_id",   
  distinct_id: "your_customized_anonymous_id",    
  identities: {
    $identity_mp_wxe02ae7c2f21d1006_openid: "openid-xx"
  }, 
  event: "$UnbindID",
  properties: {
    $referrer: "直接打开"
  },
  type: "track_id_unbind"
}
JS

此时再触发一条页面浏览事件,就不会再有 $identity_mp_wxe02ae7c2f21d1006_openid

{          
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",       
  identities: {       
    $identity_anonymous_id: "your_customized_anonymous_id",
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623"
  }, 
  event: "$MPViewScreen",
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
}
JS

2.5. 用户登出

2.5.1. 调用时机

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

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

2.5.2. 使用准备

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

2.5.3. 接口说明

使用示例:

sensors.logout();
JS

调用 用户登出 接口后,神策 SDK 会将缓存在当前小程序中的 “login_id” 、 “$identity_login_id” 及绑定的其他业务 ID 信息删除,且不会触发任何神策系统的预置事件。直到再次调用 用户登录 绑定业务 ID 接口前,用户在当前小程序上所触发的事件,在上报时将不再带有 “login_id”、“$identity_login_id” 及其他绑定的业务 ID 信息。

例如,一个登录后的用户触发了页面浏览事件 “$MPViewScreen”,则此时的事件数据示例如下:

{        
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customer_id",
  login_id: "your_customer_id"
  identities: {
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623", 
    $identity_login_id: "your_customer_id",
    $identity_anonymous_id: "your_customized_anonymous_id"
  },
  event: "$MPViewScreen", 
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
 }
JS

在调用 用户登出 接口,神策 SDK 会将缓存在本地的 “login_id” 、 “$identity_login_id” 信息清除。

若此时,用户在当前小程序上有进行了浏览,触发了 “$MPViewScreen” 事件,则事件数据示例如下:

{        
  anonymous_id: "your_customized_anonymous_id",
  distinct_id: "your_customized_anonymous_id",
  identities: {
    $identity_mp_id: "1712486830686-127572-0ddb5b17ab28868-11762623", 
    $identity_anonymous_id: "your_customized_anonymous_id"
  },
  event: "$MPViewScreen", 
  properties: {
    $referrer: "直接打开"
  },
  type: "track"
 }
JS

2.6. 重新设置匿名 ID

2.6.1. 调用时机

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

此接口一般配合 退出登录 接口使用,旨在当小程序上有多个不同用户登录时,实现用户 A 退出登录后所触发的事件都归属于后面登录的账号 B。

2.6.2. 使用准备

  • 此接口并非常用接口,使用前请确保对接口的功能已有深入的了解。
  • 微信小程序 SDK 版本号 >= v1.20.2。
  • 当前用户需要在匿名(登出)状态下,即未调用 用户登录 接口前,或调用 用户登出 接口后。如果当前用户在登录状态下,调用此接口没有任何作用。

2.6.3. 接口说明

使用示例:

// 重置匿名 ID
sensors.resetAnonymousIdentity();

// 修改为指定的匿名 ID
sensors.resetAnonymousIdentity('id-xxxxxxx-xxxxx');
JS

在用户匿名状态下调用此接口后,神策 SDK 会将 “anonymous_id”、“distinct_id”、“$identity_anonymous_id”、“$identity_mp_id” 修改为接口调用时传入的值(如果不传,神策 SDK 内部会自动生成一个 UUID 的值来设置)。

例如,我们原先的匿名 ID 是  “id_xx1”,调用 重新设置匿名 ID 接口之前的事件数据如下:

{
  anonymous_id: "your_customized_anonymous_id", 
  distinct_id: "your_customized_anonymous_id",
  identities: {
    $identity_cookie_id: "18e84a8be997ff-00eab826c4cb1d48-1c525637-1296000-18e84a8be9aa30",
    $identity_anonymous_id: "your_customized_anonymous_id"
  },
  event": "$MPViewScreen", 
  properties": {
    "$timezone_offset": -480
  },
  type: "track"
}
JS

此时,调用 重新设置匿名 ID 接口 sensors.resetAnonymousIdentity(“your_new_anonymous_id”)。然后触发新的事件($MPViewScreen)时,事件数据示例如下:

{
  anonymous_id: "your_new_anonymous_id", 
  distinct_id: "your_new_anonymous_id",
  identities: {
    $identity_cookie_id: "your_new_anonymous_id",
    $identity_anonymous_id: "your_new_anonymous_id"
  },
  event: "$MPViewScreen", 
  properties: {
    "$timezone_offset": -480
  },
  type: "track"
}
JS