微信外唤起微信小程序的方法详解
作者:全智能时代
唤起微信小程序
目的:为了跳转到微信环境下,可以进行长按扫码
0. 接口调用凭证
auth.getAccessToken
本接口应在服务器端调用,详细说明参见服务端API。
获取小程序全局唯一后台接口调用凭据(access_token
)。调用绝大多数后台接口时都需使用 access_token,开发者需要进行妥善保存。 如使用云开发,可通过云调用免维护 access_token 调用。如使用云托管,也可以通过微信令牌/开放接口服务免维护 access_token 调用。
请求地址
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
请求参数
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
grant_type | string | 是 | 填写 client_credential | |
appid | string | 是 | 小程序唯一凭证,即 AppID,可在「微信公众平台 - 设置 - 开发设置」页中获得。(需要已经成为开发者,且帐号没有异常状态) | |
secret | string | 是 | 小程序唯一凭证密钥,即 AppSecret,获取方式同 appid |
返回值
Object 返回的 JSON 数据包
属性 | 类型 | 说明 |
---|---|---|
access_token | string | 获取到的凭证 |
expires_in | number | 凭证有效时间,单位:秒。目前是7200秒之内的值。 |
errcode | number | 错误码 |
errmsg | string | 错误信息 |
errcode 的合法值
值 | 说明 | 最低版本 |
---|---|---|
-1 | 系统繁忙,此时请开发者稍候再试 | |
0 | 请求成功 | |
40001 | AppSecret 错误或者 AppSecret 不属于这个小程序,请开发者确认 AppSecret 的正确性 | |
40002 | 请确保 grant_type 字段值为 client_credential | |
40013 | 不合法的 AppID,请开发者检查 AppID 的正确性,避免异常字符,注意大小写 |
返回数据示例
正常返回
{"access_token":"ACCESS_TOKEN","expires_in":7200}
错误时返回
{"errcode":40013,"errmsg":"invalid appid"}
access_token 的存储与更新
access_token
的存储至少要保留 512 个字符空间;access_token
的有效期目前为 2 个小时,需定时刷新,重复获取将导致上次获取的access_token
失效;- 建议开发者使用中控服务器统一获取和刷新
access_token
,其他业务逻辑服务器所使用的access_token
均来自于该中控服务器,不应该各自去刷新,否则容易造成冲突,导致access_token
覆盖而影响业务; access_token
的有效期通过返回的expires_in
来传达,目前是7200秒之内的值,中控服务器需要根据这个有效时间提前去刷新。在刷新过程中,中控服务器可对外继续输出的老access_token
,此时公众平台后台会保证在5分钟内,新老access_token
都可用,这保证了第三方业务的平滑过渡;access_token
的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新access_token
的接口,这样便于业务服务器在API调用获知access_token
已超时的情况下,可以触发access_token
的刷新流程。
详情可参考微信公众平台文档 《获取access_token》
1.生成链接
urllink.generate
本接口应在服务器端调用,详细说明参见服务端API。
本接口支持云调用。需开发者工具版本 >=
1.02.1904090
(最新稳定版下载),wx-server-sdk
>=0.4.0
获取小程序 URL Link,适用于短信、邮件、网页、微信内等拉起小程序的业务场景。通过该接口,可以选择生成到期失效和永久有效的小程序链接,有数量限制,目前仅针对国内非个人主体的小程序开放,详见获取 URL Link
调用方式:
HTTPS 调用
请求地址
POST https://api.weixin.qq.com/wxa/generate_urllink?access_token=ACCESS_TOKEN
请求参数
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
access_token / cloudbase_access_token | string | 是 | 接口调用凭证 | |
path | string | 否 | 通过 URL Link 进入的小程序页面路径,必须是已经发布的小程序存在的页面,不可携带 query 。path 为空时会跳转小程序主页 | |
query | string | 否 | 通过 URL Link 进入小程序时的query,最大1024个字符,只支持数字,大小写英文以及部分特殊字符:!#$&'()*+,/:;=?@-._~% | |
env_version | string | “release” | 否 | 要打开的小程序版本。正式版为 “release”,体验版为"trial",开发版为"develop",仅在微信外打开时生效。体验版和开发版仅在iOS 上支持,Android 将在近期支持。 |
is_expire | boolean | false | 否 | 生成的 URL Link 类型,到期失效:true,永久有效:false。注意,永久有效 Link 和有效时间超过180天的到期失效 Link 的总数上限为10万个,详见获取 URL Link,生成 Link 前请仔细确认。 |
expire_type | number | 0 | 否 | 小程序 URL Link 失效类型,失效时间:0,失效间隔天数:1 |
expire_time | number | 否 | 到期失效的 URL Link 的失效时间,为 Unix 时间戳。生成的到期失效 URL Link 在该时间前有效。最长有效期为1年。expire_type 为 0 必填 | |
expire_interval | number | 否 | 到期失效的URL Link的失效间隔天数。生成的到期失效URL Link在该间隔时间到达前有效。最长间隔天数为365天。expire_type 为 1 必填 | |
cloud_base | Object | 否 | 云开发静态网站自定义 H5 配置参数,可配置中转的云开发 H5 页面。不填默认用官方 H5 页面 |
cloud_base 的结构
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
env | string | 是 | 云开发环境 | |
domain | string | 否 | 静态网站自定义域名,不填则使用默认域名 | |
path | string | / | 否 | 云开发静态网站 H5 页面路径,不可携带 query |
query | string | 否 | 云开发静态网站 H5 页面 query 参数,最大 1024 个字符,只支持数字,大小写英文以及部分特殊字符:`!#$&’()*+,/:;=?@-._~%`` | |
resource_appid | string | 否 | 第三方批量代云开发时必填,表示创建该 env 的 appid (小程序/第三方平台) |
返回值
url_link
生成的小程序 URL Link
返回值说明
如果调用成功,会直接返回生成的小程序 URL Link。如果请求失败,会返回 JSON 格式的数据。
示例
请求
{ "path": "/pages/publishHomework/publishHomework", "query": "", "is_expire":true, "expire_type":1, "expire_interval":1, "env_version": "release", "cloud_base": { "env": "xxx", "domain": "xxx.xx", "path": "/jump-wxa.html", "query": "a=1&b=2" } }
返回
{ "errcode": 0, "errmsg": "ok", "url_link": "URL Link" }
2.1 唤起小程序:URL Scheme
通过服务端接口或在小程序管理后台「工具」-「生成 URL Scheme」入口可以获取打开小程序任意页面的 URL Scheme。适用于从短信、邮件、微信外网页等场景打开小程序。 通过 URL Scheme 打开小程序的场景值为 1065。
生成的 URL Scheme 如下所示:
weixin://dl/business/?t= *TICKET*
iOS系统支持识别 URL Scheme,可在短信等应用场景中直接通过Scheme跳转小程序。
Android系统不支持直接识别 URL Scheme,用户无法通过 Scheme 正常打开小程序,开发者需要使用 H5 页面中转,再跳转到 Scheme 实现打开小程序,跳转代码示例如下:
location.href = 'weixin://dl/business/?t= *TICKET*'
该跳转方法可以在用户打开 H5 时立即调用,也可以在用户触发事件后调用。
调用上限
Scheme 将根据是否为到期有效与失效时间参数,分为短期有效Scheme与长期有效Scheme:
- 单个小程序每日生成 Scheme 上限为50万个(包含短期有效 Scheme 与长期有效 Scheme)
- 有效时间超过180天的 Scheme 或永久有效的 Scheme 为长期有效Scheme,单个小程序总共可生成长期有效 Scheme 上限为10万个,请谨慎调用
- 有效时间不超过180天的 Scheme 为短期有效Scheme,单个小程序生成短期有效 Scheme 不设上限
2.2 唤起小程序:URL Link
通过服务端接口可以获取打开小程序任意页面的 URL Link。适用于从短信、邮件、网页、微信内等场景打开小程序。 通过 URL Link 打开小程序的场景值为 1194。
生成的 URL Link 如下所示:
https://wxaurl.cn/*TICKET* 或 https://wxmpurl.cn/*TICKET*
调用上限
Link 将根据是否为到期有效与失效时间参数,分为短期有效Link 与 长期有效Link:
- 单个小程序每日生成 Link 上限为50万个(包含短期有效 Link 与长期有效 Link )
- 有效时间超过180天的 Link 或永久有效的 Link 为长期有效Link,单个小程序总共可生成长期有效 Link 上限为10万个,请谨慎调用
- 有效时间不超过180天的 Link 为短期有效Link,单个小程序生成短期有效 Link 不设上限
注意事项
- 只能生成已发布的小程序的 URL Link。
- 在微信内或者安卓手机打开 URL Link 时,默认会先跳转官方 H5 中间页,如果需要定制 H5 内容,可以使用云开发静态网站。
示例代码
默认官方 H5 示例地址:https://wxaurl.cn/pFawq35qbfd
自定义 H5 示例地址:https://wxaurl.cn/GI7aI2G1otd
兼容性
记录在IOS、安卓环境下各应用调起小程序的情况
APP | 支持环境 IOS 安卓 | 其他说明 |
---|---|---|
原生浏览器 | ✅IOS ✅安卓 | |
钉钉 | ✅安卓 | |
微博 | ✅IOS ✅安卓 | 需配置安全域名 |
小红书 | 小红链接打不开(安卓) | |
咸鱼 | 聊天窗口发送的链接 不允许打开 | |
qq群 | ✅IOS | |
知乎 | ✅IOS ✅安卓 | |
百度问答 | ||
百度网盘 | ||
快手 | ✅安卓 | |
抖音 | ✅IOS ✅安卓 | |
uc浏览器 | ✅IOS ✅安卓 | |
百度 | ✅IOS ✅安卓 | |
B站 | 对话聊天不支持打开链接(苹果/安卓) | |
网易云音乐 | ✅安卓 | |
爱奇艺 |
相关链接
urlscheme.generate | 微信开放文档
获取 URL Link | 微信开放文档
获取 URL Scheme | 微信开放文档