# SDK for 微信小程序

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 (opens new window) 中的所有方法,如获取、修改用户资料,添加用户自定义字段等。同时专门在小程序环境下使用的 通过微信授权获取用户手机号使用微信授权登录使用微信授权的手机号登录 等方法。

# 在 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

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

# 安装

从小程序基础库版本 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 初始化需要传入用户池 ID (userPoolId):

你可以在此了解如何获取 UserPoolId (opens new window),如果你对用户池的概念不是很了解,可以在此了解 Authing 系统的核心概念 (opens new window)

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

const authing = new AuthenticationClient({
  userPoolId: "YOUR_USERPOOL_ID",
})

完整参数列表如下:

  • userPoolId: 用户池 ID。
  • accessToken: 通过用户的 token 初始化 SDK 。
  • timeout: 请求超时时间,单位为毫秒,默认为 10000 (10 秒)。
  • onError: 错误处理函数,你可以用其来全局捕捉 Authing 客户端请求的所有异常。函数定义为:
(code: number, message: string, data: any) => void

完整的错误代码请见此文档 (opens new window)

  • 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 (opens new window) 中的所有方法,调用方法和 authing-js-sdk 完全一致。

# loginByCode

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

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

# 参数

  • code: 调用 wx.login() (opens new window) 获取的 code,不需要用户授权。必填。
  • options: 选填。
  • options.iv: open-typegetUserInfo微信 Button 组件 (opens new window) 点击事件返回的 ivivencryptedData 必须同时传递,Authing Server 会尝试从 ivencryptedData 中加密出用户资料。第一次需要用户手动授权。选填。
  • options.encryptedData: open-typegetUserInfo微信 Button 组件 (opens new window) 点击事件返回的 encryptedDataivencryptedData 必须同时传递,Authing Server 会尝试从 ivencryptedData 中加密出用户资料。第一次需要用户手动授权。选填。
  • options.rawData: open-typegetUserInfo微信 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

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

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

# 参数

# 示例

<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

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

# 参数

# 示例

<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": "176xxxx6754",
  "purePhoneNumber": "176xxxx6754",
  "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); // 用户不存在
}

完整的错误代码请见此文档 (opens new window)

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

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

# Contributors ✨

Thanks goes to these wonderful people (emoji key (opens new window)):


liaochangjiang


leinue


Meeken1998


vincentCheng

# 获取帮助

Join us on Gitter: #authing-chat (opens new window)