Authing 文档文档
快速开始
概念
使用指南
开发集成 V2 arrow
  • V2 文档
  • V3 文档
元数据
应用集成
身份自动化
加入 APN
开发集成
多租户(内测版)
控制台文档
多租户控制台
租户控制台
Saas 应用 Demo
快速开始
概念
使用指南
开发集成 V2 arrow
  • V2 文档
  • V3 文档
元数据
应用集成
身份自动化
加入 APN
开发集成
多租户(内测版)
控制台文档
多租户控制台
租户控制台
Saas 应用 Demo
旧版
开发集成
  • JavaScript SDK 索引
  • 单点登录(SSO)
  • 登录组件 (Guard)

  • 多因素认证组件(MFA)

  • JavaScript / Node.js

  • Java / Kotlin

  • Python

  • C#

  • PHP

  • Go

  • Ruby
  • Delphi
  • Android

  • iOS

  • Flutter

  • 微信小程序
  • 微信网页授权
  • React Native
  • 框架集成

  • Radius
  • 错误代码

¶ SDK for 微信小程序

更新时间: 2025-02-18 09:00:47
编辑

GitHub 源码地址:https://github.com/authing/authing-wxapp-sdk (opens new window)

Authing 小程序 SDK (authing-wxapp-sdk) 适用于在微信小程序环境下使用,以 authing-js-sdk (opens new window) 为基础,对微信小程序环境做了适配。你可以使用 authing-js-sdk AuthenticationClient 中的所有方法,如获取、修改用户资料,添加用户自定义字段等。同时专门在小程序环境下使用的 通过微信授权获取用户手机号、 使用微信授权登录、使用微信授权的手机号登录 等方法。

¶ 在 Authing 中配置小程序登录

为了在小程序中使用 Authing 小程序 SDK,你需要先在微信开放平台 (opens new window)申请一个小程序,同时在 Authing 控制台 (opens new window)内填入该小程序的配置。

配置小程序登录
  1. 前先前往微信开放平台 (opens new window)注册一个微信小程序开发账号
  • 如果你需要获取用户手机号,需要通过微信认证。
  • 将 core.authing.cn 加入微信的 request 合法域名:

  1. 在 Authing 控制台 (opens new window)开启微信小程序社会化登录。
  • 获取微信小程序 AppId 和 AppSecret

  • 前往 Authing 控制台 (opens new window) 连接身份源 - 社会化登录 - 小程序内登录:

  • 填入小程序 AppId 和 AppSecret,点击保存即可。

¶ GitHub 下载地址

条目说明
支持版本小程序基础库版本 2.2.1 +
仓库地址https://github.com/Authing/authing-wxapp-sdk (opens new window)

¶ 安装

从小程序基础库版本 2.2.1 或以上、及开发者工具 1.02.1808300 或以上开始,小程序支持使用 npm 安装第三方包,详情请见: npm 支持 | 微信开放文档 (opens new window) 。

¶ 安装 npm 包

使用 npm:

npm install authing-wxapp-sdk

使用 yarn:

yarn add authing-wxapp-sdk

¶ 在小程序开发者工具中构建 npm

点击开发者工具中的菜单栏:工具 --> 构建 npm:

勾选 使用 npm 模块 选项:

¶ 初始化

AuthenticationClient 初始化需要传入AppId (应用 ID):

你可以在控制台的 应用 中查看自己的应用列表。

const { AuthenticationClient } = require('authing-wxapp-sdk')

const authing = new AuthenticationClient({
  appId: 'AUTHING_APP_ID',
})

完整参数列表如下:

  • appId: Authing 应用 ID(必填);
  • accessToken: 通过用户的 token 初始化 SDK(可选,你可以在前端 localStorage 中缓存用户 token,实现记住登录的目的) 。
  • timeout: 请求超时时间,单位为毫秒,默认为 10000 (10 秒)。
  • onError: 错误处理函数,你可以用其来全局捕捉 Authing 客户端请求的所有异常。函数定义为:
(code: number, message: string, data: any) => void

