04/09/2026 19:22:21

登录模块

一、概述

MSDK 登录功能为游戏提供便捷的登录功能：玩家可以使用 QQ、微信、Facebook、GameCenter、Google、游客账号等登录您的游戏。

[info] 注意：
更新到 MSDK5.20 及之后版本的业务需联系 QQ 游戏中心，取消业务在 QQ 游戏中心启动时 scheme 携带的 accesstoken、paytoken 字段，否则会造成游戏内登录态失效。平台取消配置后，旧版本也会失去快速登录能力，详情可咨询平台侧。

支持的渠道有：

  1. WeChat
  2. QQ
  3. Guest
  4. Facebook
  5. GameCenter
  6. Google
  7. Twitter
  8. Garena
  9. Line
  10. Apple
  11. HMS

二、接入向导

2.1 推荐登录流程

  1. 初始化 SDK
  2. 注册登录回调
  3. 调用自动登录
  4. 自动登录失败则选择登录指定渠道
  5. 完整登录流程

登录推荐流程

2.2 注册回调

1）功能描述
接受 MSDK 登录模块的回调，游戏需要注册回调函数进行处理；强烈建议游戏在应用启动函数中进行注册。

2）接口声明

C#
C++
/// <summary>
/// 登出回调、应用唤醒回调、视频号授权回调
/// </summary>
public static event OnMSDKRetEventHandler<MSDKBaseRet> LoginBaseRetEvent;

/// <summary>
//// 登录回调，包括 login、bind、autologin、switchuser 等
/// </summary>
public static event OnMSDKRetEventHandler<MSDKLoginRet> LoginRetEvent;
class MSDKLoginObserver
{

public:
    // 登录回调，包括 login、bind、autologin、switchuser 等
    virtual void OnLoginRetNotify(const MSDKLoginRet &loginRet) {};

    // 登出回调、应用唤醒回调、视频号授权回调
    virtual void OnBaseRetNotify(const MSDKBaseRet &baseRet) {};
};

3）示例代码

C#
C++
MSDKLogin.LoginRetEvent += OnLoginRetEvent;
MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;

private void OnLoginRetEvent(MSDKLoginRet loginRet)
{
	Debug.Log ("OnLoginRetNotify in Login");
	string methodTag = "";
	if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGIN) {
		methodTag = "Login";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_BIND) {
		methodTag = "Bind";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_AUTOLOGIN) {
		methodTag = "AutoLogin";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_QUERYUSERINFO) {
		methodTag = "QueryUserInfo";
	}
    // GetLoginRet 为同步接口，不需要在回调中处理
//      else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_GETLOGINRESULT) {
	//	methodTag = "GetLoginResult";
	//}
    else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGINWITHCONFIRMCODE) {
		methodTag = "LoginWithConfirmCode";
	}
	SampleInstance.showRetDialog(methodTag, loginRet);
}			

private void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
	Debug.Log ("OnBaseRetNotify in Login");

	if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_WAKEUP) {
		handleDiifAccount(baseRet);
	}
	else if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGOUT) {
		string methodTag = "Logout";
	    SampleInstance.showRetDialog(methodTag, baseRet);
	}
}

// 处理异账号的逻辑
private void handleDiifAccount (MSDKBaseRet baseRet)
{
    string methodTag = "异账号";
    switch (baseRet.RetCode) {
    case MSDKError.SUCCESS: { // 本地原有票据有效，使用原有票据登录
            SampleInstance.showRetDialog (methodTag, "使用原有票据登录，游戏无需处理");
            break;
        }
    case MSDKError.LOGIN_ACCOUNT_REFRESH: { // 新旧 openid 相同，票据不同。刷新登录票据
            SampleInstance.showRetDialog (methodTag, "新旧 openid 相同，票据不同。刷新登录票据，游戏无需处理");
            break;
        }
    case MSDKError.LOGIN_URL_USER_LOGIN: {// 本地无openid，拉起有票据，使用新票据登录
            SampleInstance.showRetDialog (methodTag, "本地无openid，拉起有票据，使用新票据登录，将自动触发切换游戏账号逻辑（SwitchUser），游戏需监控登录的回调结果");
            break;
        }
    case MSDKError.LOGIN_NEED_SELECT_ACCOUNT: {
            SampleInstance.ShowSwithUserDialog ();
            break;
        }
    case MSDKError.LOGIN_NEED_LOGIN: {
            SampleInstance.showRetDialog (methodTag, "票据均无效，进入登录页面");
        }
        break;
    default:
        break;
    }
}

//销毁的时候需要移除监听
private void OnDestroy()
{
	MSDKLogin.LoginRetEvent -= OnLoginRetEvent;
	MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent;
}
MSDKLogin::SetLoginObserver(new MSDKDemoBaseLoginObserver());

