Web 端 SDK

APP 扫码 Web 端用到的 SDK 为 authing-js-sdk,请先了解如何在浏览器端安装以及初始化 SDK。

Authing SDK 提供两种方式接入:

  1. 直接使用 Authing 提供的扫码登录组件(startAppAuthScanning)。

  2. 只调用业务接口,自己实现 UI。

一键生成扫码登录组件

Authing.qrlogin.startScanning(options)

authing.startAppAuthScanning({
mount: '', // 可选,二维码挂载点,如不写则默认漂浮在文档中间
interval: 1000, // 可选,轮询间隔时间,默认为 800 ms
onPollingStart: (intervalNum) => {},
onResult: (res) => {},
onScanned: (userInfo) => {},
onSuccess: (data) => {
const { ticket, userInfo } = data;
},
onCancel: () => {},
onExpired: () => {},
onError: (data) => {},
onQRCodeShow: (qrcode) => {},
onQRCodeLoad: (qrcode) => {},
onQRCodeLoadFaild: (error) => {},
tips: '使用 <strong> APP </strong> 扫码登录',
scannedTips: '用户已扫码,等待确认',
canceledTips: '用户取消授权',
expiredTips: '二维码已过期',
successTips: '扫码成功',
retryTips: '重试',
failedTips: '网络出错,请重试'
})

参数

可选/必选

说明

mount <string>

可选

挂载点 Dom ID,如不写则默认漂浮在文档中间。

interval <number>

可选

轮询时间间隔,单位为 ms,默认为 800 ms。

onPollingStart <function>

可选

轮询开始时会被回调,只会回调一次。回调参数 intervalNum 为 setInterval 返回的数值,可使用 clearInterval 停止轮询。

如:clearInterval(intervalNum)

onResult <function>

可选

每次查询获取到数据都会回调,参数 res 示例如下:

{ "code": 200, "message": "查询二维码状态成功", "data": { "qrcodeId": "5e05f6027fde537d950f7da9", "scanned": false, "expired": false, "success": false, "canceled": false, "status": 0, "userInfo": {}, "description": "二维码还没有被扫描" }}

onScanned <function>

可选

用户扫码时会被回调,只会回调一次。回调参数 userInfo 只包含了用户昵称和头像,开发者可以将其展示在扫码框中。

onSuccess <function>

可选

用户同意授权之后将会被回调,只会回调一次之后轮询结束。参数 data 是一个字典,包含两个字段:ticket 和 userInfo。出于安全性考虑,默认情况下,userInfo 只会包含昵称(nickname)和头像(photo)两个字段,开发者也可以在后台配置使其返回完整用户信息,详情见自定义配置。 ticket 可以用来换取完整的用户信息,相关接口见下文。

onCancel <function>

可选

用户取消授权只会会被回调,只回调一次,之后轮询结束。

onExpired <function>

可选

二维码失效时被回调,只回调一次,之后轮询结束。

onError <function>

可选

每次查询失败时都会回调。回调参数 data 示例如 {"code": 2241,"message": "二维码不存在","data": null}完整错误代码请见完整错误代码页

onQRCodeLoad <function>

可选

二维码首次成功加载时回调。回调参数 qrcode 是一个字典,包含两个字段:qrcodeId、qrcodeUrl。

onQRCodeShow <function>

可选

二维码首次出现在页面上时回调。回调参数 qrcode 同上。

onQRCodeLoadFaild <function>

可选

二维码加载失败时会被回调。

下面是一个最简的调用:一共只需要 5 行代码。

authing.qrlogin.startScanning({
onSuccess(userInfo) {
localStorage.setItem('token', userInfo.token);
}
})

扫码组件示例:

生成二维码

Authing.qrlogin.geneCode(options)

authing.geneQRCode({
scene: "APP_AUTH",
userDefinedData: {
customVar1: "xxx",
customVar2: "xxx"
}
})

参数

可选/必选

说明

scene

必选

场景值。为常量值,填 APP_AUTH。

userDefinedData

可选

自定义数据。类型为任意对象。

请求示例:

const res = await authing.qrlogin.geneCode({
scene: "APP_AUTH",
userDefinedData: {
customVar1: "xxx",
customVar2: "xxx"
}
})
if(res.code === 200){
const { qrcodeId, qrcodeUrl } = res.data
}

返回结果:

{
"code": 200, // 200 表示正常
"message": "生成二维码成功",
"data": {
"qrcodeId": "5e061366445c9985e5bf890a", // 二维码 ID
"qrcodeUrl": "https://usercontents.authing.co/qrcode/5e061366445c9985e5bf890a.png" // 二维码链接
}
}

使用在线二维码解码工具 查看二维码数据如下:其中 customVar1 和 customVar2 保存到了 userDefinedData 对象中。

{
"scene":"APP_AUTH",
"qrcodeId":"5e06c47da6b47a9433f8b3be",
"userPoolId":"59f86b4832eb28071bdd9214",
"createdAt":"2019-12-28T02:57:01.697Z",
"expireAt":"2019-12-28T02:59:01.697Z",
"userDefinedData":{
"customVar1":"xxx",
"customVar2":"xxx"
}
}

查询二维码状态

Authing.qrlogin.checkCodeStatus(options)

const res = await authing.qrlogin.checkCodeStatus({
qrcodeId: "xxxxx",
scene: "APP_AUTH"
})

参数

可选/必选

说明

qrcodeId

必选

二维码 ID

scene

必选

场景值。为常量值,填 APP_AUTH。

请求示例:

