文档

# 用户信息

# 小程序登录

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

# 登录流程时序

# 说明：

  1. 调用 qq.login() 获取 临时登录凭证code ，并回传到开发者服务器。
  2. 调用 code2Session 接口，换取 用户唯一标识 OpenID 和 会话密钥 session_key。

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

注意：

  1. 会话密钥 session_key 是对用户数据进行 加密签名 的密钥。为了应用自身的数据安全，开发者服务器不应该把会话密钥下发到小程序，也不应该对外提供这个密钥。
  2. 临时登录凭证 code 只能使用一次

# UnionID 机制说明

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

# UnionID获取途径

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

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

# QQ开放平台绑定小程序流程

暂未提供

# 授权

部分接口需要经过用户授权同意才能调用。我们把这些接口按使用范围分成多个 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 <camera /> 组件 摄像头
setting.appMsgSubscribed qq.subscribeAppMsg 订阅消息（833以下版本使用scope.appMsgSubscribed，833及以上版本使用setting.appMsgSubscribed）
setting.addFriend 主动调用 qq.authorize 接口进行授权 允许被添加好友
scope.recentColorSign 主动调用 qq.authorize 接口进行授权 允许 添加最近浏览彩签

# 注意事项

  1. qq.authorize({scope: "scope.userInfo"})，不会弹出授权窗口，请使用 <button open-type="getUserInfo"/>
  2. 需要授权 scope.userLocation 时必须配置地理位置用途说明。

# 开放数据校验与解密

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

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

# 数据签名校验

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

  1. 通过调用接口（如 qq.getUserInfo）获取数据时，接口会同时返回 rawData、signature，其中 signature = sha1( rawData + session_key )
  2. 开发者将 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"
}
1
2
3
4
5
6
7
8
9

用户的 session-key：

HyVFkGl5F5OQWJZZaNzBBg==
1

用于签名的字符串为：

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

使用sha1得到的结果为

75e81ceda165f4ffa64f4068af58c64b8f54b88c
1

# 加密数据解密算法

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

  1. 对称解密使用的算法为 AES-128-CBC，数据采用PKCS#7填充。
  2. 对称解密的目标密文为 Base64_Decode(encryptedData)。
  3. 对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节。
  4. 对称解密算法初始向量 为Base64_Decode(iv)，其中iv由数据接口返回。

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

watermark参数说明：

参数 类型 说明
appid String 敏感数据归属 appId，开发者可校验此参数与自身 appId 是否一致
timestamp Int 敏感数据获取的时间戳, 开发者可以用于数据时效性校验

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

{
  "openId": "OPENID",
  "nickName": "NICKNAME",
  "avatarUrl": "AVATARURL",
  "unionId": "UNIONID",
  "watermark": {
    "appid": "APPID",
    "timestamp": TIMESTAMP
  }
}
1
2
3
4
5
6
7
8
9
10

注：

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

# 会话密钥 session_key 有效性

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

  1. qq.login 调用时，用户的 session_key 可能会被更新而致使旧 session_key 失效（刷新机制存在最短周期，如果同一个用户短时间内多次调用 qq.login，并非每次调用都导致 session_key 刷新）。开发者应该在明确需要重新登录时才调用 qq.login，及时通过 code2Session 接口更新服务器存储的 session_key。
  2. QQ不会把 session_key 的有效期告知开发者。我们会根据用户使用小程序的行为对 session_key 进行续期。用户越频繁使用小程序，session_key 有效期越长。
  3. 开发者在 session_key 失效时，可以通过重新执行登录流程获取有效的 session_key。使用接口 qq.checkSession可以校验 session_key 是否有效，从而避免小程序反复执行登录流程。
  4. 当开发者在实现自定义登录态时，可以考虑以 session_key 有效期作为自身登录态有效期，也可以实现自定义的时效性策略。

# 获取手机号

内测中，目前仅对部分被邀请的开发者开放

# 生物认证

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

← 转发 →