class  MSDKDemoBaseLoginObserver: public GCloud::MSDK::MSDKLoginObserver {
    // 登录回调，包括 login、bind、autologin、switchuser 等
public:
    virtual void OnLoginRetNotify(const GCloud::MSDK::MSDKLoginRet &loginRet) {、
        UMSDKDemoBase::showNormalAlert(loginRet);
    };
    // 登出回调、应用唤醒回调
    virtual void OnBaseRetNotify(const GCloud::MSDK::MSDKBaseRet &baseRet) {
        if (baseRet.methodNameID == kMethodNameWakeUp) {
            //异账号处理
            switch (baseRet.retCode) {
                case MSDKError::SUCCESS:
                	baseRet.append("使用原有票据登录，游戏无需处理");
                    break;
                case MSDKError::LOGIN_ACCOUNT_REFRESH:
                	baseRet.append("新旧 openid 相同，刷新登录票据，游戏无需处理");
                    break;
                case MSDKError::LOGIN_URL_USER_LOGIN:
                	baseRet.append("本地无openid，拉起有票据，使用新票据登录，将自动触发切换游戏账号逻辑（SwitchUser），游戏需监控登录的回调结果");
                    break;
                case MSDKError::LOGIN_NEED_SELECT_ACCOUNT:
                	baseRet.append("选择是否切换用户");
                    break;
                case MSDKError::LOGIN_NEED_LOGIN:
                	baseRet.append("票据均无效，进入登录页面");
                    break;
                default:
                    break;
            }
            return;
        }
        if (baseRet.retCode == MSDKError::NEED_REALNAME) {
            //实名制不需要处理
            return;
        }
        UMSDKDemoBase::showNormalAlert(ret);
    };
};

4）数据结构

MSDKLoginRet 详解
继承自 MSDKBaseRet，包含基础的信息

成员变量名称 类型 说明
openID string 用户ID
token string 用户凭证
tokenExpire long 过期时间
firstLogin int 是否首次登陆，未知：-1，是：1，否：0
regChannelDis string 首次注册的分发渠道
userName string 昵称
gender int 性别，未定义：0，男：1，女：2
微信和手Q渠道固定返回 0
pictureUrl string 头像链接
pf string pf值
pfkey string pfkey
realNameAuth bool 是否需要实名认证
channelID int 渠道ID
channel string 渠道名
channelInfo string 第三方渠道登录信息。该字段设计用途不可用于关键路径，有可能发生变更或删除。需要获取渠道 openid 请使用 “openID” 字段。如需使用第三方原样 openid，请联系MSDK助手进行配置。
confirmCode string 确认码，绑定失败后返回
confirmCodeExpireTime string 确认码过期时间戳

2.3 自动登录

1）功能描述
自动登录，MSDK 将自动获取本地登录态，并到 MSDK 服务器校验登录态是否有效，若本地无登录态缓存或者服务器返回登录态失效则回调自动登录失败的结果。

2）接口声明

C#
C++
public static void AutoLogin();
public static void AutoLogin();

3）示例代码

C#
C++
MSDKLogin.AutoLogin();
MSDKLogin::AutoLogin();

2.4 登录

1）功能描述
登录指定渠道，获取第三方平台登录态并到 MSDK 服务器鉴权，返回 MSDK 统一账号。
目前只有微信、QQ渠道支持二维码登录，详情见 2.13 扫码登录功能。

2）接口声明

C#
C++
public static void Login(string channel, string permissions = "", string subChannel = "", string extraJson = "")
public static void Login(const String &channel, const String &permissions, const String &subChannel, const String &extraJson)

3）参数说明

参数名称 参数类型 说明
channel string 渠道名字，大小写敏感。例如："WeChat"、"QQ"、"Facebook"
permissions string 登录授权的权限列表，可用逗号","分隔，例如微信："snsapi_userinfo,snsapi_friend"（仅供参考，业务按实际权限填入）， QQ 渠道所有权限传入"all"。详细权限请参考 MSDK 支持渠道列表 下对应渠道的详细说明
subChannel string 子渠道名字，大小写敏感。例如："Garena 包含的 Facebook 子渠道"
extraJson string 扩展字段，具体含义参考各渠道说明

4）示例代码

C#
C++
MSDKLogin.Login(MSDKChannel.WeChat);
std:string permissionList = "snsapi_userinfo,snsapi_friend,snsapi_message";
MSDKLogin::Login("WeChat", permissionList);

2.5 退出登录

1）功能描述
退出登录渠道

2）接口声明

C#
C++
public static void Logout(string channel = "", string subChannel = "", bool channelOnly = false)
public static void Logout(const String &channel = "", const String &subChannel = "", const bool channelOnly = false)

3）示例代码

C#
C++
MSDKLogin.Logout();
MSDKLogin::Logout();

2.6 获取登录态