authing.qrlogin.checkCodeStatus({
qrcodeId: "xxxxx",
scene: "APP_AUTH"
}).then(res => {
console.log(res)
})

返回结果示例:

{
"code": 200, // 业务状态码,200 表示正常
"message": "查询二维码状态成功",
"data": {
"qrcodeId": "5e061489445c9985e5bf890d",
"scanned": false,
"expired": false,
"success": false,
"canceled": false,
"status": 0,
"userInfo": {},
"ticket": "", // 该字段不一定会有
"description": "二维码还没有被扫描"
}
}

请求结果字段说明:

  • scanned: 二维码是否已经被扫描

  • expired:二维码是否已经过期

  • success:用户是否成功授权

  • canceled:用户是否取消授权

  • status

    • 0: 未知状态,即还未扫码,或者已经扫码但用户还没有点击同意授权或者取消授权。

    • 1: 用户同意授权

    • -1: 用户取消授权

  • userInfo:

    • 默认情况下,在用户扫码之后,会包含昵称(nickname)和头像(photo)两个字段

    • 开发者也可以配置返回完整用户信息(包括登录凭证 token)

  • ticket:用于换取完整用户资料。此字段只有在用户同意授权之后才会出现。详情见下文。

轮询二维码状态

Authing.qrlogin.pollingCodeStatus(options)

此接口为 checkQRCodeStatus 的封装。

authing.qrlogin.pollingCodeStatus({
qrcodeId,
scene: 'APP_AUTH',
interval: 1000,
onPollingStart: function (intervalNum) {
console.log("Start polling for qrcode status: ", intervalNum)
// clearInterval(intervalNum)
},
onResult: function (res) {
console.log("Got qrcode latest result: ", res)
},
onScanned: function (userInfo) {
console.log("User scanned qrcode: ", userInfo)
},
onSuccess: function (data) {
const { ticket, userInfo } = data;
console.log(`User confirmed authorization: ticket = ${ticket}`, userInfo)
// 获取用户信息
authing.exchangeUserInfoWithTicket(ticket).then(res => {
const { code } = res
if (code === 200) {
console.log("Exchange userInfo success: ", res)
} else {
console.log("Exchange userInfo failed: ", res)
}
})
},
onCancel: function () {
console.log("User canceled authorization")
},
onExpired: function () {
console.log("QRCode has expired.")
},
onError: function (data) {
console.log("Chcek qrcode status failed: ", data)
}
})

参数说明:

参数

可选/必选

说明

onPollingStart <function>

可选

轮询开始时会被回调,只会回调一次。回调参数 intervalNum 为 setInterval 返回的数值,可使用 clearInterval 停止轮询。

如:clearInterval(intervalNum)

onResult

可选

每次查询获取到数据都会回调,参数 res 示例如下:

{ "code": 200, "message": "查询二维码状态成功", "data": { "qrcodeId": "5e05f6027fde537d950f7da9", "scanned": false, "expired": false, "success": false, "canceled": false, "status": 0, "userInfo": {}, "description": "二维码还没有被扫描" }}

onScanned

可选

用户扫码时会被回调,只会回调一次。回调参数 userInfo 只包含了用户昵称和头像,开发者可以将其展示在扫码框中。

onSuccess

可选

用户同意授权之后将会被回调,只会回调一次之后轮询结束。参数 data 是一个字典,包含两个字段:ticket 和 userInfo。出于安全性考虑,默认情况下,userInfo 只会包含昵称(nickname)和头像(photo)两个字段,开发者也可以在后台配置使其返回完整用户信息,详情见自定义配置。 ticket 可以用来换取完整的用户信息,相关接口见下文。

onCancel

可选

用户取消授权只会会被回调,只回调一次,之后轮询结束。

onExpired

可选

二维码失效时被回调,只回调一次,之后轮询结束。

onError

可选

每次查询失败时都会回调。回调参数 data 示例如 {"code": 2241,"message": "二维码不存在","data": null}完整错误代码请见完整错误代码页

一个完整的扫码流程

ticket 换用户信息接口

Authing.qrlogin.exchangeUserInfo(ticket)

const res = authing.qrlogin.exchangeUserInfo(ticket)

参数说明:

参数

可选/必选

说明

ticket

必选

从二维码状态查询接口得到的 ticket

调用示例:

authing.qrlogin.exchangeUserInfo(ticket).then(res => {
const { code } = res
if (code === 200) {
console.log("Exchange userInfo success: ", res.data)
} else {
console.log("Exchange userInfo failed: ", res.data)
}
})

返回结果:

{
"code":200,
"message":"换取用户信息成功",
"data":{
"_id":"5e05bbf2d51b3761d5c71070",
"email":"983132@qq.com",
"emailVerified":false,
"oauth":"",
"registerMethod":"default:username-password",
"username":"983132@qq.com",
"nickname":"",
"company":"",
"photo":"https://usercontents.authing.co/authing-avatar.png",
"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImVtYWlsIjoiOTgzMTMyQHFxLmNvbSIsImlxxxxxxxxx",
"phone":"",
"tokenExpiredAt":"2020-01-11T08:08:18.000Z",
"loginsCount":1,
"lastIP":"::1",
"signedUp":"2019-12-27T08:08:18.115Z",
"blocked":false,
"isDeleted":false
}
}

注意:默认情况下,此接口只允许在服务器端调用,即需要使用用户池密钥初始化之后。

ticket 默认有效时间为 300 s。

开发者可在 Authing 控制台 基础配置 -> 基础设置 -> App 扫码登录 Web 自定义配置 处修改。详情见自定义配置项页。