{"id":34,"type":"Article","title":"X-SDK 小程序集成","slug":"x-sdk-miniapp","content":"👏🏻👏🏻小程序集成X-SDK采用标准插件方式，插件已经在微信官方发布上线，搜索添加后可直接使用。\r\n\r\n小程序 X-SDK 同样支持小程序path路径的方式，进行页面级别的问卷投放，详细查看：[投放页面设置](https://howxm.com/help/articles/distribution-page-setting#part-b634ffd8a92c4b14)\r\n\r\n小程序 X-SDK 支持原生小程序应用，也支持使用 uni-app 框架开发的小程序，请放心使用。\r\n\r\n我们在 github 上放置了浩客的集成 demo repo 代码库，[可以进行查看](https://github.com/howxm). \u003cbr\u003e\r\n\r\n\r\n| 最新版本号 | 描述 | 发布时间 |\r\n| -------- | -------- | -------- |\r\n| 2.1.0    | 字段说明支持富文本| 2025-06-25 |\r\n| 2.0.10    | 优化identify逻辑，重复调用identify在用户信息有变化或距上次调用超过24小时生效| 2025-03-05 |\r\n| 2.0.9    |  修复问卷中评价字段样式与预览不一致 | 2024-05-20 |\r\n| 2.0.8    | 多选题支持做多选 N 项，最少选 N 项 | 2024-03-27 |\r\n| 2.0.7    | 单选字段也只支持选项横向标签展示 | 2024-03-06 |\r\n| 2.0.6    | 数据详情里增加用户的屏幕分辨率 | 2024-02-29 |\r\n| 2.0.5    | 问卷-所有题目支持设置头图 | 2024-01-04 |\r\n| 2.0.4    | 问卷-CTA题目支持设置按钮位置 | 2023-12-12 |\r\n| 2.0.3    | 修复修复appid为空时请求错误 | 2023-12-06 |\r\n| 2.0.1    | 极大地优化SDK网络请求，丰富了debug模式的日志 | 2023-11-14 |\r\n| 1.19.7     | 优化当一页中存在描述题目+一道其他必填题目的填写体验，无需点击下一步按钮可直接进入下一页   | 2023-10-11 |\r\n| 1.19.6     | 优化page事件发送   | 2023-09-15 |\r\n| 1.19.5     | 问卷-结束页支持上传图片，以及自定义自动关闭时长  | 2023-09-08 |\r\n| 1.19.4     | 新增 `unset` 接口 清除客户uid信息  | 2023-08-23 |\r\n| 1.19.2     | 修复bug，支持使用 uni-app 框架开发的小程序  | 2023-07-18 |\r\n\r\n# **Step 1：创建微信小程序应用**\r\n创建应用时，选择应用类型「微信小程序」，并完善应用信息，包括应用名称（必填）及App ID（非必填）。\r\n![](https://help-assets.jinshuju.net/assets/file/1266/WeChatWorkScreenshot_e5319001-7072-4300-8341-0bab615f917a.png)\r\n\r\n# **Step2：复制SDK代码进行集成**\r\n在创建完成一个微信小程序应用后，可以在页面左侧「应用设置」里，可以找到「插件安装」，按照提示完成初始化安装。\r\n![](https://help-assets.jinshuju.net/assets/file/1267/WeChatWorkScreenshot_6fea4b06-1f8d-4983-8d1f-70143160196e.png)\r\n\r\n你可以自行完成 SDK 集成，也可以下载插件使用说明，交由研发人员处理。如有任何疑问请随时联系我们，会有专业客户顾问为你解答。\r\n![](https://help-assets.jinshuju.net/assets/file/1268/WeChatWorkScreenshot_eea9cfe4-6e99-4aa8-909e-842051559482.png)\r\n\r\n# **Step3：验证 SDK 集成是否生效**\r\n在完成第二步 SDK 代码集成后，你可以访问所集成 X-SDK 代码的微信小程序应用，就可以看到 X-SDK 集成的状态变为   绿色  ，点击会提示微信小程序连通中，可以对评价、问卷进行正常投放。\r\n![](https://help-assets.jinshuju.net/assets/file/1270/WeChatWorkScreenshot_e5dae71a-cf19-4662-b562-b66029a15032.png)\r\n\r\n否则你将会看到「微信小程序未连通」的红色提醒：\r\n![](https://help-assets.jinshuju.net/assets/file/1269/WeChatWorkScreenshot_8c40cedc-4424-4659-9193-a8de04ae828f.png)\r\n\r\n需要检查SDK代码是否正确安装，或者确认微信小程序绑定的应用ID是否正确。\u003cbr\u003e\r\n\r\n**获取应用ID**\r\n\r\n你可以在 **应用设置-小程序设置** 中直接复制应用ID。\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1362/29.png)\r\n\r\n\u003cbr\u003e\r\n**注意：如果在72小时内，X-SDK没有收到来自目标微信小程序的访问数据时，也会出现「微信小程序未连通」的提醒，你可以再次进入微信小程序，状态即可恢复。**\r\n\r\n# **Step 4：投放问卷、评价，回收数据**\r\n当 SDK 集成完毕，即可使用浩客问卷等相关能力；也可以邀请团队成员加入到你的应用中，协作进行管理。\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n* [创建一个评价](https://howxm.com/help/articles/create-feedback)\r\n* [创建一个问卷](https://howxm.com/help/articles/create-survey)\r\n* [邀请团队成员加入](https://howxm.com/help/articles/apps-team)\r\n\r\n\r\n---\r\n---\r\n\r\n# **插件介绍**\r\n**微信小程序插件id：**wx37a782d0c8107a02\r\n**微信插件官方页面**：[点击查看](https://mp.weixin.qq.com/wxopen/pluginbasicprofile?action=intro\u0026appid=wx37a782d0c8107a02)\r\n\r\n![](https://help-assets.jinshuju.net/assets/file/1271/%E5%B0%8F%E7%A8%8B%E5%BA%8F%E6%8F%92%E4%BB%B6.png)\r\n\r\n# **插件导入**\r\n## **第一步：**\u003cbr\u003e\r\n在小程序管理后台的“设置 - 第三方服务 - 插件管理”中添加插件。开发者可登录小程序管理后台，通过 wx37a782d0c8107a02 查找插件并添加。\r\n![](https://help-assets.jinshuju.net/assets/file/659/19.png)\r\n\r\n## **第二步：**\u003cbr\u003e\r\n在 app.json 配置插件信息\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n```JSON\r\n{\r\n \"plugins\": {\r\n   \"howxm-plugin\": {\r\n     \"version\": \"1.0.0\",\r\n     \"provider\": \"wx37a782d0c8107a02\"\r\n   }\r\n }\r\n}\r\n```\r\n## **第三步：**\u003cbr\u003e\r\n在 app.js 初始化插件\u003cbr\u003e\r\n\r\n```javascript\r\nconst howxm = requirePlugin('howxm-plugin')\r\n\r\nApp({\r\n onShow() {\r\n   howxm.debug(true) //设置为true时，开启调试模式\r\n   howxm.init(\r\n     '\u003c替换为你的浩客appId\u003e',\r\n     {},\r\n     function (data) {\r\n       // 成功回调\r\n     },\r\n     function (err) {\r\n       // 失败回调\r\n     }\r\n   )\r\n },\r\n\t})\r\n```\r\n## **第四步：**\u003cbr\u003e\r\n在需要弹出浩客问卷的页面引入 howxm-widget 组件\u003cbr\u003e\r\n\r\n  - 在页面 json 文件中引入组件\r\n\t- 如果在多个页面中都需要浩客问卷，可以在 app.json 中统一引入，而无需在单个页面中分别引入。\r\n  - 如果你的小程序是 uni-app 开发，且希望在全局绑定浩客插件时，请在 pages.json 中的 globalStyle 里来进行引入。\r\n\r\n```JSON\r\n{\r\n  \"usingComponents\": {\r\n    \"howxm-widget\": \"plugin://howxm-plugin/howxm-widget\"\r\n  }\r\n}\r\n```\r\n## **第五步：**\u003cbr\u003e\r\n  - 在所有应用到插件的wxml页面中需要手动引用组件\u003cbr\u003e\r\n \r\n```javascript\r\n \u003chowxm-widget  /\u003e\r\n```\r\n  - 插件支持的props\r\n  * path: 传入当前页面路径，可以配合问卷下“投放设置”内的“特定页面”功能，实现在小程序指定页面弹出问卷。（例如：``` \u003chowxm-widget path=\"page/home/index\"  /\u003e```）\r\n\r\n\r\n# **接口能力**\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\r\n```javascript\r\n  const howxm = requirePlugin('howxm-plugin')\r\n\r\n  howxm.identify(\r\n    {\r\n      uid: '00000001', // 必填\r\n      name: 'howxm',\r\n      mobile: '15380000000',\r\n      email: 'demo@howxm.com',\r\n\r\n      plan: 'basic',\r\n      birthday_at: '1998-01-28+08:00',\r\n    },\r\n    function (data) {\r\n      // 成功回调\r\n    },\r\n    function (err) {\r\n      // 失败回调\r\n    }\r\n  )\r\n```\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\r\n```javascript\r\n  const howxm = requirePlugin('howxm-plugin')\r\n\r\n  howxm.event(\r\n    '事件code', // 必填\r\n    {\r\n      // 事件属性，选填\r\n    },\r\n    function () {\r\n      // 成功回调\r\n    },\r\n    function (err) {\r\n      // 失败回调\r\n    }\r\n  )\r\n```\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\r\n```javascript\r\n    const howxm = requirePlugin('howxm-plugin')\r\n\r\n  howxm.checkOpen(\r\n    {\r\n      campaignId: '问卷/评价ID', // 必填\r\n\r\n      // 检测时可以传入当前的用户uid，选填\r\n      customer: {\r\n        uid: '00000001',\r\n      },\r\n      // 选填\r\n      extra: {\r\n        // 其他属性\r\n      },\r\n    },\r\n    function () {\r\n      // 检测成功回调\r\n    },\r\n    function (err) {\r\n      // 检测失败回调\r\n    }\r\n  )\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\r\n```javascript\r\n  const howxm = requirePlugin('howxm-plugin')\r\n\r\n  howxm.open({\r\n    campaignId: '问卷/评价ID', // 必填\r\n\r\n    // 手动触发时可以传入当前的用户信息，选填\r\n    customer: {\r\n      uid: '00000001',\r\n      // 其他用户属性\r\n    },\r\n    // 选填\r\n    extra: {\r\n      // 其他属性\r\n    },\r\n  })\r\n```\r\n\r\n## **5. register 注册事件回调**\r\n通过此方法可注册全局回调事件，在问卷展示和回收过程的不同阶段进行自定义处理。调用方法如下：\r\n\r\n  ```javascript\r\n  const howxm = requirePlugin('howxm-plugin')\r\n\r\n  howxm.registerCallback('onBeforeOpen', function(campaignId, uid, attributes){\r\n    console.log('onBeforeOpen: ', campaignId, uid, attributes)\r\n  })\r\n\t\r\n  howxm.registerCallback('onOpen', function(campaignId, uid, attributes){\r\n    console.log('onOpen: ', campaignId, uid, attributes)\r\n  })\r\n\t\r\n  howxm.registerCallback('onClose', function(campaignId, uid){\r\n    console.log('onClose: ', campaignId, uid)\r\n  })\r\n\t\r\n  howxm.registerCallback('onPageComplete', function(campaignId, uid, fieldsEntry){\r\n    console.log('onPageComplete: ', campaignId, uid, fieldsEntry)\r\n  })\r\n\t\r\n  howxm.registerCallback('onComplete', function(campaignId, uid){\r\n    console.log('onComplete: ', campaignId, uid)\r\n  })\r\n  ```\r\n\t\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## **6. unset 清除客户uid信息**\r\n\r\n在用户退出登录时，调用此接口可以清除用户uid信息\r\n\r\n```\r\nconst howxm = requirePlugin('howxm-plugin')\r\n\r\nhowxm.unset()\r\n```\r\n\r\n# **示例代码**\r\n## **1. 原生微信小程序**\r\nhttps://github.com/howxm/howxm-miniapp-seed\r\n## **2. Taro**\r\nhttps://github.com/howxm/howxm-taro-seed\r\n\r\n# **常见问题**\r\n## **1. 报错信息：component is not attached on current page**\r\n\r\n您需要在**页面 wxml 文件中添加组件**，示例代码如下：\r\n\r\n```javascript\r\n \u003chowxm-widget path=\"\u003c替换为调用页面的路径\u003e\" /\u003e\r\n```\r\n\r\n## **2. 使用 Taro 开发框架，无法弹出问卷**\r\n\r\nTaro的打包将 wxml 上所有的组件全部分离出去，生成了一个独立的模板文件，每个引用的组件包装为了template，而这种模式可能存在bug，具体可参照issue：https://github.com/NervJS/taro/issues/12553\r\n\r\n临时的解决方案为，在打包后的 dist 目录，找到使用使用组件的page页面的wxml，手动将插件引入：\\\u003chowxm-widget /\u003e，确保当前页面一定有引入插件即可解决。\r\n\r\n## **3. 小程序插件报错信息：Plugin \"wx.../0\" is not defined**\r\n![](https://help-assets.jinshuju.net/assets/file/1431/%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E6%88%AA%E5%9B%BE_c4e3741f-3b3f-4364-aa7d-56356bb71c9b.png)\r\n\r\n**问题描述**：https://developers.weixin.qq.com/community/develop/doc/00026826bb4e086140c7b847456400\r\n\r\n**解决方案**：检查打包是否超过了微信的包大小限制，导致微信自动进行了分包\r\n\r\n## **4. 小程序中弹窗从tab-bar上方弹出，如何配置**\r\n 调整custom-tab-bar/index.wxml文件中`cover-view`为`view`\r\n \r\n ## **5. 如何开启调试模式？\r\n \r\n 可以在 app.js 初始化插件的时候，插入代码    howxm.debug(true) 来开启调试模式。\r\n","featured":false,"category_id":4,"created_at":"2023-02-15T01:20:00.255Z","updated_at":"2025-06-25T06:50:16.593Z"}