接口介绍

当完成 WEB/H5/网站、ios 、Android、小程序的 X-SDK 的集成后，所有SDK都提供了如下的 API 接口，可以通过嵌入少量的代码，完成身份信息传递、事件触发、问卷投放、投放检测的能力。

使用技巧

• 当面向已有用户或已登录用户进行问卷投放时，强烈建议您使用 identify 方法传递用户身份信息，这样在回收的数据、投放策略、免打扰机制上有更加灵活的配置，业务人员在浩客后台就可以进行相关的设定，而无需进行更多的代码调用。详细请查看精准用户投放。

• 建议先使用浩客系统后台投放设置里的「投放页面」、「投放时机」、「事件触发」、「精准用户投放」、「弹出策略」设置，无需研发介入，且业务人员可以灵活控制，无需进行更多的接口集成。若系统内配置无法满足投放需求时，可使用下面的 event、checkopen、open 等接口，再进行代码级别的弹出控制。

基本参数

在使用个过程中，您会经常遇到这么2个id信息，在此统一说明

如何获取问卷/评价ID？

1. identify 用户身份信息传递

该接口用于传递用户身份信息，传入身份信息后，免打扰机制将基于用户 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、姓名、手机号、邮箱；除了4个默认字段信息，也可以传入自定义的属性信息，方便做后续的数据分析，比如用户等级、最近登陆时间、套餐类型、用户类别、标签等诸多内容。

• 目前字段属性信息目前支持3种类型：string字符串、numeric数字、date 日期。

• 属性「key」定义：仅支持英文/数字，且需要以英文开头，其中date 日期类型字段 key 值，需要以 _at 作为结尾，比如 last_visit_at , birthday_at , last_login_at 等。

• 属性值定义：可以传入字符串、数字、日期，其中date日期字段属性值以特定的UTC日期字符串格式传递，建议使用javascript的 toISOString 方法，参考如下：
  
  

2. event 抛出事件接口

该接口用于基于事件触发的问卷投放，你可以在用户付费成功后、点击了某个按钮、完成了某个重大动作后，抛出 event 事件。您可以设置问卷/反馈的弹出策略为接收到某个event事件后触发，详情查看 事件触发

接口名称

• event
  

接口示例（网站/H5）

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

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

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

传入参数说明:

3. checkOpen 弹出策略检查接口

当你选择使用代码内主动弹出问卷时，建议先进行 checkOpen 检查当前的投放是否符合弹出策略（免打扰机制），比如某个用户是否已经看过问卷或填写过问卷等等。弹出策略的系统内设置入口为：投放 -> 弹出策略。

接口名称

• checkOpen

接口示例（网站/H5）

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

传入参数说明:

4. open 弹出问卷接口

您可以直接调用 open 方法来显示弹出某个问卷，该方法将会绕过所有投放规则和弹出策略，建议您在调用该方法时，先进行 checkOpen 检查弹出策略是否满足。

接口名称

• open

接口示例（网站/H5）

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

_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}
})

传入参数说明:

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

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