完整的错误代码请见此文档。

  • host: Authing 服务器地址。如果你使用的是公有云版本,请忽略此参数。如果你使用的是私有化部署的版本,此参数必填。格式如下: https://authing-api.mydomain.com,最后不带 /。

¶ 使用方法

在用户完成登录之后,SDK 会将用户的 token 写入到微信的 Storage 中,后续请求会自动携带 token 访问。

const { code } = await wx.login()
// 无需用户授权
const user = await authing.loginByCode(code) // 成功登录,将 token 写入微信 Storage

// 登录之后可以进行此操作
await authing.updateProfile((nickname: 'Bob'))

后续用户再次打开小程序,如果小程序的 Storage 中保存有用户的 token,访问 authing 的请求将会自动带上该 token。

// 该请求可以成功,因为该用户出于登录状态。
await authing.updateProfile((nickname: 'Mick'))

¶ API Reference

你可以使用 authing-js-sdk AuthenticationClient 中的所有方法,调用方法和 authing-js-sdk 完全一致。

¶ loginByCode

使用微信授权的方式登录。

  • 如果用户第一次在小程序中登录,且用户没有使用和该小程序绑定同一主体的微信应用登录过,将会创建一个新账号。
  • 如果用户第一次在小程序中登录,但是该用户使用和该小程序绑定同一主体的微信应用登录过,将会返回对应的微信账号。

¶ 参数

  • code: 调用 wx.login() (opens new window) 获取的 code,不需要用户授权。必填。
  • options: 选填。
  • options.iv: open-type 为 getUserInfo 的微信 Button 组件 (opens new window) 点击事件返回的 iv。iv 和 encryptedData 必须同时传递,Authing Server 会尝试从 iv 和 encryptedData 中加密出用户资料。第一次需要用户手动授权。选填。
  • options.encryptedData: open-type 为 getUserInfo 的微信 Button 组件 (opens new window) 点击事件返回的 encryptedData。iv 和 encryptedData 必须同时传递,Authing Server 会尝试从 iv 和 encryptedData 中加密出用户资料。第一次需要用户手动授权。选填。
  • options.rawData: open-type 为 getUserInfo 的微信 Button 组件 (opens new window) 点击事件返回的 rawData。和 iv + encryptedData 二选一,如果传了 rawData, Authing Server 会直接使用该数据作为用户的 profile。第一次需要用户手动授权。选填。

¶ 示例

  1. 静默授权

首次注册的用户的 profile 中的 nickname, avatar 将为空,因为没有获取到用户的头像和昵称。

const { code } = await wx.login()
const data = await authing.loginByCode(code)
  1. 用户手动授权获取昵称头像

仅第一次需要授权,用户授权之后可以使用 wx.getUserInfo 直接获取头像昵称。

  • 第一次请求用户手动授权
<button open-type="getUserInfo" bindgetuserinfo="getUserInfo">
  获取头像昵称
</button>
getUserInfo: async function (e) {
  const { code } = await wx.login()
  const { rawData } = e.detail
  const user = await authing.loginByCode(code, { rawData })

  // 或者传 iv encryptedData
  // const { iv, encryptedData } = e.detail
  // const user = await authing.loginByCode(code, { iv, encryptedData })

  console.log(user)
}
  • 之后可以通过 wx.getUserInfo 自动获取
const { rawData } = await wx.getUserInfo()
const user = await authing.loginByCode(code, { rawData })
// 或者传 iv encryptedData
// const { iv, encryptedData } = e.detail
// const user = await authing.loginByCode(code, { iv, encryptedData })

¶ loginByPhone

通过微信手机号授权的方式登录。每次调用都需要用户手动授权。

  • 如果该手机号第一次注册,该会把该手机号与该微信账号绑定(不存在会创建)。
  • 如果该手机号之前注册过,将会返回该手机号对应的账号,并且将该手机号与当前微信账号绑定。

¶ 参数

  • code: 调用 wx.login() (opens new window) 获取的 code,不需要用户授权。必填。
  • iv: open-type 为 getPhoneNumber 的微信 Button 组件 (opens new window) 点击事件返回的 iv。必填.
  • encryptedData: open-type 为 getPhoneNumber 的微信 Button 组件 (opens new window) 点击事件返回的 encryptedData。必填.

