X-SDK 小程序集成

👏🏻👏🏻小程序集成X-SDK采用标准插件方式,插件已经在微信官方发布上线,搜索添加后可直接使用。

小程序 X-SDK 同样支持小程序path路径的方式,进行页面级别的问卷投放,详细查看:投放页面设置

小程序 X-SDK 支持原生小程序应用,也支持使用 uni-app 框架开发的小程序,请放心使用。

我们在 github 上放置了浩客的集成 demo repo 代码库,可以进行查看.

最新版本号 描述 发布时间
2.0.7 单选字段也只支持选项横向标签展示 2024-03-06
2.0.6 数据详情里增加用户的屏幕分辨率 2024-02-29
2.0.5 问卷-所有题目支持设置头图 2024-01-04
2.0.4 问卷-CTA题目支持设置按钮位置 2023-12-12
2.0.3 修复修复appid为空时请求错误 2023-12-06
2.0.1 极大地优化SDK网络请求,丰富了debug模式的日志 2023-11-14
1.19.7 优化当一页中存在描述题目+一道其他必填题目的填写体验,无需点击下一步按钮可直接进入下一页 2023-10-11
1.19.6 优化page事件发送 2023-09-15
1.19.5 问卷-结束页支持上传图片,以及自定义自动关闭时长 2023-09-08
1.19.4 新增 unset 接口 清除客户uid信息 2023-08-23
1.19.2 修复bug,支持使用 uni-app 框架开发的小程序 2023-07-18

Step 1:创建微信小程序应用

创建应用时,选择应用类型「微信小程序」,并完善应用信息,包括应用名称(必填)及App ID(非必填)。

Step2:复制SDK代码进行集成

在创建完成一个微信小程序应用后,可以在页面左侧「应用设置」里,可以找到「插件安装」,按照提示完成初始化安装。

你可以自行完成 SDK 集成,也可以下载插件使用说明,交由研发人员处理。如有任何疑问请随时联系我们,会有专业客户顾问为你解答。

Step3:验证 SDK 集成是否生效

在完成第二步 SDK 代码集成后,你可以访问所集成 X-SDK 代码的微信小程序应用,就可以看到 X-SDK 集成的状态变为 绿色 ,点击会提示微信小程序连通中,可以对评价、问卷进行正常投放。

否则你将会看到「微信小程序未连通」的红色提醒:

需要检查SDK代码是否正确安装,或者确认微信小程序绑定的应用ID是否正确。

获取应用ID

你可以在 应用设置-小程序设置 中直接复制应用ID。


注意:如果在72小时内,X-SDK没有收到来自目标微信小程序的访问数据时,也会出现「微信小程序未连通」的提醒,你可以再次进入微信小程序,状态即可恢复。

Step 4:投放问卷、评价,回收数据

当 SDK 集成完毕,即可使用浩客问卷等相关能力;也可以邀请团队成员加入到你的应用中,协作进行管理。



插件介绍

微信小程序插件id:wx37a782d0c8107a02 微信插件官方页面点击查看

插件导入

第一步:

在小程序管理后台的“设置 - 第三方服务 - 插件管理”中添加插件。开发者可登录小程序管理后台,通过 wx37a782d0c8107a02 查找插件并添加。

第二步:

在 app.json 配置插件信息

{
 "plugins": {
   "howxm-plugin": {
     "version": "1.0.0",
     "provider": "wx37a782d0c8107a02"
   }
 }
}

第三步:

在 app.js 初始化插件

const howxm = requirePlugin('howxm-plugin')

App({
 onShow() {
   howxm.debug(true) //设置为true时,开启调试模式
   howxm.init(
     '<替换为你的浩客appId>',
     {},
     function (data) {
       // 成功回调
     },
     function (err) {
       // 失败回调
     }
   )
 },
    })

第四步:

