小游戏登录指南

名词解释

登录流程中涉及的相关名词解释如下：

名词	解释	获取方式	有效期
app_id	小游戏唯一标识	从快手海外开发者平台获取	不变
app_secret	小游戏密钥	从快手海外开发者平台获取	不变
code	临时登录凭证	小游戏前端调用 ks.login 获取	5分钟
open_id	用户唯一身份标识	小游戏服务器从快手服务器获取	单个小游戏内不变
session_key	会话密钥	小游戏服务器从快手服务器获取，用于后续接口签名和校验数据完整性使用	由快手服务器维护，活跃用户自动延长有效期
自定义登录态	小游戏登录态，区别于快手登录态	小游戏服务器自己定义生成，与 open_id、session_key 关联

登陆流程

登陆流程时序图如下：

说明

1. 小游戏服务器应妥善保管 session_key，勿将该字段下发至小游戏前端，避免会话密钥泄露，保证数据安全；此外小游戏前端调用 ks.login 接口会导致 session_key 被刷新，存储在小游戏服务端的旧 session_key 失效，所以前端应谨慎判断调用 ks.login 的时机；
2. 每个快手用户在单个小游戏内 open_id 始终不变，小游戏服务器可据此生成自定义登录态，用于后续业务中前后端交互时识别用户身份；
3. 临时登录凭证 code 仅单次有效，且有有效期限制，小游戏服务器收到后应及时调用登录凭证校验接口 code2session 换取 open_id 和 session_key 。
4. ks.login 的调用时机：在游戏本地存在自定义登录态时，可以直接使用自定义登录态发起业务请求，当自定义登录态失效时才需要重新调用 ks.login ，调用流程伪代码如下：

if (自定义登录态有效){
  发起业务请求 // 携带自定义登录态
} else {
  // 先通过登录流程获取自定义登录态，再发起业务请求
  ks.login({
    success : function(res) {
       通过游戏服务器获取自定义登录态 // 携带 res.code
       发起业务请求 // 携带自定义登录态
    },
    fail : function() {
      //错误处理
    }
  });
}

5. ks.checkSession 的调用时机：游戏需要使用session_key时，可以调用 ks.checkSession 检查快手小游戏服务器侧登录态是否过期，如果过期需要调用ks.login重新获取用户登陆态，调用流程伪代码如下：

ks.checkSession({
  success () {
    //session_key 未过期，并且在本生命周期一直有效
  },
  fail () {
    // session_key 已经失效，需要重新执行登录流程
    ks.login() //重新登录
  }
})