模板模式接入关联普通二维码

产品介绍

普通二维码是指开发者使用工具对网页链接进行编码后生成的二维码。

商家可不需更换线下二维码，通过在小程序后台设置新的关联规则，将原线下普通二维码的地址与小程序页面关联，用户用支付宝扫描该地址的普通二维码即可打开小程序并跳转到指定页面。

系统服务商（ISV）推广小程序模板时，常常需要在商家订购小程序之前，预先生产对应的普通二维码物料。后续每有一个商家成功订购小程序模板，就可以立即为其配发一定数量的线下二维码物料，作为此小程序的流量入口。

系统服务商（ISV）在设计线下二维码物料时，建议遵循下文的设计规范，做好相关规划，以便后续能通过统一的规则高效管理所有线下二维码。

设计规范

原则

同一个商家的所有二维码地址，都拥有相同的 URL 地址前缀，且该地址前缀是该商家独享的。

示例

例如，商家 A 的所有二维码（如下），都以 https://www.openhome.com/a 开头，该地址前缀为商家 A 独享。

https://www.openhome.com/a/001

https://www.openhome.com/a/002/abc

https://www.openhome.com/a/003/def/ghi

... ...

商家 B 的所有二维码（如下），都以 https://www.openhome.com/b 开头，该地址前缀为商家 B 独享。

https://www.openhome.com/b/001

https://www.openhome.com/b/002/abc

https://www.openhome.com/b/003/def/ghi

... ...

优势

在为小程序关联普通二维码时，每个商家小程序，只需要配置一条规则即可。可以大幅度降低二维码部署的复杂度，以及提升二维码的扫码效率。

例如，商家 A 的小程序，配置的关联规则如下图所示。

接入流程

1. 上传模板代码版本后，在 开放平台控制台 > 三方服务 > 小程序模板，选择需要的模板，在 码管理 > 关联普通二维码，点击 添加。
    
   

1. 在模板的 码管理 中配置规则，并按照提示，正确完成匹配规则中二维码地址的域名校验。
   校验步骤：
   a. 下载检验文件；
   b. 将校验文件放置于二维码的域名根目录下；
   例如，需要关联的二维码域名是 a.b.com/1/qrcode1 和 a.b.com/2/qrcode2，则只需要验证 b.com 域名即可。
   c. 点击页面上的验证按钮，确认验证文件可以正常访问。
    
   

精确匹配 和 模糊匹配 区别：

• 精确匹配：根据填写的二维码地址精确匹配，地址完全一致时才能唤起小程序并跳转到指定页面（如：配置二维码地址为 https://www.alipay.com/my/doc?id=123 ，当用户扫这个地址的二维码可唤起小程序）。

• 模糊匹配：根据填写的二维码地址前缀模糊匹配，只要地址前缀匹配即可唤起小程序跳转到指定页面（如：配置二维码地址为 https://www.alipay.com/my/ ，当用户扫的二维码地址为 https://www.alipay.com/my/doc?id=123 可唤起小程序，只要前缀完全匹配即可唤起小程序）。

1. 构建商家小程序版本 后，第三方应用代商家小程序调用 alipay.open.mini.qrcode.bind 接口，为商家小程序关联在模板码管理中已校验域名的普通二维码。
   即入参 route_url 的域名是在模板码管理中已校验的（上述步骤 2.C）。
   

说明：

• 不同的商家小程序需关联不同的普通二维码，即需保证不同商家关联的二维码地址不同。
  

• 如需删除关联规则，可调用 alipay.open.mini.qrcode.unbind 接口，删除商家小程序中已关联的二维码。
  

• 若商家小程序没有生成体验版，调用关联普通二维码接口会失败。请生成体验版或商家小程序有上架版本后，再调用关联普通二维码接口。
  

获取二维码码值

获取二维码码值请在小程序 app.js 文件的 app() 的 onLaunch() 方法中使用 options.query 获取，解析码值可得到二维码地址 ? 后的所携参数，代码示例如下：

onLaunch(options){    my.alert({      title: 'app onLaunch',      content:  JSON.stringify(options),      success: (res) => {          //成功处理代码段      },    });  //获取关联普通二维码的码值，放到全局变量qrCode中  if (options.query && options.query.qrCode) {      this.qrCode = options.query.qrCode;    }



IDE 调试启动参数

比如普通二维码码值是 http://商户网站域名?bb=cc&dd=ff。

1. URLENCODE 处理后，得到http%3a%2f%2f%e5%95%86%e6%88%b7%e7%bd%91%e7%ab%99%e5%9f%9f%e5%90%8d%3fbb%3dcc%26dd%3dff。
   

2. 打开 IDE 顶部功能区中的添加编译模式，选择自定义编译。
   
   

1. 在之前得到的参数前面加上 “qrCode=” 后填入启动参数并确认。 
    
   

2. 在模拟器中进行调试。
   

常见问题

Q：第一次扫码进入小程序，切入后台。第二次扫码进入后，在 onLaunch 函数中获取不到参数，如何解决？

A：建议在 app.js 的 onLaunch 和 onShow 函数中都尝试获取参数。

Q：在模板中添加了域名，调用接口时还是提示“HOST_VERIFY_FAILD 域名校验失败 ”，如何解决？

A：添加域名应在第三方应用的域白名单中添加，之后，需要重新构建商家小程序版本，进行提审并通过后，新的配置才会在商家小程序中生效。

Q：调用接口时提示“TEMPLATE_NOT_HAVE_HOST 非模板名下持有域名”，如何解决？

A：请检查：

1. 需要配置规则的小程序必须是该模板实例化出来的；
   

2. 按照操作流程 2.C 的说明，正确完成域名校验。