# 游云南开放平台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)

# 使用前准备

  1. 在游云南开放平台注册成为开发者
  2. 创建应用
  3. 获得 appid 和 appsecret
  4. 申请开放能力权限

# 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

App.onShow (opens new window)

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);
  }
}
# 其他:获取所属容器的通用能力
  1. 获取当前手机设备型号
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应用前端必须部署在游云南域名下。部署应用时可以联系我们进行部署。

上次更新: 6/11/2021, 5:30:47 PM