开放标签
标签名称:
官方文档: developers.weixin.qq.com/doc/offiacc…
a、使用条件:
-
同一账号主体且通过认证的微信服务号、微信开放平台账号:先找到承载的公众号(必须是服务号),并配置公众号的js安全域名:登录微信公众平台进入“公众号设置”的“功能设置”里填写“JS接口安全域名”(当前h5网页)
-
公众号与app和h5网页绑定:微信开放平台里找对应的公众号,设置移动应用唤起,配置js安全域名
b、微信管理平台配置:
微信公众号操作:
1、开发-基本配置中-添加服务器ip白名单 ;
2、设置-公众号设置-功能设置-添加业务域名、js接口安全域名。
微信开放平台操作:
1、在微信开放平台将公众号进行绑定;
2、管理中心-创建需要跳转的移动应用;
3、在关联的公众号中进行网页跳转移动应用的关联设置。
实现的需求
app分享到微信的H5卡片网页(https的网页),微信公众号中打开的H5页面,用户打开该网页后上方有一个打开APP的按钮,如果手机已经安装了APP,则直接打开APP,如果未安装则跳转到应用市场进行下载等。
实现原理
利用微信提供的开放标签wx-open-launch-app,来进行跳转,通过该标签还能够得知当前手机是否安装app,如果已安装则打开app,未安装则跳转应用宝,在ios下应用宝会自动跳转App Store。
准备工作
-
微信公众号(已认证的
服务号),拿到开发者ID(AppID)和开发者密码(AppSecret),并设置IP白名单(计算签名的服务器IP); -
该服务号必须绑定JS接口安全域名,也就是移动端H5页面的域名;
-
关联移动应用(APP)的绑定关系,微信开放平台准备一个账号,主体需要和微信公众的服务号一致,并将服务号绑定在微信开放平台账号下,并在开放平台内绑定app,并设置域名与所需跳转的app,并拿到绑定的移动应用的AppID。
开发工作
-
请求后端提供的接口获取签名(实现整个过程需要后端来计算一个签名,所以需要先后端开发一个接口给前端,前端需要将当前页面的url传到后端参与签名,后端将签名信息返回给前端)。
-
引入JS-SDK
-
通过SDK的config方法将 请求后端得到的签名信息传入配置项
wx.config({ debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来,若要查看传入的参数,可以在pc端打开,参数信息会通过log打出,仅在pc端时才会打印 appId: '', // 必填,公众号的唯一标识 timestamp: , // 必填,生成签名的时间戳 nonceStr: '', // 必填,生成签名的随机串 signature: '',// 必填,签名 jsApiList: ['checkJsApi'], // 必填,需要使用的JS接口列表,没有就随便填一个 openTagList: ['wx-open-launch-app'] //必填, 要申请的开放标签名称})
将调试模式打开,当在微信内打开分享的该H5页面后,页面弹出 ok 字样验证成功。
appid就是移动应用关联的APPID,extinfo为需要传递给app的参数(仅支持字符串类型),launch事件为用户点击了跳转app按钮,error为跳转app失败事件
<wx-open-launch-app appid="关联的app应用id" :extinfo="extinfo" @launch="wxlaunchFn" @error="wxerrorFn"> <script type="text/wxtag-template"> <style>.btn {padding: 12px;}</style> <p class="btn">在APP内打开</button> </script></wx-open-launch-app>
注意事项:只有在签名,域名,都验证成功后,开放标签才会显示,否则什么都看不见
可以在打开失败的事件下,做判断,如果未安装app,则跳转应用市场让用户选择下载安装app
wxerrorFn(e){ //console.log('fail' , e); if(e.detail.errMsg === 'launch:fail') { //console.log('未安装app, 跳转应用宝地址'); window.location.href = "https://a.app.qq.com/o/simple.jsp?pkgname=xxxx"; } else if(e.detail.errMsg === 'launch:fail_check fail'){ //console.log('appid未绑定未关联到微信'); } },
以下为一些配置或属性介绍以及爱看i发过程中遇到的问题点
wx.config
首先与使用 JS-SDK 一致,需要先引入 jweixin-1.6.0 .js,后通过wx.config进行配置与申请;
这里的一个注意点是,即使只需要引入开放标签而不需要使用任何 JsApi,也需要至少向 jsApiList 传递一项,不能为空数组,必须要写一个微信的方法,如
wx.config({ debug: false, appId: '', // 必填,公众号的唯一标识 从后端获取的认证后的服务号的appId timestamp: , // 必填,生成签名的时间戳 nonceStr: '', // 必填,生成签名的随机串 signature: '',// 必填,签名 jsApiList: ['checkJsApi'],// 不能为空,必须要写一个微信的方法 openTagList: ['wx-open-launch-app']})
否则会导致iOS配置的没问题,但安卓始终无法配置成功,触发 wx.error。
标签引用
官方文档中的引用示例如下
<wx-open-launch-app appid="关联的app应用id" :extinfo="extinfo" @launch="wxlaunchFn" @error="wxerrorFn"> <template type='text/wxtag-template'> <style>.btn { padding: 12px }</style> <button class="btn">打开app</button> </template></wx-open-launch-app>
并且 <style> 中的样式需要以字符串形式编写,或直接在 button 上写行内样式。
如果使用了ts,那么引入微信开放标签是无法识别的,会报错,所以首先需要定义一下。
declare namespace JSX { interface IntrinsicElements { 'wx-open-launch-app': any; }}
在vue中使用
在vue使用开放标签时,需要在main.js中加入以下代码,否则会报错。
Vue.config.ignoredElements = [// 忽略自定义元素标签抛出的报错 'wx-open-launch-app'];
样式编写
外部样式无法影响到标签内元素的样式(
编写单位时不能使用 vw、vh,因此需要 getPx 转化,即用px进行编写;
<wx-open-launch-app> 的父元素不能是 flex 布局,否则会被挤到宽度近乎为0;
可以把所有的样式赋给开放标签的父级容器,设置宽高,溢出隐藏等属性,再把开放标签内样式opacity: 0, 就可达到想要的效果;
安卓手机可能出现标签样式不生效的问题,如果是vue开发,那么把开放标签展示由v-show 改为 v-if; 因为开放标签的父容器display:none 的话可能会影响到安卓端样式,导致样式不生效,点击不到等异常问题即使用v-if也不用担心,这样也会正常被微信编译。
标签属性
appid:
appid 是在微信公众平台中配置的关联应用(开放平台上的移动应用)的 appId或者说是需要跳转的app的id(注意不是公众号的 appId)
当碰上 "launch:fail_check fail" 报错时,应该检查的可能性有两个
-
上述的 appId 是否准确;
-
wx.config 中的 appId 配置的公众号Id是否准确。
extinfo:
extinfo 里放的是最重要的,即要给到客户端的需跳转到的对应路径信息,
其格式是字符串,因此如果约定的数据是对象,不要忘了先 JSON.stringify 下,给到客户端自行解析,例如跳转链接等。
错误信息获取
文档中写着 error 事件的返回值是 { errMsg: string },但实际上应该是 { detail: string },
可以在打开失败的事件下,做判断,如果未安装app,则跳转应用市场让用户选择下载安装app。
btn.addEventListener('error', function (e) {
console.log('fail', e.detail);
});
客户端处理
app开发人员也需要提前接入SDK,微信拉起客户端通过开放标签传过来的extinfo 参数(目标页面链接)进行解析,获取页面跳转链接打开页面,前提是必须保证SDK已经初始化,否则会出现只打开app,不会跳转到目标页面的情况。
调试
1、开放标签不能在本地调试,目前也不能在微信开发者工具调式,只能在真机,并且代码要部署到已认证的服务号,服务号绑定“JS接口安全域名”下的网页
2、微信开放标签按钮点击拉起app,必须是合法链接。通过app分享的H5卡片网页(https的网页),微信公众号中打开的H5页面,以及通过工具将链接生成二维码扫码跳转的H5页面等才能使用开放标签拉起app,暴露链接是不能拉起app的,点击会没反应,微信认为这是外链,安全性未知。
兜底处理
唤起失败
用户手机中可能未装有对应 App,及其他不会成功唤起 App 的情况
因此需要在 wx.error 和 <wx-open-launch-app> 绑定的 error 事件中都进行兜底处理,如调起原有的跳转到 AppStore / 应用宝等的流程 (wx.error 是针对微信版本、系统版本过低导致的配置失败的处理,开放标签的 error 则是针对应用尚未安装的处理)。