游戏引擎 / 系统课时

登录能力怎样兼容多个平台

登录能力怎样兼容多个平台

同一套 Cocos Creator 3.8 游戏发布到 Web、原生应用和微信小游戏后,拿到的登录凭证、SDK 回调和恢复时机都不同。本课把差异关进平台适配器,让大厅、背包和存档模块只依赖统一会话。

学习目标

  • 区分平台临时凭证与游戏服务端签发的会话。
  • 实现可替换的登录适配器和会话状态管理。
  • 处理登录失败、过期、前后台切换与重新登录。

凭证不同,会话却要相同

不要让业务模块分别解析微信 code、原生 SDK 票据和 Web 表单结果。它们只是证明身份的输入,并不是可以直接用于游戏接口的统一访问令牌。

运行环境 客户端获取的内容 服务端职责
Web 用户提交的账号凭据或 OAuth 授权结果 校验凭据或授权结果
微信小游戏 wx.login 返回的临时 code 向微信服务端兑换并校验身份
Android/iOS 原生 所接渠道 SDK 的授权码或身份票据 按渠道规则验证签名、受众与有效期

三种方式最终都由游戏自己的服务端返回同一数据结构:userId、accessToken、expiresAtMs。其中 expiresAtMs 是毫秒时间戳;业务层只判断会话是否有效,不依赖 openid 或某个渠道字段。原生平台是否有静默登录,取决于实际接入的渠道 SDK,不能假设所有原生包都有同一个登录 API。

从平台入口到统一会话

登录界面向 LoginAdapter 索要凭证,再交给 AuthGateway 请求服务端验证;只有服务端验证成功,SessionService 才把状态从 authorizing 改成 authenticated。微信 code 应一次性尽快使用,既不作为业务 Token,也不写入持久化存储。

登录适配器与服务端会话的数据流

在 Cocos Creator 中验证适配器

新建 CrossPlatformLoginDemo.ts,挂到场景内任意激活节点。示例的 Web 通道和服务端兑换使用显式模拟实现,可在编辑器预览中验证状态变化;微信通道则调用真实 wx.login 获取临时凭证。原生渠道必须另外注入对应 SDK 适配器。

ts
import { _decorator, Component } from 'cc';
import { NATIVE, WECHAT } from 'cc/env';

const { ccclass } = _decorator;

// 未引入微信类型包时,为小游戏入口补充最小声明。
declare const wx: {
  login(options: {
    success: (res: { code?: string }) => void;
    fail: (err: unknown) => void;
  }): void;
};

type Proof = { provider: 'web' | 'wechat'; credential: string };
type Session = { userId: string; accessToken: string; expiresAtMs: number };
type State = 'signedOut' | 'authorizing' | 'authenticated' | 'expired' | 'error';

interface LoginAdapter {
  getProof(): Promise<Proof>;
}

class WebDemoAdapter implements LoginAdapter {
  async getProof(): Promise<Proof> {
    // 仅用于验证接线;正式 Web 登录由表单或 OAuth 提供真实凭据。
    return { provider: 'web', credential: 'local-demo' };
  }
}

class WechatAdapter implements LoginAdapter {
  getProof(): Promise<Proof> {
    return new Promise((resolve, reject) => {
      wx.login({
        success: (res) => res.code
          ? resolve({ provider: 'wechat', credential: res.code })
          : reject(new Error('登录未返回 code')),
        fail: reject,
      });
    });
  }
}

class DemoGateway {
  async exchange(proof: Proof): Promise<Session> {
    // 模拟服务端响应,不做真实身份校验。
    if (!proof.credential) throw new Error('缺少登录凭证');
    return {
      userId: 'demo-user',
      accessToken: 'DEMO_ONLY',
      expiresAtMs: Date.now() + 60000,
    };
  }
}

class SessionService {
  state: State = 'signedOut';
  session: Session | null = null;

  async login(adapter: LoginAdapter): Promise<Session> {
    this.state = 'authorizing';
    try {
      const proof = await adapter.getProof();
      const next = await new DemoGateway().exchange(proof);
      if (!next.accessToken || next.expiresAtMs <= Date.now()) {
        throw new Error('会话无效或已过期');
      }
      this.session = next;
      this.state = 'authenticated';
      return next;
    } catch (err) {
      this.session = null;
      this.state = 'error';
      throw err;
    }
  }

  isActive(): boolean {
    if (this.session && Date.now() >= this.session.expiresAtMs) {
      this.session = null;
      this.state = 'expired';
    }
    return this.state === 'authenticated';
  }

  logout(): void {
    this.session = null;
    this.state = 'signedOut';
  }
}

@ccclass('CrossPlatformLoginDemo')
export class CrossPlatformLoginDemo extends Component {
  start(): void {
    if (NATIVE) {
      console.log('原生端请接入对应渠道的 LoginAdapter');
      return;
    }
    const adapter = WECHAT ? new WechatAdapter() : new WebDemoAdapter();
    const auth = new SessionService();
    void auth.login(adapter).then((session) => {
      console.log(`state=${auth.state}, user=${session.userId}, active=${auth.isActive()}`);
      auth.logout();
      console.log(`state=${auth.state}`);
    }).catch((err) => console.error('login failed', err));
  }
}

预期输出(Web 编辑器预览):

text
state=authenticated, user=demo-user, active=true
state=signedOut

过期、切后台与异常怎么处理

会话状态至少区分未登录、授权中、已登录、已过期和错误。页面恢复前台时,平台适配层发出统一恢复事件;会话层检查本地过期时间,必要时调用后端刷新或重新授权。本地时间检查只能做快速判断,服务端才是权限是否有效的最终依据。

验收时依次模拟重复点击登录、用户取消授权、SDK 返回空凭证、断网、Token 过期、切后台再恢复和主动退出。登录请求未结束时禁用重复提交;失败要清理过期会话并允许重试,不能把上次成功用户残留在 UI。敏感凭证不要写入普通日志,长期凭证只应保存在经安全设计的服务端或平台安全存储中。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

登录能力怎样兼容多个平台

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通