在微信外唤起微信小程序

唤起微信小程序

目的：为了跳转到微信环境下，可以进行长按扫码

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 调用
• 云调用

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：

1. 单个小程序每日生成 Scheme 上限为50万个（包含短期有效 Scheme 与长期有效 Scheme）
2. 有效时间超过180天的 Scheme 或永久有效的 Scheme 为长期有效Scheme，单个小程序总共可生成长期有效 Scheme 上限为10万个，请谨慎调用
3. 有效时间不超过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：

1. 单个小程序每日生成 Link 上限为50万个（包含短期有效 Link 与长期有效 Link ）
2. 有效时间超过180天的 Link 或永久有效的 Link 为长期有效Link，单个小程序总共可生成长期有效 Link 上限为10万个，请谨慎调用
3. 有效时间不超过180天的 Link 为短期有效Link，单个小程序生成短期有效 Link 不设上限

注意事项

1. 只能生成已发布的小程序的 URL Link。
2. 在微信内或者安卓手机打开 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站		对话聊天不支持打开链接（苹果/安卓）
网易云音乐	✅安卓
爱奇艺

相关链接

https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/url-scheme/urlscheme.generate.html
https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/url-link.html
https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/url-scheme.html