{"id":52,"type":"Article","title":"X-SDK 接口介绍","slug":"x-sdk-api","content":"# 接口介绍\r\n当完成 [WEB/H5/网站](https://howxm.com/help/articles/web-sdk-intro)、[ios](https://howxm.com/help/articles/ios-x-sdk) 、[Android](https://howxm.com/help/articles/x-sdk-andriod)、[小程序](https://howxm.com/help/articles/x-sdk-miniapp)的 X-SDK 的集成后，所有SDK都提供了如下的 API 接口，可以通过嵌入少量的代码，完成身份信息传递、事件触发、问卷投放、投放检测的能力。\r\n\r\n## **使用技巧**\u003cbr\u003e\r\n\r\n* **当面向已有用户或已登录用户进行问卷投放时，强烈建议您使用 identify 方法传递用户身份信息，这样在回收的数据、投放策略、免打扰机制上有更加灵活的配置，业务人员在浩客后台就可以进行相关的设定，而无需进行更多的代码调用。详细请查看[精准用户投放](https://howxm.com/help/articles/distribution-users)**。\r\n\r\n\r\n* **建议先使用浩客系统后台投放设置里的「[投放页面](https://howxm.com/help/articles/distribution-page-setting)」、「[投放时机](https://howxm.com/help/articles/distribution-timing-setting)」、「[事件触发](https://howxm.com/help/articles/distribution-evens-trigger)」、「[精准用户投放](https://howxm.com/help/articles/distribution-users)」、「[弹出策略](https://howxm.com/help/articles/distribution-strategy)」设置，无需研发介入，且业务人员可以灵活控制，无需进行更多的接口集成。若系统内配置无法满足投放需求时，可使用下面的 event、checkopen、open 等接口，再进行代码级别的弹出控制。**\r\n\r\n\r\n## **基本参数** \u003cbr\u003e\r\n\r\n在使用个过程中，您会经常遇到这么2个id信息，在此统一说明\r\n\r\n| 字段         | 说明   | 是否必填 | 类型        | 备注          |\r\n|:----------:|:----:|:----:|:---------:|:-----------:|\r\n| campaignId | 问卷/评价ID | 必填   | String 类型 | 某个问卷/评价ID，请从该问卷/评价的设置中获取 |\r\n| uid        | 用户id | 必填   | String 类型 | 用于传递的识别唯一用户身份，该信息将适用于投放、免打扰等机制  |\r\n\r\n如何获取问卷/评价ID？\r\n![](https://help-assets.jinshuju.net/assets/file/1378/%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E6%88%AA%E5%9B%BE_7df06739-ade6-4e41-931a-355d9493c2cf.png)\r\n\r\n\r\n\r\n# **1. identify 用户身份信息传递**\r\n该接口用于传递用户身份信息，传入身份信息后，[免打扰机制](https://howxm.com/help/articles/distribution-strategy)将基于用户 uid 作为唯一识别，同时在[投放规则](https://howxm.com/help/articles/distribution-users)里，将基于传入的身份信息做用户人群的精准投放。\u003cbr\u003e\r\n\r\n* **系统内更多维度的投放控制在身份传递后会有极大增强，强烈建议对于登录用户的反馈收集都调用此方法**\r\n* **建议在用户打开页面或页面切换时传递身份信息**\r\n* **该方法可多次调用。系统会根据使用最新调用的值覆盖同一个用户已存在的值。**\u003cbr\u003e\r\n* **同一个session内，如果24小时内重复调用且用户信息并没有变更的情况下，会忽略该请求**\u003cbr\u003e\r\n* **调用该方法并不会立即将用户身份信息写入数据库，而是写入服务端缓存中，如果3天内该用户有投放问卷才会将用户身份信息持久化到数据库中,  重复调用identify会重置缓存时间**\u003cbr\u003e\r\n\r\n\r\n\r\n## **接口名称**\r\n - **identify**\u003cbr\u003e\r\n\r\n## **接口示例（网站/H5）**\r\n以下以网站/H5的代码为例，在移动端和小程序中接口类似\u003cbr\u003e\r\n\r\n```javascript\r\n\r\n_howxm('identify', {\r\n    uid:  '00000001' , // 用户唯一ID, 默认字段, 必填，string 类型\r\n    name: 'howxm', // 名称，默认字段，非必填，string 类型\r\n    mobile: '15380000000', // 手机号，默认字段，非必填，string类型，会进行校验\r\n    email: 'demo@howxm.com', // 邮箱，默认字段，非必填，string类型，会进行校验\r\n\r\n    //以下字段为举例，可以进行自定义属性的传递\r\n    login_times: 14, // 登录次数，numeric 类型\r\n    last_visit_at: '2022-08-30T09:07:06.701Z', // 最近访问时间, date类型\r\n    plan:'basic', // 套餐, string 类型\r\n});\r\n```\r\n## **传入参数说明**\r\n\r\n| **字段** | **说明** | **是否必填** | **类型**    | **备注**             |\r\n|--------|--------|----------|-----------|--------------------|\r\n| uid    | 用户id ，用于识别唯一用户身份  | 必填       | String 类型 |   系统默认创建       |\r\n| name   | 姓名 ，可以传入用户昵称    | 选填       | String 类型 |    系统默认创建           |\r\n| mobile | 手机号 ，可以用户手机号，方便联系用户   | 选填       | String 类型 | 系统默认创建，会对手机号格式进行校验 |\r\n| email  | 邮箱 ，可以用户邮箱，方便联系用户    | 选填       | String 类型 | 系统默认创建，会对邮箱格式进行校验  |\r\n| plan  |    自定义的属性示例  | 选填       |   | 需要自己创建  |\r\n| login_times  |   自定义的属性示例  | 选填       |   | 需要自己创建  |\r\n| last_visit_at  |    自定义的属性示例  | 选填       |   | 需要自己创建  |\r\n\r\n- 系统内有4个默认字段信息：**uid**、姓名、手机号、邮箱；除了4个默认字段信息，也可以**传入自定义的属性信息**，方便做后续的数据分析，比如**用户等级、最近登陆时间、套餐类型、用户类别、标签**等诸多内容。\r\n\r\n- 目前字段属性信息目前支持3种类型：**string**字符串、**numeric**数字、**date** 日期。\r\n\r\n- **属性「key」定义：仅支持英文/数字，且需要以英文开头**，其中**date** 日期类型字段 key 值，需要以 **\\_at** 作为结尾，比如 last\\_visit\\_at , birthday\\_at , last\\_login\\_at 等。\r\n\r\n- **属性值定义**：可以传入字符串、数字、日期，其中**date**日期字段属性值以特定的UTC日期字符串格式传递，建议使用javascript的 toISOString 方法，参考如下：\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n| **格式**                 | **示例**                    | **转换后**              |\r\n|------------------------|---------------------------|----------------------|\r\n| YYYY-MM-DD             | 2022-08-24                | 2022-08-24T00:00:00Z |\r\n| YYYY-MM-DDThh:mm:ss    | 2022-08-24T01:52:45       | 2022-08-24T01:52:45Z |\r\n| YYYY-MM-DDTZD          | 2022-08-24+08:00          | 2022-08-23T16:00:00Z |\r\n| YYYY-MM-DDThh:mm:ssTZD | 2022-08-24T09:52:45+08:00 | 2022-08-24T01:52:45Z |\r\n\r\n---\r\n\r\n# **2. event 抛出事件接口**\r\n该接口用于基于事件触发的问卷投放，你可以在用户付费成功后、点击了某个按钮、完成了某个重大动作后，抛出 event 事件，同时也可将事件触发时的动态信息作为场景属性(attributes)传入。\r\n\r\n您可以设置问卷/反馈的弹出策略为接收到某个event事件后触发，详情查看  [事件触发](https://howxm.com/help/articles/distribution-evens-trigger) 。\r\n\r\n**注意：**由于 APP 应用没有像 WEB 、小程序应用有页面（page view）的概念，故在 APP 中均需使用事件触发的方式弹出问卷。事件触发后，同样会校验投放用户、页面、免打扰等机制，而实现精准的用户投放。\r\n\r\n## **接口名称**\r\n - **event**\u003cbr\u003e\r\n\r\n## **接口示例（网站/H5）**\r\n以下以网站/H5的代码为例，在移动端和小程序中接口类似。\u003cbr\u003e\r\n\r\n```javascript\r\n// 接口定义\r\n// _howxm('event', '\u003cevent_code\u003e', {\u003cattributes\u003e});\r\n\r\n// Example\r\n_howxm('event',            // 必填\r\n       'payment_clicked',  // 必填\r\n       {                   // 非必填\r\n          product: 'pro_plan',\r\n          price: 199\r\n       }\r\n);\r\n```\r\n## **传入参数说明:**\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n| **字段**     | **说明** | **是否必填** | **类型**    | **备注**                  |\r\n|------------|--------|----------|-----------|-------------------------|\r\n| event_code | 事件code | 必填       | String 类型 | 只能包含由数字、字母、下划线，且不能以数字开头 |\r\n| attributes | 事件场景属性 | 非必填 | Json 类型 | 事件触发时的动态属性信息 |\r\n\r\n事件场景属性 attributes，可用于事件触发时的属性校验，也可在数据页面的隐藏显示列中，看到用户所填写数据时的场景信息，比如示例中的：选择产品套餐类型、价格、模板信息等等。\r\n---\r\n# **3. checkOpen 弹出策略检查接口**\r\n\r\n当你选择使用代码内主动弹出问卷时，建议先进行 checkOpen 检查当前的投放是否符合弹出策略（免打扰机制），比如某个用户是否已经看过问卷或填写过问卷等等。弹出策略的系统内设置入口为：投放 -\u003e 弹出策略。\r\n\r\n\r\n## **接口名称**\r\n\r\n- **checkOpen**\r\n\r\n## **接口示例（网站/H5）**\r\n\r\n```javascript\r\n_howxm('checkOpen', {\r\n  campaignId: '问卷/评价ID（必填）',  // 必填\r\n  uid: '当前用户的唯一ID（必填）', // 必填\r\n  success() {},\r\n  failed(data) {}, // {result: boolean; errMsg?: string}\r\n})\r\n```\r\n## **传入参数说明:**\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n| **字段**     | **说明** | **是否必填** | **类型**    | **备注**      |\r\n|------------|--------|----------|-----------|-------------|\r\n| campaignId | 问卷/评价ID   | 必填       | String 类型 | 某个问卷/评价ID，请从该问卷/评价的设置中获取 |\r\n| uid        | 用户id   | 必填       | String 类型 | 用于识别唯一用户身份  |\r\n\r\n---\r\n# **4. open 弹出问卷接口**\r\n\r\n您可以直接调用 open 方法来显示弹出某个问卷，该方法将会绕过所有投放规则和弹出策略，建议您在调用该方法时，先进行 checkOpen 检查弹出策略是否满足。\u003cbr\u003e\r\n\r\n## **接口名称**\r\n- **open**\r\n\r\n## **接口示例（网站/H5）**\r\n以下以网站/H5的代码为例，在移动端和小程序中接口类似。\u003cbr\u003e\r\n\r\n```javascript\r\n_howxm('open', {\r\n  campaignId: '问卷/评价ID ',  // 必填\r\n  // 手动触发时可以传入当前的用户信息，选填\r\n  customer: { // 非必填\r\n    uid:  '00000001' , // 用户唯一ID, 默认字段, 必填，string 类型\r\n    name: 'howxm', // 名称，默认字段，非必填，string 类型\r\n    mobile: '15380000000', // 手机号，默认字段，非必填，string类型，会进行校验\r\n    email: 'demo@howxm.com', // 邮箱，默认字段，非必填，string类型，会进行校验\r\n  },\r\n  // 非必填\r\n  extra: {\r\n    // 其他属性\r\n  },\r\n  completed(data) {}, // {success: boolean; errMsg?: string}\r\n})\r\n```\r\n## **传入参数说明:**\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n| **字段**     | **说明** | **是否必填** | **类型**    | **备注**      |\r\n|------------|--------|----------|-----------|-------------|\r\n| campaignId | 问卷/评价ID    | 必填       | String 类型 | 某个问卷/评价ID，请从该问卷/评价的设置中获取 |\r\n\u003cbr\u003e\r\ncustomer  属性字段说明（*选填*）\u003cbr\u003e\r\n用于记录填写问卷时的用户的信息，参数格式与 [identify中的格式](https://howxm.com/help/articles/x-sdk-api)相同\u003cbr\u003e\r\n\r\nextra 属性说明 （*选填*）\u003cbr\u003e\r\n用于记录填写问卷时其他的自定义属性\u003cbr\u003e\r\n\r\n\r\n# **5. register 注册事件回调**\r\n\r\n您可以注册全局的回调事件，在问卷展示和回收的不同过程阶段，进行自定义处理。\r\n\r\n## **接口名称**\r\n- **registerCallback**\r\n\r\n## **接口示例（网站/H5）**\r\n\r\n  ```javascript\r\n\r\n_howxm('registerCallback', 'onBeforeOpen', function(campaignId, uid, attributes){\r\nconsole.log('onBeforeOpen: ', campaignId, uid, attributes)\r\n})\r\n\t\r\n\t\r\n_howxm('registerCallback', 'onOpen', function(campaignId, uid, attributes){\r\nconsole.log('onOpen: ', campaignId, uid, attributes)\r\n})\r\n\t\r\n\t\r\n_howxm('registerCallback', 'onClose', function(campaignId, uid){\r\nconsole.log('onClose: ', campaignId, uid)\r\n})\r\n\r\n\r\n_howxm('registerCallback', 'onPageComplete', function(campaignId, uid,fieldsEntry){\r\nconsole.log('onPageComplete: ', campaignId, uid, fieldsEntry)\r\n})\r\n\r\n\r\n_howxm('registerCallback', 'onComplete', function(campaignId, uid){\r\nconsole.log('onComplete: ', campaignId, uid)\r\n})\r\n  ```\r\n\r\n## **传入参数说明:**\u003cbr\u003e\r\n\r\n### 回调阶段定义\r\n\r\n| 名称                            | 说明                                                       |\r\n|--------------------------|---------------------------------------------|\r\n| onBeforeOpen            | 问卷展示前调用                                    |\r\n| onOpen                      | 问卷展示后调用                                     |\r\n| onClose                      | 问卷在屏幕消失后调用                          |\r\n| onComplete               | 用户提交了最后一页题目后调用            |\r\n| onPageComplete       | 用户每提交一页，系统调用一次            |\r\n\r\n\r\n### 参数说明\r\n\r\n| 名称                            | 说明                                                       |\r\n|--------------------------|---------------------------------------------|\r\n| campaignId            | 问卷/评价的ID                                    |\r\n| uid                      | 所传入的当前用户 uid                                     |\r\n| attributes                      | 传入的属性信息                          |\r\n| fieldsEntry               | 用户所填写的数据信息            |\r\n","featured":false,"category_id":2,"created_at":"2023-02-17T02:22:50.267Z","updated_at":"2025-03-04T08:17:29.595Z"}