X-SDK 集成

WEB/H5/网站的 X-SDK ,是一串针对某个应用的 JavaScript 代码,你可以在创建完成一个应用或在应用设置的地方找到,在开始进行体验数据收集时,需要确保 X-SDK 已经成功集成到你的应用中。

STEP 1 应用 X-SDK 集成代码

在创建完成一个应用后,或者在应用页面左侧的「应用设置」里,可以找到 X-SDK 的集成代码。

注意:该代码只可应用于所绑定的网址,在进行集成之前,请确认网址是否正确,如果想在本地或测试环境中调试,请参看 SDK 测试及常见问题

获取应用ID

创建应用后,如需获取当前应用的ID,可以在 应用设置-网站设置 中直接复制应用ID。

STEP 2 复制集成代码进行集成

点击复制按钮,复制 X-SDK 代码,并将其插入到对应产品网站的 HTML 代码的 <head></head> 中。

你可以自行完成X-SDK的代码集成,或者交由公司的研发人员进行处理。如果有任何疑问可以随时联系我们浩客团队的客户顾问为你解答。

注意:X-SDK 代码需要集成到所有想要对用户做体验数据收集的页面中,建议可以集成整个网站中。

STEP 3 验证 X-SDK 集成是否生效

在完成第二步代码集成后,你可以访问或页面刷新所集成 X-SDK 代码的网站,就可以看到 X-SDK 集成的状态变为<绿色> ,点击会提示网站联通中,可以对评价、问卷进行正常投放。

否则你将会看到「未联通」的红色提醒。

需要检查代码是否正确安装,或者确认应用绑定的网址地址是否正确,检查协议号是否与网站一致(https/http)。如果想在本地或测试环境中调试,请参看 SDK 测试及常见问题

注意:如果在72小时内,X-SDK没有收到来自目标网站的访问数据时,也会出现「网站未联通」的提醒,你可以再次刷新一下包含 X-SDK 代码的页面,状态即可恢复。

STEP 4 X-SDK 集成成功

如果 X-SDK 代码已经集成,你就可以开始使用浩客的评价、问卷、概览页等相关的能力,也建议你可以邀请团队成员加入到你的应用中,协作进行管理。

创建一个评价

创建一个问卷

应用设置及团队协作


X-SDK 接口能力

** X-SDK 的接口信息、参数、使用场景,请先查看 接口文档

如果想要进行用户身份验证、复杂的免打扰机制,可以查看这部分内容。请确保已经阅读并且理解 X-SDK的整体介绍。

在完成 X-SDK 集成后,可以使用相关的接口能力,完成更加复杂的场景,比如:

  • 传入用户身份信息,实现复杂的免打扰机制,以及对于人群的定向投放

  • 传入扩展属性信息,用于对某些场景的识别,获得更加细分的数据洞察

  • 手动弹出评价/问卷,用于用户完成某些动作后的,精准投放等

1. identify 用户身份信息传递

接口信息,详细可查看:identify

_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 类型
    level: "a",
    role: "hr"
});

错误情况:

如果在identity的时候,缺失uid,console中会有异常提示:Error: invalid argument

2. event 抛出事件接口

接口信息,详细可查看:event

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

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

传入参数说明:

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

3. checkOpen 弹出策略检查接口

接口信息,详细可查看:checkOpen

_howxm('checkOpen', {
  campaignId: '问卷/评价ID(必填)',  // 必填
  uid: '当前用户的唯一ID(必填)', // 必填
  onSuccess() {},
  onFailed(data) {}, // {result: boolean; errMsg?: string}
})

传入参数说明:

字段 说明 是否必填 类型 备注
campaignId 问卷/评价ID 必填 String 类型 某个问卷/评价ID,请从该问卷/评价的设置中获取
uid 用户id 必填 String 类型 用于识别唯一用户身份

错误情况:
1. 传入不存在的campaignId,网络请求404

4. open 弹出问卷接口

接口信息,详细可查看: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 属性说明 (选填)

用于记录填写问卷时其他的自定义属性

错误情况:
1. 如果传入的campaignId不存在,console中会提示:{success: false, errMsg: 'campaign not found'}

5. register 注册事件回调

通过此方法可注册全局回调事件,在问卷展示和回收过程的不同阶段进行自定义处理。调用方法如下:


_howxm('registerCallback', 'onBeforeOpen', function(campaignId, uid, attributes){
console.log('onBeforeOpen: ', campaignId, uid, attributes)
})


_howxm('registerCallback', 'onOpen', function(campaignId, uid, attributes){
console.log('onOpen: ', campaignId, uid, attributes)
})


_howxm('registerCallback', 'onClose', function(campaignId, uid){
console.log('onClose: ', campaignId, uid)
})


_howxm('registerCallback', 'onPageComplete', function(campaignId, uid,fieldsEntry){
console.log('onPageComplete: ', campaignId, uid, fieldsEntry)
})


_howxm('registerCallback', 'onComplete', function(campaignId, uid){
console.log('onComplete: ', campaignId, uid)
})

回调阶段定义

名称 说明
onBeforeOpen 问卷展示前调用
onOpen 问卷展示后调用
onClose 问卷在屏幕消失后调用
onComplete 用户提交了最后一页题目后调用
onPageComplete 用户每提交一页,系统调用一次