1）功能描述
在游戏中，获取游戏的登录态信息

[warning] 此接口中已移除对登录态过期的校验。

2）接口声明

C#
C++
public static MSDKLoginRet GetLoginRet()
public static bool GetLoginRet(MSDKLoginRet &loginRet)

3）示例代码

C#
C++
MSDKLoginRet ret = MSDKLogin.GetLoginRet();
MSDKLoginRet ret;
MSDKLogin::GetLoginRet(ret);

2.7 视频号授权

1）功能描述
MSDK 封装视频号授权接口，通过调用 ChannelPermissionAuth 接口，当前微信要求传入 snsapi_channels_livestream，在 MSDK 的回调中获取 tdiAuthBuffer，用于后续的直播登录。 该功能不限制登录渠道及登录态，即可以跨平台调用该接口。

2）接口声明

C#
C++
public static void ChannelPermissionAuth(string channel, string permissions = "", string subChannel = "", string extraJson = "")
public static void  ChannelPermissionAuth(const String &channel, const String &permissions = "", const String &subChannel = "", const String &extraJson = "")

3）参数说明

参数名称 参数类型 说明
channel string 渠道名字，大小写敏感。当前仅支持："WeChat"
permissions string 视频号授权的权限列表，可用逗号","分隔，当前传入 "snsapi_channels_livestream"
subChannel string 子渠道名字，大小写敏感。暂不支持，传入 null 或不传入即可
extraJson string 扩展字段，具体含义参考各渠道说明。暂不支持，传入 null 或不传入即可

4）示例代码

在视频号授权回调 OnBaseRetNotify（C++）或 OnLoginBaseRetEvent（C#）接口中，通过判断 methodId 为 137（MSDK_CHANNEL_PERMISSION_AUTH）的授权返回作为直播授权的标记，具体使用可参照注册回调部分。 调用示例：

C#
C++
MSDKLogin.ChannelPermissionAuth(MSDKChannel.WeChat, "snsapi_channels_livestream");
MSDKLogin::ChannelPermissionAuth("WeChat", "snsapi_channels_livestream");

5）注意事项

  • 视频号授权当前仅支持微信视频号
  • 权限列表目前请填 snsapi_channels_livestream，这同时也是底层区分正常登录与权限申请的标记，后续微信要求的 permissions 可能会变动
  • 视频号授权回调中 tdiAuthBuffer 存在于 extraJson 字段中，以 Base64 的格式返回，通过 Json 解析获取，请使用标准的 Base64 解码后使用
  • 暂未支持超时回调逻辑
  • MSDK 仅做 tdiAuthBuffer 内容的返回，具体使用方法联系 MSDK助手 对接

2.8 切换游戏账号

1）功能描述
在出现异账号的情况，选择是否切换另一个账号登录。 异账号的情况：比如游戏用 QQ 登录，按 Home 键返回桌面后，又从微信游戏中心启动游戏，就会出现是否需要切换到微信账号的情况，称为异账号。 一般国内会出现异账号的情况。

2）接口声明

C#
C++
public static bool SwitchUser(bool useLaunchUser)
public static bool SwitchUser(bool useLaunchUser);

3）参数说明

参数名称 参数类型 说明
useLaunchUser bool 是否切换账号登录

[info] 注意
1.如果玩家选择切换账号，请将 useLaunchUser 置为 true。切换账号的结果将从游戏监控的登录回调处返回。
2.如果玩家选择不切换账号，请将 useLaunchUser 置为 false。MSDK 将自动触发自动登录逻辑，但不会回调给游戏

4）示例代码

C#
C++
MSDKLogin.SwitchUser(true);
MSDKLogin::SwitchUser(true);

2.9 绑定（仅支持海外）

1）功能描述
绑定的本质是指多个第三方账号共用一个 MSDK openid。一般使用场景为：游客登陆游戏，之后绑定 Facebook 或者 Google 账号。

2）接口声明

C#
C++
public static void Bind(string channel, string permissions = "", string subChannel = "", string extraJson = "")
public static void Bind(const String &channel, const String &permissions = "", const String &subChannel = "", const String &extraJson = "")

3）参数说明

参数名称 参数类型 说明
channel string 渠道信息，大小写敏感。比如“WeChat”、“QQ”、“Facebook”
permissions string 登录授权的权限列表，可用逗号","分隔，例如："user_info,inapp_friends"
subChannel string 子渠道名字，大小写敏感。比如 Garena 包含 Facebook 子渠道
extraJson string 扩展字段，具体含义参考各渠道说明

4）示例代码

C#
C++
MSDKLogin.Bind("WeChat");
MSDKLogin::Bind("WeChat");

2.10 使用确认码登录

1）功能描述
当登录或者绑定失败后，通过确认码再次尝试登录，避免让用户再次拉起授权登录界面。 确认码是后台返回的。

