# 游云南开放平台JS-SDK使用说明
游云南开放平台JS-SDK主要提供了第三方小程序、第三方内嵌 Web 应用跳转游云南应用进行认证;和获取游云南下发 code 的方法。第三方应用的前端(小程序)需要将此 sdk 返回的 code 传递给第三方应用的服务。由第三方应用服务先调用游云南开放平台认证 api 换取 access_token 等,再携带 access_token 调游云南开放平台业务 api 请求到开放能力的数据。
除此之外,在内嵌 Web 应用中,开放平台JS-SDK还提供了容器的一些通用数据,比如手机设备型号信息。
# 更新日志
# 📌 1.0.5
- 支持第三方内嵌Web应用(内嵌在小程序)授权
- 支持获取容器提供的设备型号信息
# 0.1.4
- 支持第三方小程序应用授权
# 下载导入
开放平台JS-SDK直接提供了js源文件,可以下载后导入项目中作为本地依赖使用。
v1.0.5 (opens new window) v0.1.4 (opens new window)
# 使用前准备
- 在游云南开放平台注册成为开发者
- 创建应用
- 获得 appid 和 appsecret
- 申请开放能力权限
# sdk 使用
# 在第三方原生小程序中使用
# 第一步:使用 appid 创建实例
推荐使用独立的文件导出一个YynOpenSdk
的实例供项目使用。
所使用的 appid 是游云南开放平台下发的 appid
/**
* 假设下载下来的源文件放在项目src的plugins/yynOpenSdk.js
* 并将导出YynOpenSdk实例的文件放在utils/yynOpenSdk.js
*/
// utils/yynOpenSdk.js
// ES6
import YynOpenSdk from 'plugins/yynOpenSdk.js';
export default new YynOpenSdk({ appid: 'your appid' });
// 或者
// commonjs 原生小程序开发可能需要用这种引入方式
const YynOpenSdk = require('path/to/yynOpenSdk.js');
module.exports = new YynOpenSdk({ appid: 'your appid' });
# 第二步:第三方小程序唤起游云南小程序进行认证
注意,由于内部调用wx.navigateToMiniProgram
,所以此方法必须由用户主动触发调用。
wx.navigateToMiniProgram - 使用限制 (opens new window)
/**
* 需要使用开放能力的地方
*/
const yynOpenSdk = require('utils/yynOpenSdk.js');
//OR
// import yynOpenSdk from 'utils/yynOpenSdk.js'
// 这个方法应该被类似button click的行为主动调用,调用后将会跳转到游云南小程序获取认证
// scope是一个由开放能力授权域标识组成的字符串,由逗号分隔
async function callMpAuth() {
const scope = 'scope1,scope2,scope3...';
try {
await yynOpenSdk.callMpAuth(scope);
} catch (e) {
console.error(e);
}
}
# 第三步:在 onShow 中获取 code
wx.onAppShow (opens new window)
/**
* 需要使用开放能力的地方
* 可以在小程序app.js中响应回调,也可以使用wx.onAppShow
*/
const yynOpenSdk = require('utils/yynOpenSdk.js');
// app.js
App({
onShow(options) {
if (options.referrerInfo && options.referrerInfo.appId) {
try {
const code = yynOpenSdk.onMpAuthed(referrerInfo);
if (code) {
// 存储code或者传递给后端服务
}
} catch (e) {
console.error(e);
}
}
},
});
// OR
wx.onAppShow((options) => {
if (options.referrerInfo && options.referrerInfo.appId) {
try {
const code = yynOpenSdk.onMpAuthed(referrerInfo);
if (code) {
// 传递给后端服务换取token,并获取openid
}
} catch (e) {
console.error(e);
}
}
});
# 在内嵌 Web 应用(内嵌在小程序)中使用
# 第一步:使用 appid 创建实例
推荐使用独立的文件导出一个YynOpenSdk
的实例供项目使用。
所使用的 appid 是游云南开放平台下发的 appid
/**
* 假设下载下来的源文件放在项目src的plugins/yynOpenSdk.js
* 并将导出YynOpenSdk实例的文件放在utils/yynOpenSdk.js
*/
// utils/yynOpenSdk.js
import YynOpenSdk from 'plugins/yynOpenSdk.js';
export default new YynOpenSdk({ appid: 'your appid' });
# 第二步:第三方内嵌 Web 应用唤起游云南小程序进行认证
/**
* 需要使用开放能力的地方
*/
import yynOpenSdk from 'utils/yynOpenSdk.js';
// 调用后将会跳转到游云南小程序获取认证
// scope是一个由开放能力授权域标识组成的字符串,由逗号分隔
async function callMpAuthInWeb() {
const scope = 'scope1,scope2,scope3...';
// const customReturnUri = '......
try {
await yynOpenSdk.callMpAuthInWeb(scope);
// 也可以自定义从原生小程序返回的url,默认是window.location.origin + window.location.pathname
// await yynOpenSdk.callMpAuthInWeb(scope, customReturnUri)
} catch (e) {
console.error(e);
}
}
# 第三步:在入口文件或程序启动较早的时机获取 code
游云南小程序返回时,相当于重新加载内嵌 Web 应用,并通过 url 参数将 code 返回
import yynOpenSdk from 'utils/yynOpenSdk.js';
// 此方法可以在应用entry时调用
// 如果使用vue或react,也可以在根组件创建时调用
// 也可以在DOMContentLoaded监听内调用
// 不过要注意获取openid后,使用openid的时机要在这个异步操作之后
async function onMpAuthedInWeb() {
try {
const code = yynOpenSdk.onMpAuthedInWeb();
if (code) {
// 传递给后端服务换取token,并获取openid
}
} catch (e) {
console.error(e);
}
}
# 其他:获取所属容器的通用能力
- 获取当前手机设备型号
import yynOpenSdk from 'utils/yynOpenSdk.js';
const deviceModel = yynOpenSdk.getDeviceModelInWeb();
# API
interface OpenSdkOptions {
// 在开放平台注册应用的appid
appid: string;
// 可以提供一个三方维护的session来作为认证过程中的state校验,以确保通信的一致性
session?: string;
}
class YynOpenSdk {
// 构造函数
constructor(options: OpenSdkOptions);
// 获取当前应用的appid
get currentAppid(): string;
// 更新注入的session信息
updateSession(session: string): void;
// 第三方小程序唤起游云南小程序进行认证
callMpAuth(scope: string): Promise<any>;
// 第三方小程序监听从游云南小程序返回的code,ReferrerInfo是小程序onAppShow回调的一部分参数
// 具体请查看https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onAppShow.html
onMpAuthed(referrerInfo: ReferrerInfo): string | undefined;
// 第三方内嵌Web应用(内嵌在小程序)唤起游云南小程序进行认证
callMpAuthInWeb(scope: string, redirectUri?: string): Promise<any>;
// 第三方内嵌Web应用(内嵌在小程序)监听从游云南小程序返回的code
onMpAuthedInWeb(): string | undefined;
// 第三方内嵌Web应用(内嵌在小程序)获取游云南小程序容器提供的设备型号
getDeviceModelInWeb(): string | undefined;
}
# F.A.Q
Q: 什么是开放能力授权域?
A: 可以理解为开放能力的标识,和开放能力一一对应。开发者可以到开放平台中自己的应用管理中查看能力的标识字符串。第三方小程序想要接入什么能力就将对应的标识写到 scope 字符串中,不过请确保想要获取的能力都已经在开放平台被授权,否则只要有一个未授权的作用域标识传递给游云南小程序,都会被驳回。
Q: 内嵌Web应用可以部署在第三方域名下么?
A: 前端不可以。由于小程序webview安全域名限制,内嵌在游云南小程序内的Web应用前端必须部署在游云南域名下。部署应用时可以联系我们进行部署。