支付宝小程序

在支付宝小程序里嵌入对话页面。配好域名之后要重新打包提审，线上小程序才会跟着生效。

通用原理、前提条件和各平台对照见小程序接入总览。这一页只讲支付宝这边要做的事。

支付宝特有的两条

白名单有两个，别配错。 支付宝后台有「服务器域名白名单」和「H5 域名配置」两处，管的不是一回事：前者管小程序自己发的网络请求，后者才管 web-view 打开的页面。要配的是后者。

改完要重新发版才生效。 微信和抖音改完域名当即生效，支付宝这边配好之后，已发布的线上小程序不会跟着变，要重新打包提审发布。

开始之前

• 小程序是企业主体
• 有一个已完成备案的域名，并且你能往它的根目录传文件——支付宝靠这个文件确认域名归你，跟域名备案在谁名下无关
• 已经完成自有域名部署，用浏览器打开 https://你的域名/chat.html 能正常对话

第一步：把域名加入 H5 域名白名单

登录支付宝开放平台，进入你的小程序，在开发设置里找到 H5 域名配置（不是「服务器域名白名单」），选择 添加。

1. 选择 下载校验文件，把它传到你的域名根目录，确认浏览器能访问到。传校验文件和传 chat.html 是同一个操作，交给同一个人做就行。
2. 填写域名地址，格式为 https://你的域名，确认校验文件能正常访问，校验通过后保存。
3. 填写内嵌页面的使用场景、域名地址和页面截图，提交审核。截图要和这个域名实际打开的页面一致，对不上会被驳回。

只支持 HTTPS 域名，不支持 IP 地址和端口号。具体菜单位置以支付宝开放平台当时的界面为准。

第二步：单独建一个页面放 web-view

web-view 会铺满整个页面

一个小程序页面只能放一个 web-view，它会盖住页面上的其他组件。要单独建一个页面专门放它，不要塞进已有页面的一块区域。

新建页面的 axml 里只放一行：

<web-view src="https://你的域名/chat.html"></web-view>

然后在首页、我的页面或者任何你想放客服入口的地方跳转过来：

my.navigateTo({ url: '/pages/support/index' })

第三步：带上客户身份

在拼 web-view 地址时把客户信息带上，客服就不是面对一个匿名访客：

Page({
  data: { url: '' },
  onLoad() {
    const user = my.getStorageSync({ key: 'user' }).data || {}
    const query = [
      'u=' + encodeURIComponent(user.id),
      'n=' + encodeURIComponent(user.name),
    ].join('&')
    this.setData({ url: 'https://你的域名/chat.html?' + query })
  },
})

u 是必填的，其余资料要挂在它上面。姓名手机号这些参数在页面打开后会自动从地址栏抹掉。完整的参数清单见传客户资料给客服。

常见问题

页面打不开，提示域名不在白名单

症状：web-view 页面打开后报错或空白，提示域名未配置。

成因：域名没加进 H5 域名配置，或者加错到了「服务器域名白名单」里。

解决：确认加的是 H5 域名配置那一项。已经加对的，检查是否重新打包发布过——线上版本用的是发版时的配置。

开发工具里能打开，真机上打不开

症状：在支付宝开发者工具里预览正常，用支付宝扫码或线上版本打开就失败。

成因：多半是白名单改了但没重新发版。开发工具通常可以跳过域名校验，真机走的是线上配置。

解决：重新打包生成体验版验证，确认无误后提交审核发布。

页面出来了但聊天窗一直转圈

症状：对话页面能打开，聊天区域一直加载不出来。

成因：多半是对话页面本身的问题，跟小程序没关系。H5 域名白名单只管 web-view 打开的地址，页面里加载客服程序、连接服务端用到的地址不用你配。

解决：用手机浏览器直接打开 https://你的域名/chat.html。浏览器里也转圈，按故障排查定位对话页面本身；浏览器里正常的，检查 web-view 的地址有没有被改写或跳转到别的域名，跳转之后的域名也要加进白名单。

下一步

• 小程序接入总览 —— 其他平台怎么接，以及共同的注意事项
• 传客户资料给客服 —— 把会员信息传给客服
• 故障排查 —— 对话页面本身打不开时怎么定位