{"id":4,"type":"Article","title":"X-SDK 集成","slug":"web-sdk-intro","content":"WEB/H5/网站的 X-SDK ，是一串针对某个应用的 JavaScript 代码，你可以在创建完成一个应用或在应用设置的地方找到，在开始进行体验数据收集时，需要确保 X-SDK 已经成功集成到你的应用中。\r\n\r\n# STEP 1  应用 X-SDK 集成代码\r\n\r\n\r\n在创建完成一个应用后，或者在应用页面左侧的**「应用设置」**里，可以找到 X-SDK 的集成代码。\r\n\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1247/WeChatWorkScreenshot_6fc8be40-b74b-4464-b767-7de3d9fd5d80.png)\r\n\r\n**注意：该代码只可应用于所绑定的网址，在进行集成之前，请确认网址是否正确，如果想在本地或测试环境中调试，请参看[ SDK 测试及常见问题](https://howxm.com/help/articles/web-sdk-qa)。**\r\n\r\n**获取应用ID**\u003cbr\u003e\r\n\r\n创建应用后，如需获取当前应用的ID，可以在 **应用设置-网站设置** 中直接复制应用ID。\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1358/26.png)\r\n\r\n\r\n# STEP 2 复制集成代码进行集成\r\n\r\n\r\n点击复制按钮，复制 X-SDK 代码，并将其插入到对应产品网站的 HTML 代码的 \\\u003chead\u003e\\\u003c/head\u003e 中。\r\n\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1248/%E5%A4%8D%E5%88%B6.png)\r\n\r\n\r\n你可以自行完成X-SDK的代码集成，或者交由公司的研发人员进行处理。如果有任何疑问可以随时联系我们浩客团队的客户顾问为你解答。\r\n\r\n**注意：X-SDK 代码需要集成到所有想要对用户做体验数据收集的页面中，建议可以集成整个网站中。**\r\n\r\n\r\n# STEP 3 验证 X-SDK 集成是否生效\r\n\r\n\r\n在完成第二步代码集成后，你可以访问或页面刷新所集成 X-SDK 代码的网站，就可以看到 X-SDK 集成的状态变为\u003c绿色\u003e  ，点击会提示网站联通中，可以对评价、问卷进行正常投放。\r\n\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1530/%E8%81%94%E9%80%9A%E4%B8%AD.png)\r\n\r\n\r\n否则你将会看到**「未联通」**的红色提醒。\r\n\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1532/%E6%9C%AA%E8%81%94%E9%80%9A.png)\r\n\r\n\r\n需要检查代码是否正确安装，或者确认应用绑定的网址地址是否正确，检查协议号是否与网站一致（https/http）。如果想在本地或测试环境中调试，请参看 [SDK 测试及常见问题](https://howxm.com/help/articles/web-sdk-qa)。\r\n\r\n**注意：如果在72小时内，X-SDK没有收到来自目标网站的访问数据时，也会出现「网站未联通」的提醒，你可以再次刷新一下包含 X-SDK 代码的页面，状态即可恢复。**\r\n\r\n\r\n# STEP 4 X-SDK 集成成功\r\n\r\n\r\n如果 X-SDK 代码已经集成，你就可以开始使用浩客的评价、问卷、概览页等相关的能力，也建议你可以邀请团队成员加入到你的应用中，协作进行管理。\r\n\r\n[创建一个评价](https://howxm.com/help/articles/create-feedback)\r\n\r\n[创建一个问卷](https://howxm.com/help/articles/create-survey)\r\n\r\n[应用设置及团队协作](https://howxm.com/help/articles/apps-team)\r\n\r\n\r\n---\r\n\r\n# X-SDK 接口能力\r\n\r\n** X-SDK 的接口信息、参数、使用场景，请先查看  [接口文档](https://howxm.com/help/articles/x-sdk-api) \r\n\r\n如果想要进行用户身份验证、复杂的免打扰机制，可以查看这部分内容。请确保已经阅读并且理解 [X-SDK](https://howxm.com/help/articles/x-sdk-intro)的整体介绍。\r\n\r\n**在完成 X-SDK 集成后，可以使用相关的接口能力，完成更加复杂的场景，比如：**\u003cbr\u003e\r\n\r\n- 传入用户身份信息，实现复杂的免打扰机制，以及对于人群的定向投放\r\n\r\n- 传入扩展属性信息，用于对某些场景的识别，获得更加细分的数据洞察\r\n\r\n- 手动弹出评价/问卷，用于用户完成某些动作后的，精准投放等\r\n\r\n\r\n# **1. identify 用户身份信息传递**\r\n\r\n接口信息，详细可查看：[identify](https://howxm.com/help/articles/x-sdk-api#1-identify)\r\n\r\n```javascript\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    level: \"a\",\r\n    role: \"hr\"\r\n});\r\n```\r\n\r\n**错误情况：**\r\n\r\n如果在identity的时候，缺失uid，console中会有异常提示：Error: invalid argument\r\n\r\n# **2. event 抛出事件接口**\r\n\r\n接口信息，详细可查看：[event](https://howxm.com/help/articles/x-sdk-api#2-event)\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\r\n传入参数说明:\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n| 字段         | 说明     | 是否必填 | 类型        | 备注                      |\r\n|------------|--------|------|-----------|-------------------------|\r\n| event_code | 事件code | 必填   | String 类型 | 只能包含由数字、字母、下划线，且不能以数字开头 |\r\n\r\n\r\n# **3. checkOpen 弹出策略检查接口**\r\n\r\n接口信息，详细可查看：[checkOpen](https://howxm.com/help/articles/x-sdk-api#3-checkopen)\r\n\r\n```javascript\r\n_howxm('checkOpen', {\r\n  campaignId: '问卷/评价ID（必填）',  // 必填\r\n  uid: '当前用户的唯一ID（必填）', // 必填\r\n  onSuccess() {},\r\n  onFailed(data) {}, // {result: boolean; errMsg?: string}\r\n})\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**错误情况：**\u003cbr\u003e\r\n1. 传入不存在的campaignId，网络请求404\r\n\r\n\r\n# **4. open 弹出问卷接口**\r\n\r\n接口信息，详细可查看：[open](https://howxm.com/help/articles/x-sdk-api#4-open)\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  onCompleted(data) {}, // {success: boolean; errMsg?: string}\r\n})\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\r\n\r\n**customer 属性字段说明（选填）**\r\n\r\n用于记录填写问卷时的用户的信息，参数格式与 identify中的格式相同\r\n\r\n**extra 属性说明 （选填）**\r\n\r\n用于记录填写问卷时其他的自定义属性\r\n\r\n**错误情况：**\u003cbr\u003e\r\n1. 如果传入的campaignId不存在，console中会提示：{success: false, errMsg: 'campaign not found'}\r\n\r\n\r\n# **5. register 注册事件回调**\r\n通过此方法可注册全局回调事件，在问卷展示和回收过程的不同阶段进行自定义处理。调用方法如下：\r\n\r\n  ```\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回调阶段定义\r\n\r\n| 名称                            | 说明                                                       |\r\n|--------------------------|---------------------------------------------|\r\n| onBeforeOpen            | 问卷展示前调用                                    |\r\n| onOpen                      | 问卷展示后调用                                     |\r\n| onClose                      | 问卷在屏幕消失后调用                          |\r\n| onComplete               | 用户提交了最后一页题目后调用            |\r\n| onPageComplete       | 用户每提交一页，系统调用一次            |\r\n","featured":false,"category_id":3,"created_at":"2023-02-14T11:05:12.262Z","updated_at":"2025-08-18T09:22:17.055Z"}