小程序登录

小程序可以通过QQ官方提供的登录能力方便地获取QQ提供的用户身份标识，快速建立小程序内的用户体系。

登录流程时序

说明：

调用 qq.login() 获取 临时登录凭证code ，并回传到开发者服务器。

调用 code2Session 接口，换取 用户唯一标识 OpenID 和 会话密钥 session_key。

之后开发者服务器可以根据用户标识来生成自定义登录态，用于后续业务逻辑中前后端交互时识别用户身份。

注意：

会话密钥 session_key 是对用户数据进行 加密签名 的密钥。为了应用自身的数据安全，开发者服务器不应该把会话密钥下发到小程序，也不应该对外提供这个密钥。

临时登录凭证 code 只能使用一次

UnionID 机制说明

如果开发者拥有多个移动应用、网站应用、小程序，可通过 UnionID 来区分用户的唯一性，因为只要是QQ互联帐号下的移动应用、网站应用、小程序，用户的 UnionID 是唯一的。换句话说，同一用户，对同一个QQ互联平台下的不同应用，unionid是相同的。

UnionID获取途径

绑定了开发者帐号的小程序，可以通过以下途径获取 UnionID。

调用接口 qq.getUserInfo，从解密数据中获取 UnionID。注意本接口需要用户授权，请开发者妥善处理用户拒绝授权后的情况。

授权

部分接口需要经过用户授权同意才能调用。我们把这些接口按使用范围分成多个 scope ，用户选择对 scope 来进行授权，当授权给一个 scope 之后，其对应的所有接口都可以直接使用。

部分接口需要获得用户授权同意后才能调用。此类接口调用时：

如果用户未接受或拒绝过此权限，会弹窗询问用户，用户点击同意后方可调用接口；

如果用户已授权，可以直接调用接口；

如果用户已拒绝授权，则不会出现弹窗，而是直接进入接口 fail 回调。请开发者兼容用户拒绝授权的场景。

获取用户授权设置

开发者可以使用 qq.getSetting 获取用户当前的授权状态。

打开设置界面

用户可以在小程序设置界面(「右上角」 - 「关于」 - 「右上角」 - 「设置」)中控制对该小程序的授权状态。

开发者可以调用 qq.openSetting 打开设置界面，引导用户开启授权。

提前发起授权请求

开发者可以使用 qq.authorize 在调用需授权 API 之前，提前向用户发起授权请求。

scope 列表

scope

对应接口

描述

scope.userInfo

qq.getUserInfo

用户信息

scope.userLocation

qq.getLocation, qq.chooseLocation

地理位置

scope.address

qq.chooseAddress

通讯地址

scope.invoiceTitle

qq.chooseInvoiceTitle

发票抬头

scope.invoice

qq.chooseInvoice

获取发票

scope.qqrun

qq.getQQRunData

QQ运动步数

scope.record

qq.startRecord

录音功能

scope.writePhotosAlbum

qq.saveImageToPhotosAlbum, qq.saveVideoToPhotosAlbum

保存到相册

scope.camera

组件

摄像头

setting.appMsgSubscribed

qq.subscribeAppMsg

订阅消息(833以下版本使用scope.appMsgSubscribed，833及以上版本使用setting.appMsgSubscribed)

setting.addFriend

主动调用qq.authorize接口进行授权

注意事项

qq.authorize({scope: "scope.userInfo"})，不会弹出授权窗口，请使用

需要授权 scope.userLocation 时必须配置地理位置用途说明。

开放数据校验与解密

小程序可以通过各种前端接口获取QQ提供的开放数据。考虑到开发者服务器也需要获取这些开放数据，QQ会对这些数据做签名和加密处理。开发者后台拿到开放数据后可以对数据进行校验签名和解密，来保证数据不被篡改。

签名校验以及数据加解密涉及用户的会话密钥 session_key。 开发者应该事先通过 qq.login 登录流程获取会话密钥 session_key 并保存在服务器。为了数据不被篡改，开发者不应该把 session_key 传到小程序客户端等服务器外的环境。

