X-SDK 接口集成

接口介绍

X-SDK内的所有SDK都提供以下两类接口,可以通过嵌入少量的代码,完成客户端系统与浩客系统的数据传递。

用户身份信息传递(推荐使用)

该接口用于传递用户身份信息,传入身份信息后,免打扰机制将基于用户 uid 作为唯一识别,同时在投放规则里,将基于传入的身份信息做用户人群的精准投放。

  • 系统内更多维度的数据分析、投放控制在用户身份传递后会有极大增强,强烈建议对于登录用户的反馈收集都调用此方法
  • 建议在用户打开页面或页面切换时传递身份信息
  • 该方法不会产生副作用,可多次调用。系统会根据使用最新调用的值覆盖同一个客户已存在的值。

接口名称

  • identify

接口示例(网站/H5)

以下以网站/H5的代码为例,在移动端和小程序中接口类似


_howxm('identify', {
    uid:  '00000001' , // 用户唯一ID, 默认字段, 必填,string 类型
    name: 'howxm', // 名称,默认字段,非必填,string 类型
    mobile: '15380000000', // 手机号,默认字段,非必填,string类型,会进行校验
    email: 'demo@howxm.com', // 邮箱,默认字段,非必填,string类型,会进行校验

    //以下字段为举例,可以进行自定义属性的传递
    login_times: 14, // 登录次数,numeric 类型
    last_visit_at: '2022-08-30T09:07:06.701Z', // 最近访问时间, date类型
    plan:'basic', // 套餐, string 类型
});

参数说明

系统内有4个默认字段信息:

字段 说明 是否必填 类型 备注
uid 用户id 必填 String 类型 用于识别唯一用户身份
name 姓名 选填 String 类型 用户的昵称
mobile 手机号 选填 String 类型 方便联系用户,会对手机号格式进行校验
email 邮箱 选填 String 类型 方便联系用户,会对邮箱格式进行校验

传入自定义的属性信息:
可以传入用户的更加丰富的属性信息,方便做后续的数据分析,比如用户等级、最近登陆时间、套餐类型、用户类别、标签等诸多内容。

目前字段属性信息目前支持3种类型:string字符串、numeric数字、date 日期。 date 日期类型字段 key 值,需要以 _at 作为结尾,比如 last_visit_at , birthday_at , last_login_at 等。 date日期字段属性值以特定的UTC日期字符串格式传递,建议使用javascript的 toISOString 方法,参考如下:

格式 示例 转换后
YYYY-MM-DD 2022-08-24 2022-08-24T00:00:00Z
YYYY-MM-DDThh:mm:ss 2022-08-24T01:52:45 2022-08-24T01:52:45Z
YYYY-MM-DDTZD 2022-08-24+08:00 2022-08-23T16:00:00Z
YYYY-MM-DDThh:mm:ssTZD 2022-08-24T09:52:45+08:00 2022-08-24T01:52:45Z

问卷弹出(高级控制)

X-SDK提供了三种方式来展示问卷,业务人员可通过在浩客后台的配置来自动控制,通常无需研发多次配合。

  • 自动弹出(仅网站/H5支持) 根据用户访问的页面,结合用户的属性与规则的匹配度,进行自动弹出控制。绝大部分情况下使用此方式,研发无需二次开发
  • 事件弹出 用于针对特殊的用户事件进行弹出。例如付费成功,套餐到期等。业务人员可梳理清楚重要事件后,由研发人员一次性嵌入,此后无需再次开发
  • 人工弹出(不推荐) 特殊情况下,研发可通过调用X-SDK提供的open方法来弹出问卷。一般是业务场景固定且不再变化的情况,此方法会忽略所有免打扰机制而立刻弹出,且需要研发人员进行编码调用

接口名称

  • event 用于向浩客发送事件,并且使用事件触发投放的能力。详见 事件触发
  • open(不推荐) 如果您希望根据某些客户行为,手动触发投放来显示问卷组件,可以使用 open 方法,此方法可以绕过所有投放规则以及免打扰限制,另外业务需求变化时,需要研发重新编码部署。
  • checkOpen(不推荐) 基于用户uid和免打扰策略来判断,是否需要给用户弹框显示问卷组件。在调用open方法前,建议调用checkOpen进行免打扰检测后,感觉返回结果判断是否调用。

接口示例(网站/H5)

以下以网站/H5的代码为例,在移动端和小程序中接口类似。

event

// 接口定义
// _howxm('event', '<event_code>', {<attributes>});

// Example
_howxm('event',            // 必填
       'payment_clicked',  // 必填
       {                   // 非必填
          product: 'pro_plan',
          price: 199
       }
);

传入参数说明:

字段 说明 是否必填 类型 备注
event_code 事件code 必填 String 类型 只能包含由数字、字母、下划线,且不能以数字开头

open

_howxm('open', {
  campaignId: '投放ID',  // 必填
  // 手动触发时可以传入当前的用户信息,选填
  customer: { // 非必填
    uid:  '00000001' , // 用户唯一ID, 默认字段, 必填,string 类型
    name: 'howxm', // 名称,默认字段,非必填,string 类型
    mobile: '15380000000', // 手机号,默认字段,非必填,string类型,会进行校验
    email: 'demo@howxm.com', // 邮箱,默认字段,非必填,string类型,会进行校验
  },
  // 非必填
  extra: {
    // 其他属性
  },
  completed(data) {}, // {success: boolean; errMsg?: string}
})

传入参数说明:

字段 说明 是否必填 类型 备注
campaignId 投放Id 必填 String 类型 问卷组件对应的投放Id


customer 属性字段说明(选填
用于记录填写问卷时的用户的信息,参数格式与 identify中的格式相同

extra 属性说明 (选填
用于记录填写问卷时其他的自定义属性

checkOpen

_howxm('checkOpen', {
  campaignId: '投放ID(必填)',  // 必填
  uid: '当前用户的唯一ID(必填)', // 必填
  success() {},
  failed(data) {}, // {result: boolean; errMsg?: string}
})

传入参数说明:

字段 说明 是否必填 类型 备注
campaignId 投放Id 必填 String 类型 问卷组件对应的投放Id
uid 用户id 必填 String 类型 用于识别唯一用户身份