2）接口声明

C#
C++
public static void LoginWithConfirmCode (int actionType = 0, string confirmcode = "",string extraJson = "")
public static void LoginWithConfirmCode(const int actionType = 0, const String &confirmCode = "", const String &extraJson = "");

3）参数说明

参数名称 参数类型 说明
actionType int 0 一般登录；1 恢复渠道账号绑定的游客，并登录到游客
confirmcode string 后台返回的确认码
extraJson string 扩展字段，具体含义参考各渠道说明

4）示例代码

C#
C++
MSDKLogin.LoginWithConfirmCode(0, confirmcode);
MSDKLogin::LoginWithConfirmCode(0, confirmcode);

2.11 重置游客功能

1）功能描述
将游客重置，再次使用游客渠道登录时，将生成新的游客。

2）接口声明

C#
C++
public static void ResetGuest()
static void ResetGuest()

3）示例代码

C#
C++
MSDKLogin.ResetGuest();
MSDKLogin::ResetGuest();

2.12 预登陆功能（MSDKPIXCore V5.39.100 版本新增）

1）功能描述
在业务登录过程中，弹出《用户隐私协议》、《游戏服务协议》、《广告开关及协议》等协议流程，满足有特定要求的合规流程。如有接入需求，请联系 MSDK 产品咨询。

与一般流程不同的是，用户相关协议是在授权登录之后：

  • 用户点击登录按钮
  • 完成渠道授权
  • 弹出用户隐私协议，用户进行选择

注意：由于协议在登录流程之后，那么必须在登录之前不要上报用户相关的统计数据


2）接口声明

C#
C++
public static void LoginWithPrivacy(string channel, string permissions = "", string subChannel = "", string extraJson = "")
public static void LoginWithPrivacy(const String &channel, const String &permissions = "", const String &subChannel = "",const String &extraJson = "");

3）示例代码

例如，使用游客登录，调用预登陆接口的方式如下，登录流程中会按照策略弹窗（依赖中控策略），用户完成弹窗所要求的年龄协议选择确认后，才会登录成功。登录成功后会在登录回调中回调用户选择协议的结果。

C#
C++
MSDKLogin.LoginWithPrivacy("Guest");
MSDKLogin::LoginWithPrivacy("Guest");

2.13 扫码登录功能（MSDKPIXCore V5.41.100 版本新增）

1）功能描述

将 QQ、微信扫码登录能力封装成单独接口；使用二维码登录指定渠道，获取第三方平台登录态并到 MSDK 服务器鉴权，返回 MSDK 统一账号。目前只有微信、QQ 渠道支持二维码登录。

2）接口声明

C#
C++
public static void QRLogin(string channel, string permissions = "", string subChannel = "", string extraJson = "")
public static void QRLogin(const String &channel, const String &permissions, const String &subChannel, const String &extraJson);

3）参数说明

参数名称 参数类型 说明
channel string 渠道名字，大小写敏感。例如："WeChat"、"QQ"
permissions string 登录授权的权限列表，可用逗号","分隔，例如微信："snsapi_userinfo,snsapi_friend"（仅供参考，业务按实际权限填入）， QQ 渠道所有权限传入"all"。详细权限请参考 https://docs.msdk.qq.com/v5/zh-CN/Channel/ 下对应渠道的详细说明
subChannel string 子渠道名字，大小写敏感；微信、QQ渠道当前暂不涉及
extraJson string 扩展字段

4）示例代码

C#
C++
MSDKLogin.QRLogin("WeChat");
MSDKLogin::QRLogin("WeChat");

三、Editor环境下模拟登录

业务在开发阶段，需要在 Editor 环境上登录，进行联调。MSDK 目前提供模拟登录方案，以供业务在 Editor 环境联调。

请参考Editor环境下模拟登录

四、游客模式和绑定功能说明

4.1 功能描述

游客模式是指：每次用户登录均使用游客身份进行登录（如：无登录按钮直接进入游戏），在游戏内进行社交关系绑定达到账号关联以找回账号的一种登录方式。

游戏使用场景说明：

  1. 一般没有渠道登录按钮，直接使用游客进入游戏
  2. 在游戏新手教程、游戏设置界面中，有绑定社交关系账号功能，绑定账号用于拉取用户好友、找回账号

  3. 找回账号通过绑定触发，当被绑定账号存在进度时会返回错误及确认码，可通过确认码登录接口实现账号恢复

    游客绑定流程

4.2 登录

每次均使用游客渠道进行登录

4.3 绑定账号

通过绑定接口进行账号绑定。绑定账号可用于获取用户关系链及找回账号。

[info] 测试过程中，如需要解绑账号便于测试，请在企业微信联系 MSDK助手

4.4 恢复账号

  1. 通过绑定失败触发。当被绑定渠道存在账号进度时，三方错误码为：1403
  2. 通过判断错误码，使用确认码登录接口进行登录