数据签名校验

为了确保开放接口返回用户数据的安全性，QQ会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验，确保数据的完整性。

通过调用接口(如 qq.getUserInfo)获取数据时，接口会同时返回 rawData、signature，其中 signature = sha1( rawData + session_key )

开发者将 signature、rawData 发送到开发者服务器进行校验。服务器利用用户对应的 session_key 使用相同的算法计算出签名 signature2 ，比对 signature 与 signature2 即可校验数据的完整性。

如 qq.getUserInfo的数据校验：

接口返回的rawData：

{

"nickName": "Band",

"gender": 1,

"language": "zh_CN",

"city": "Guangzhou",

"province": "Guangdong",

"country": "CN",

"avatarUrl": "http://thirdqq.qlogo.cn/qqapp/55107C3B8501CD7CBD90AEE4626E6D17/40"

}

用户的 session-key：

HyVFkGl5F5OQWJZZaNzBBg==

用于签名的字符串为：

{"nickName":"Band","gender":1,"language":"zh_CN","city":"Guangzhou","province":"Guangdong","country":"CN","avatarUrl":"http://thirdqq.qlogo.cn/qqapp/55107C3B8501CD7CBD90AEE4626E6D17/40"}HyVFkGl5F5OQWJZZaNzBBg==

使用sha1得到的结果为

75e81ceda165f4ffa64f4068af58c64b8f54b88c

加密数据解密算法

接口如果涉及敏感数据(如qq.getUserInfo当中的 openId 和 unionId)，接口的明文内容将不包含这些敏感数据。开发者如需要获取敏感数据，需要对接口返回的加密数据(encryptedData) 进行对称解密。 解密算法如下：

对称解密使用的算法为 AES-128-CBC，数据采用PKCS#7填充。

对称解密的目标密文为 Base64_Decode(encryptedData)。

对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节。

对称解密算法初始向量 为Base64_Decode(iv)，其中iv由数据接口返回。

另外，为了应用能校验数据的有效性，会在敏感数据加上数据水印( watermark )

watermark参数说明：

|参数|类型|说明|

|appid|String|敏感数据归属 appId，开发者可校验此参数与自身 appId 是否一致|

|timestamp|Int|敏感数据获取的时间戳, 开发者可以用于数据时效性校验|

如接口 qq.getUserInfo 敏感数据当中的 watermark：

{

"openId": "OPENID",

"nickName": "NICKNAME",

"gender": GENDER,

"city": "CITY",

"province": "PROVINCE",

"country": "COUNTRY",

"avatarUrl": "AVATARURL",

"unionId": "UNIONID",

"watermark": {

"appid": "APPID",

"timestamp": TIMESTAMP

}

}

注：

解密后得到的json数据根据需求可能会增加新的字段，旧字段不会改变和删减，开发者需要预留足够的空间

会话密钥 session_key 有效性

开发者如果遇到因为 session_key 不正确而校验签名失败或解密失败，请关注下面几个与 session_key 有关的注意事项。

qq.login 调用时，用户的 session_key 可能会被更新而致使旧 session_key 失效(刷新机制存在最短周期，如果同一个用户短时间内多次调用 qq.login，并非每次调用都导致 session_key 刷新)。开发者应该在明确需要重新登录时才调用 qq.login，及时通过 code2Session 接口更新服务器存储的 session_key。

QQ不会把 session_key 的有效期告知开发者。我们会根据用户使用小程序的行为对 session_key 进行续期。用户越频繁使用小程序，session_key 有效期越长。

开发者在 session_key 失效时，可以通过重新执行登录流程获取有效的 session_key。使用接口 qq.checkSession可以校验 session_key 是否有效，从而避免小程序反复执行登录流程。

当开发者在实现自定义登录态时，可以考虑以 session_key 有效期作为自身登录态有效期，也可以实现自定义的时效性策略。

获取手机号

暂不支持,后续版本将进行更新

生物认证

暂不支持,后续版本将进行更新