在需要弹出浩客问卷的页面引入 howxm-widget 组件

  • 在页面 json 文件中引入组件
    • 如果在多个页面中都需要浩客问卷,可以在 app.json 中统一引入,而无需在单个页面中分别引入。
  • 如果你的小程序是 uni-app 开发,且希望在全局绑定浩客插件时,请在 pages.json 中的 globalStyle 里来进行引入。
{
  "usingComponents": {
    "howxm-widget": "plugin://howxm-plugin/howxm-widget"
  }
}

第五步:

  • 在所有应用到插件的wxml页面中需要手动引用组件
 <howxm-widget  />
  • 插件支持的props
  • path: 传入当前页面路径,可以配合问卷下“投放设置”内的“特定页面”功能,实现在小程序指定页面弹出问卷。(例如:<howxm-widget path="page/home/index" />

接口能力

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

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

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

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

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

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

1. identify 用户身份信息传递

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

  const howxm = requirePlugin('howxm-plugin')

  howxm.identify(
    {
      uid: '00000001', // 必填
      name: 'howxm',
      mobile: '15380000000',
      email: 'demo@howxm.com',

      plan: 'basic',
      birthday_at: '1998-01-28+08:00',
    },
    function (data) {
      // 成功回调
    },
    function (err) {
      // 失败回调
    }
  )

2. event 抛出事件接口

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

  const howxm = requirePlugin('howxm-plugin')

  howxm.event(
    '事件code', // 必填
    {
      // 事件属性,选填
    },
    function () {
      // 成功回调
    },
    function (err) {
      // 失败回调
    }
  )

3. checkOpen 弹出策略检查接口

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

    const howxm = requirePlugin('howxm-plugin')

  howxm.checkOpen(
    {
      campaignId: '问卷/评价ID', // 必填

      // 检测时可以传入当前的用户uid,选填
      customer: {
        uid: '00000001',
      },
      // 选填
      extra: {
        // 其他属性
      },
    },
    function () {
      // 检测成功回调
    },
    function (err) {
      // 检测失败回调
    }
  )

4. open 弹出问卷接口

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

  const howxm = requirePlugin('howxm-plugin')

  howxm.open({
    campaignId: '问卷/评价ID', // 必填

    // 手动触发时可以传入当前的用户信息,选填
    customer: {
      uid: '00000001',
      // 其他用户属性
    },
    // 选填
    extra: {
      // 其他属性
    },
  })

5. register 注册事件回调

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

  const howxm = requirePlugin('howxm-plugin')

  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 用户每提交一页,系统调用一次

6. unset 清除客户uid信息

在用户退出登录时,调用此接口可以清除用户uid信息

const howxm = requirePlugin('howxm-plugin')

howxm.unset()

示例代码

1. 原生微信小程序

https://github.com/howxm/howxm-miniapp-seed

2. Taro

https://github.com/howxm/howxm-taro-seed

常见问题

1. 报错信息:component is not attached on current page

您需要在页面 wxml 文件中添加组件,示例代码如下:

 <howxm-widget path="<替换为调用页面的路径>" />

2. 使用 Taro 开发框架,无法弹出问卷

Taro的打包将 wxml 上所有的组件全部分离出去,生成了一个独立的模板文件,每个引用的组件包装为了template,而这种模式可能存在bug,具体可参照issue:https://github.com/NervJS/taro/issues/12553

临时的解决方案为,在打包后的 dist 目录,找到使用使用组件的page页面的wxml,手动将插件引入:<howxm-widget />,确保当前页面一定有引入插件即可解决。

3. 小程序插件报错信息:Plugin "wx.../0" is not defined

问题描述https://developers.weixin.qq.com/community/develop/doc/00026826bb4e086140c7b847456400

解决方案:检查打包是否超过了微信的包大小限制,导致微信自动进行了分包

4. 小程序中弹窗从tab-bar上方弹出,如何配置

调整custom-tab-bar/index.wxml文件中cover-viewview

## **5. 如何开启调试模式?

可以在 app.js 初始化插件的时候,插入代码 howxm.debug(true) 来开启调试模式。