4.5 重置进度

由于每次通过游客登录，用户如果想新启进度时，可以通过重置游客接口，删除当前游客（仅删除游客，可通过绑定的设计账号找回）

注意：如果游客没有绑定账号，重置进度将导致游客账号丢失

五、实名认证

根据国家法律法规的相关要求，网络游戏用户需要使用有效身份证件进行实名注册才可登录游戏。为了减轻游戏开发的负担，我们在游戏登录的过程中，封装了实名认证的操作。当登录后返回需要实名认证时，会自动拉起 WebView 组件，打开实名认证的网页。当玩家完成实名认证后，就可以登录游戏。实名认证过程，游戏无需额外的开发。

[info] 注意：
1、实名认证需要接入 WebView 组件
2、实名认证的网页是全屏展示，若玩家点击返回登录，则返回给游戏的登录态是登录不成功。
3、实名认证是由中控提供的相关服务
4、只有国内游戏才有实名认证过程，国外游戏没有

实名认证页面

版本说明

V 5.11 及以后版本

1）功能描述

增加了自检函数 ，帮助开发者排查SDK接入过程中遇到的问题，目前只支持微信渠道, 测试环境测试使用，正式环境不可以使用此功能

2) 接口代码

channel 填写 “WeChat“ ,其他字段为预留字段填空的字符串即可