使用此 API 前提需要严格依次执行以下 2 个步骤,任何一个步骤若重新获取,都将导致 code 值和 encryptedData 值不相匹配,而使得数据解密失败,最终导致无法正确获取到手机号。

  1. 调用 wx.login() (opens new window) 获取 code 值
  2. 使用微信 Button 组件 (opens new window)点击事件,获取 iv 和 encryptedData 值

¶ 示例

<button open-type="getPhoneNumber" bindgetphonenumber="getPhone">
  获取手机号
</button>
getPhone: async function(e) {
  const { code } = await wx.login()
  const { iv, encryptedData } = e.detail
  const data = await authing.loginByPhone(code, iv, encryptedData)
  console.log(data)
}

¶ getPhone

获取当前用户的手机号(不会使用该手机号注册或绑定账号)

¶ 参数

  • code: 调用 wx.login() (opens new window) 获取的 code,不需要用户授权。必填。
  • iv: open-type 为 getPhoneNumber 的微信 Button 组件 (opens new window) 点击事件返回的 iv。必填.
  • encryptedData: open-type 为 getPhoneNumber 的微信 Button 组件 (opens new window) 点击事件返回的 encryptedData。必填.

¶ 示例

<button open-type="getPhoneNumber" bindgetphonenumber="getPhone">
  获取手机号
</button>
getPhone: async function(e) {
  const { code } = await wx.login()
  const { iv, encryptedData } = e.detail
  const data = await authing.getPhone(code, iv, encryptedData)
  console.log(data)
}

返回的数据示例:

{
  "countryCode": "86",
  "phoneNumber": "188xxxx8888",
  "purePhoneNumber": "188xxxx8888",
  "openid": "o1p9H4wAgb9uTqpxG5Z1g0pIr3FE",
  "unionid": "o0pqE6Fbr5M-exSu_PeL_sjwN44U"
}

¶ updateAvatar

更新用户头像,该方法会自动调用 wx.chooseImage 获取图片并上传到 Authing 的 cdn,仅需一行代码调用。

¶ 示例

const { photo } = await authing.updateAvatar()
console.log(photo)

¶ 最佳实践

我们推荐用户第一次使用小程序的时候,使用 loginByCode 获取该小程序账号对应的 Authing 账号,如果该账号之前绑定了手机号,就无须再次请求用户授权手机号。如果该账号没有绑定手机号,再调用 loginByPhone 方法请求用户授权手机号。

用户登录之后,authing-wxapp-sdk 会将 token 写入小程序的 Storage,你可以调用 authing.checkLoginStatus() 判断该用户的 token 是否有效,当 token 失效的时候再重新登录。

¶ 错误处理

你可以使用 try catch 进行错误处理:

try {
  const user = await authing.loginByEmail('test@example.com', 'passw0rd')
} catch (error) {
  console.log(error.code) // 2004
  console.log(error.message) // 用户不存在
}

完整的错误代码请见此文档。

你还可以指定 onError 统一捕捉所有 Authing 请求异常,如使用 wx.showModal 等微信组件显示错误提示。

const authing = new AuthenticationClient({
  userPoolId,
  onError: (code, message) => {
    wx.showModal({
      content: message,
      showCancel: false,
    })
  },
})

¶ 获取帮助

请访问 Authing 论坛 (opens new window)。

  • 在 Authing 中配置小程序登录
  • GitHub 下载地址
  • 安装
  • 初始化
  • 使用方法
  • API Reference
  • 最佳实践
  • 错误处理
  • 获取帮助

用户身份管理

集成第三方登录
手机号闪验 (opens new window)
通用登录表单组件
自定义认证流程

企业内部管理

单点登录
多因素认证
权限管理

开发者

开发文档
框架集成
博客 (opens new window)
GitHub (opens new window)
社区用户中心 (opens new window)

公司

400 888 2106
sales@authing.cn
北京市朝阳区北辰世纪中心 B 座 16 层(总)
成都市高新区天府五街 200 号 1 号楼 B 区 4 楼 406 室(分)

京ICP备19051205号

beian京公网安备 11010802035968号

© 北京蒸汽记忆科技有限公司