C#
C++
public static void CheckUniversalLink(string channel, string subChannel = "", string extraJson = "");
MSDK_EXPORT_UE static void CheckUniversalLink(const String &channel, const String &subChannel = "", const String &extra = "");
`

3) 示例代码：

接口调用

C#
C++
MSDKLogin.CheckUniversalLink(("WeChat");
MSDKLogin::CheckUniversalLink("WeChat");

回调函数

C#
C++
// 登出回调、应用唤醒回调
 public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
    Debug.Log("OnBaseRetNotify in Login");
    if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_CHECK_UL)
    {
        // 处理回调检查 Universal Link 结果
    }
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(baseRet));
}
// 登出回调、应用唤醒回调
void OnBaseRetNotify(const MSDKBaseRet &baseRet) {
    if (baseRet.methodNameID == kMethodNameCheckUniversalLink) {
        // 处理回调检查 Universal Link 结果
    }
    handleCallback(baseRet, baseRet.methodNameID);
};

4) 字段说明

其中检测结果会放在 baseRet.ExtraJson 中，格式为一个 JSON 字符串

{
    "success":true,
    "errorInfo":"Universal Link check passed. The application is launched by WeChat via Universal Link",
    "step":"WXULCheckStepBackToCurrentApp",
    "suggestion":""
}

success 标识当前步骤检测结果
errorInfo 为提示信息
suggestion 为提示开发者的操作信息
step 的值说明:
    step = WXULCheckStepParams: 参数检查
    step = WXULCheckStepSystemVersion: 当前系统版本检查
    step = WXULCheckStepWechatVersion: 微信客户端版本检查
    step = WXULCheckStepSDKInnerOperation: 微信SDK内部操作检查
    step = WXULCheckStepLaunchWechat: App拉起微信检查
    step = WXULCheckStepBackToCurrentApp: 由微信返回当前App检查
    step = WXULCheckStepFinal: 最终检查

会依次回调这 7 个 step，当回调了WXULCheckStepFinal，说明检测通过，SDK 接入成功。 任一 step 回调的 success 为 false, 流程终止，后续不再回调，可以根据errorInfo的查看当前步骤错误的原因，根据 suggestion 修复问题.

七、PGS Recall API（海外）

7.1 PGS Recall API 介绍

7.1.1 什么是 PGS Recall API

借助 Recall API，游戏可以将 Recall 令牌存储在 Google 服务器中，从而管理 Google Play Games 服务 (PGS) 用户与其游戏内账号之间的关联。

7.1.2 Recall API 的使用场景

下面是一个使用 Recall API 的示例场景：

  1. 用户正在玩一款游戏，其开发者可以通过身份系统跟踪用户进度，并同时使用 PGS 和其他身份验证方法让用户登录其游戏。在此示例中，用户登录了其 PGS 账号 Laura，然后使用开发者的身份系统（名为 Racer94）创建了一个游戏内账号。当用户玩游戏时，开发者的游戏服务器会同步其进度。

  2. 此外，开发者还在 Google 上保存一个 Recall 令牌，该令牌与用户的游戏内账号相对应。Google 会根据用户的 PGS 玩家资料自动存储该 Recall 令牌。

  3. 现在，用户第一次决定在 Google Play 游戏电脑版平台上玩游戏。用户会自动使用其 PGS 账号进行身份验证，而游戏客户端会检查该 PGS 用户是否有任何进度。然后，游戏服务器会向 Google 查询，以确认是否有此 PGS 账号的任何令牌。由于存在，Google 会发回 Recall 令牌，游戏服务器使用该令牌查找用户的关联账号 Racer94，并恢复其游戏进度。由于使用 PGS 进行身份验证是一次顺畅的体验，因此无需用户输入用户名或密码，应用即会恢复用户的进度。此外，开发者可以将 PGS 身份验证与现有的身份系统搭配使用，并依赖 Google 来存储玩家进度与其 PGS 账号之间的关联。

7.1.3 存储与检索 Recall 令牌的流程

详细流程请参考：存储与检索 Recall 令牌流程

7.2 MSDK Recall API 接入功能

MSDK 封装了 PGS Recall 的 4 个接口，为游戏客户端提供以下核心能力：

  • 存储关联：将当前 PGS 用户与游戏内账号的关联关系（Recall Token）安全存储至 Google 服务器。
  • 查询关联：查询当前 PGS 用户已存储的 Recall Token，用于恢复游戏内账号。
  • 删除关联：移除当前 PGS 用户已存储的某个 Recall Token。
  • Recall 登录流程：利用查询返回的 Recall Token 快速登录游戏。

[info] 注意： 方案限制：仅支持 Android 设备且需具备 Google 服务框架。

1）功能描述
将当前 PGS 用户与游戏内账号的关联关系（Recall Token）安全存储至 Google 服务器。该接口为异步调用，结果通过 MSDKBaseRet 回调返回。

[danger] 注意： 本地需已有登录态，再调用此接口，否则会导致调用失败。

2）接口声明

C#
C++
public static void RecallLink(string channel, string extraJson = "");
public static void RecallLink(const String &channel, const String &extraJson = "");

3）参数说明

参数名称 参数类型 必填 说明
channel string 是 PGS Recall 功能支持渠道名称，目前仅支持 "GooglePlay"
extraJson string 否 扩展字段，具体含义请参考各渠道详细说明

4）示例代码

  • 接口调用：

C#
C++
MSDKLogin.RecallLink("GooglePlay","");
MSDKLogin::RecallLink("GooglePlay","");

  • 回调处理：

C#
C++
// 注册回调
MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;

// 存储关联结果通过 LoginBaseRetEvent 回调
public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
    // 针对 methodID 为 MSDK_RECALL_LINK 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (baseRet.methodNameID == (int)MSDKMethodNameID.MSDK_RECALL_LINK) {
        if (baseRet.retCode == MSDKError.SUCCESS) {
            // 存储关联成功
        } else {
            // 其他错误，请根据实际业务逻辑进行处理
        }
    } 
}

// 移除回调
MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent;
// 注册回调
MSDKLogin::SetLoginObserver(new MSDKBaseCallBacks());

// 存储关联结果通过 OnBaseRetNotify 回调
void MSDKBaseCallBacks::OnBaseRetNotify(const MSDKBaseRet &baseRet) {
    // 针对 methodID 为 kMethodNameRecallLink 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (baseRet.methodNameID == kMethodNameRecallLink) {
        if (baseRet.retCode == MSDKError::SUCCESS) {
            // 存储关联成功
        } else {
            // 其他错误，请根据实际业务逻辑进行处理
        }
    } 
}

7.2.2 查询关联(Recall Retrieve)

1）功能描述
查询当前PGS用户已存储的Recall Token，用于恢复游戏内账号，通常与 Recall Login 一起使用。 该接口为异步调用，结果通过 MSDKBaseRet 回调返回。

2）接口声明

C#
C++
public static void RecallRetrieve(string channel, string extraJson = "");
public static void RecallRetrieve(const String &channel, const String &extraJson = "");

3）参数说明

参数名称 参数类型 必填 说明
channel string 是 PGS Recall 功能支持渠道名称，目前仅支持 "GooglePlay"
extraJson string 否 扩展字段，具体含义请参考各渠道详细说明

4）示例代码

C#
C++
// 注册回调
MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;

// 查询关联结果通过 LoginBaseRetEvent 回调
public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
    // 针对 methodID 为 MSDK_RECALL_RETRIEVE 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (baseRet.methodNameID == (int)MSDKMethodNameID.MSDK_RECALL_RETRIEVE) {
        if (baseRet.retCode == MSDKError.SUCCESS) {
            // 查询关联成功
            // 处理 baseRet.extraJson 中 获取 link_info ，该字段的值是一个列表，即用户存储的所有关联信息
            // link_info 示例:[{"channel_id":4,"openid":"123123123","channel":"Facebook","user_name":"test1","picture_url":"https://xxxx/xxxx/xxxx.png","create_at":1765271313,"expire_at":1767863306}]
        } else {
            // 其他错误，请根据实际业务逻辑进行处理
        }
    } 
}

// 移除回调
MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent;
// 注册回调
MSDKLogin::SetLoginObserver(new MSDKBaseCallBacks());

// 查询关联结果通过 OnBaseRetNotify 回调
void MSDKBaseCallBacks::OnBaseRetNotify(const MSDKBaseRet &baseRet) {
    // 针对 methodID 为 kMethodNameRecallRetrieve 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (baseRet.methodNameID == kMethodNameRecallRetrieve) {
        if (baseRet.retCode == MSDKError::SUCCESS) {
            // 查询关联成功
            // 处理 baseRet.extraJson 中 获取 link_info ，该字段的值是一个列表，即用户存储的所有关联信息
            // link_info 示例:[{"channel_id":4,"openid":"123123123","channel":"Facebook","user_name":"test1","picture_url":"https://xxxx/xxxx/xxxx.png","create_at":1765271313,"expire_at":1767863306}]
        } else {
            // 其他错误，请根据实际业务逻辑进行处理
        }
    } 
}

1）功能描述
移除当前PGS用户已存储的某个Recall Token。该接口为异步调用，结果通过 MSDKBaseRet 回调返回。

2）接口声明

C#
C++
public static void RecallUnLink(string channel, string channelInfoJson, string extraJson = "");
public static void RecallUnLink(const String &channel, const String &channelInfoJson, const String &extraJson = "");

3）参数说明

参数名称 参数类型 必填 说明
channel string 是 PGS Recall 功能支持渠道名称，目前仅支持 "GooglePlay"
channelInfoJson string 是 渠道信息，从查询回调的 link_info 列表中选取
extraJson string 否 扩展字段，具体含义请参考各渠道详细说明

4）示例代码

  • 接口调用：

C#
C++
// channelInfoJson 需替换为实际业务所选的值，该值应从查询接口 RecallRetrieve 回调的 extraJson 中的 link_info 字段获取
MSDKLogin.RecallUnLink("GooglePlay","{\"channel_id\":4,\"openid\":\"123123123\",\"channel\":\"Facebook\",\"user_name\":\"test1\",\"picture_url\":\"https:\/\/xxxx\/xxxx\/xxxx.png\",\"create_at\":1765271313,\"expire_at\":1767863306}","");
// channelInfoJson 需替换为实际业务所选的值，该值应从查询接口 RecallRetrieve 回调的 extraJson 中的 link_info 字段获取
MSDKLogin::RecallUnlink("GooglePlay","{\"channel_id\":4,\"openid\":\"123123123\",\"channel\":\"Facebook\",\"user_name\":\"test1\",\"picture_url\":\"https:\/\/xxxx\/xxxx\/xxxx.png\",\"create_at\":1765271313,\"expire_at\":1767863306}","");

  • 回调处理：

C#
C++
// 注册回调
MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;

// 删除关联结果通过 LoginBaseRetEvent 回调
public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
    // 针对 methodID 为 MSDK_RECALL_UNLINK 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (baseRet.methodNameID == (int)MSDKMethodNameID.MSDK_RECALL_UNLINK) {
        if (baseRet.retCode == MSDKError.SUCCESS) {
            // 删除关联成功
        } else {
            // 其他错误，请根据实际业务逻辑进行处理
        }
    } 
}

// 移除回调
MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent;
// 注册回调
MSDKLogin::SetLoginObserver(new MSDKBaseCallBacks());

// 删除关联结果通过 OnBaseRetNotify 回调
void MSDKBaseCallBacks::OnBaseRetNotify(const MSDKBaseRet &baseRet) {
    // 针对 methodID 为 kMethodNameRecallUnlink 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (baseRet.methodNameID == kMethodNameRecallUnlink) {
        if (baseRet.retCode == MSDKError::SUCCESS) {
            // 删除关联成功
        } else {
            // 其他错误，请根据实际业务逻辑进行处理
        }
    }
}

7.2.4 关联登录(Recall Login)

1）功能描述
在查询后，从返回的数组中选择一个 Recall Token 快速登录游戏。该接口为异步调用，结果通过 MSDKLoginRet 回调返回。

2）接口声明

C#
C++
public static void RecallLogin(string channel,string channelInfoJson, string extraJson = "");
public static void RecallLogin(const String &channel,const String &channelInfoJson, const String &extraJson = "");

3）参数说明

参数名称 参数类型 必填 说明
channel string 是 PGS Recall 功能支持渠道名称，目前仅支持 "GooglePlay"
channelInfoJson string 是 渠道信息，从查询回调的 link_info 列表中选取
extraJson string 否 扩展字段，具体含义请参考各渠道详细说明

4）示例代码

  • 接口调用：

C#
C++
// channelInfoJson 需替换为实际业务所选的值，该值应从查询接口 RecallRetrieve 回调的 extraJson 中的 link_info 字段获取
MSDKLogin.RecallLogin("GooglePlay","{\"channel_id\":4,\"openid\":\"123123123\",\"channel\":\"Facebook\",\"user_name\":\"test1\",\"picture_url\":\"https:\/\/xxxx\/xxxx\/xxxx.png\",\"create_at\":1765271313,\"expire_at\":1767863306}","");
// channelInfoJson 需替换为实际业务所选的值，该值应从查询接口 RecallRetrieve 回调的 extraJson 中的 link_info 字段获取
MSDKLogin::RecallLogin("GooglePlay","{\"channel_id\":4,\"openid\":\"123123123\",\"channel\":\"Facebook\",\"user_name\":\"test1\",\"picture_url\":\"https:\/\/xxxx\/xxxx\/xxxx.png\",\"create_at\":1765271313,\"expire_at\":1767863306}","");

  • 回调处理：

C#
C++
// 设置登录回调
MSDKLogin.LoginRetEvent += OnLoginRetEvent;
MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;

// 针对登录回调结果进行相应逻辑处理
private void OnLoginRetEvent(MSDKLoginRet loginRet)
{
    // 针对 methodID 为 MSDK_RECALL_LOGIN 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (loginRet.methodNameID == (int)MSDKMethodNameID.MSDK_RECALL_LOGIN) {
        if (loginRet.retCode == MSDKError.SUCCESS) {
            // 关联登录成功，直接进入游戏
        } else {
            // 其他错误，跳转到登录界面引导用户选择渠道登录
        }
    } 
    ...
}

public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
    // 过程中可能触发中控策略弹窗
    // MSDK 会回调此错误码告知游戏目前正在弹窗
    // 一般的，游戏不需要处理此错误码
    if (baseRet.retCode == MSDKError.NEED_REALNAME) {
        // 实名制不需要处理
        return;
    }
}

// 移除登录回调
MSDKLogin.LoginRetEvent -= OnLoginRetEvent;
MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent;
// 设置登录回调
MSDKLogin::SetLoginObserver(new MSDKBaseCallBacks());

// 针对登录回调结果进行相应逻辑处理
void MSDKBaseCallBacks::OnLoginRetNotify(const MSDKLoginRet &loginRet) {
    // 针对 methodID 为 kMethodNameRecallLogin 的回调结果进行相应逻辑处理
    // 以下仅罗列了部分错误码，其他错误码及具体含义请参考 MSDKError 枚举说明
    if (loginRet.methodNameID == kMethodNameRecallLogin) {
        if (loginRet.retCode == MSDKError::SUCCESS) {
            // 关联登录成功，直接进入游戏
        } else {
            // 其他错误，跳转到登录界面引导用户选择渠道登录
        }
    }
}

void MSDKBaseCallBacks::OnBaseRetNotify(const MSDKBaseRet &baseRet) {
    // 过程中可能触发中控策略弹窗
    // MSDK 会回调此错误码告知游戏目前正在进行中控弹窗
    // 一般的，游戏不需要处理此错误码
    if (baseRet.retCode == MSDKError::NEED_REALNAME) {
        // 中控实名制不需要处理
        return;
    }
}

7.3 常见问题

更多常见设置问题请参考: 常见问题。

八、常见问题

  1. 为保障安全性，MSDK 登录态受有效期限制，一般情况下为 30 天 。由于更换设备登录、安全问题考量，登录态也会提前过期。
  2. MSDK 5.4.0000 版本开始（对应 GCloud 2.0.10 版本），移除登录防重入限制，但仍然保留登录超时检测。在 iOS9 以上系统，点击系统左上角的“返回xx游戏”或者通过 home 键直接返回游戏，不会有登录回调，此时再调用登录接口，可以重新拉起登录流程（旧版本会返回 InProgress 错误），上次的登录流程作废。
  3. 如何判断通过手Q/微信游戏中心拉起游戏？
    MSDK5.3.000 版本及之后的版本，通过 wakeup 回调里 ExtraJson 参数中的 param 字段判断，此字段会全量接收游戏中心返回的字段。手Q为：launchfrom:sq_gamecenter；微信Android为：_wxobject_message_ext:WX_GameCenter；微信iOS为：messageExt:WX_GameCenter。
  4. 如何获取米大师支付场景 token？
    手Q渠道使用 pay_token，需要解析登录回调 channelInfo 中的 pay_token 字段获取；
    其他渠道没有 pay_token，使用 MSDK 登录回调最外层的 token 字段。其中，国内游戏对此 token 不需要做任何处理。海外游戏需要使用 获取第三方渠道 token 接口 将此 token 转成对应的渠道 token。
    注意：推荐的支付鉴权方式为，获取第三方 openid 和 token 后按需到指定平台进行支付鉴权。
  5. 错误码
    见错误码说明。



Copyright © 2026 MSDK.
All rights reserved.

results matching ""

    No results matching ""