访客账户绑定

概述

有些游戏允许用户在没有平台账户(Garena / Facebook / Google账户等)的情况下使用访客账户玩游戏。

如果用户想要获得更好的游戏体验，例如与平台好友互动、跨设备使用相同的游戏账号，他们可以将自己的访客账户与平台账户绑定。

这个文档介绍了访客账户绑定的流程。

流程

• 访客绑定由游戏侧发起
• 进行最终绑定步骤前，游戏侧需确保平台账号在游戏中没有角色（没有玩过游戏）
• 游戏侧需检查绑定结果，如果绑定成功，游戏客户端需调用MSDK接口清理本地访客账户以完成绑定流程
• 游戏侧调用GOP服务器访客绑定API v2 /game/guest/swap 成功完成访客绑定后，用户的OpenID保持不变。

协作与流程

步骤：

1. 游戏客户端调用MSDK API开始访客绑定流程。
2. MSDK跳转平台app或网页，让用户完成登录授权。
3. 用户授权后，MSDK获得新平台账户的access token和OpenID。
4. MSDK将新的access token和OpenID返回给游戏客户端（新OpenID的生成基于所用平台）。
5. 游戏客户端将新的access token和OpenID传给游戏服务器，请求访客绑定。
6. 游戏服务器检查OpenID在游戏中无角色（确保此平台账号此前未玩过该游戏）。
7. 游戏服务器调用GOP服务器API v2 (/game/guest/swap)请求访客绑定。
8. GOP服务器处理访客绑定请求，并返回结果给游戏服务器。如果访客绑定成功，原先的访客账户将无法被使用。
9. 游戏服务器将访客绑定接口回传给游戏客户端。
10. 如果访客绑定成功，游戏客户端需调用MSDK API重置本地的访客账户，并使用新的已绑定的平台账号继续游戏。如果访客绑定失败，游戏客户端无需调用MSDK API，可使用原先的访客账号继续游戏。

注：步骤4的新OpenID只用于检查脸书账号下有无游戏档案，用户OpenID不受影响。

时序图

获取绑定信息

获取绑定信息API将要求用户登录到一个平台，并在回调中返回登录信息，这些信息可以用于执行与GOP的绑定操作。

以下代码示例展示了如何获取平台认证令牌，这是访客绑定流程的第一步。

Android

accountManager.getGuestBindingTokenV2(platformType, callback);

iOS

// 请求平台用户认证
[MSDKLoginManager.shared getGuestBindingTokenV2ForPlatform:platform
                                         completion:^(MSDKLoginRet *loginRet) {
    NSLog(@"登录结果 %@", loginRet);
                
    // 通知GOP您希望使用访客交换API将当前访客绑定到该令牌

    // 以下是MSDKLoginRet.flag可能的结果：
    // - MSDKeFlagSucc
    // - MSDKeFlagAppNotInstalled
    // - MSDKeFlagUserCancalled
    // - MSDKeFlagNetworkException
    // - MSDKeFlagUnkownError
}];

Unity

// 请求平台用户认证
GMSDKHandler.BindClient.GetGuestBindingTokenV2((AccountPlatform)_guestBindingPlatform, ret =>
{
   if (ret.resultCode == ErrorCode.Success)
   {                    
       var platform = ret.platform;
       var openId = ret.openId;
       var token = ret.token;
       // 请求游戏服务端，执行绑定操作
   }
   else
   {
       Debug.LogError("GetGuestBindingToken() failed");
   }
});

Unreal

MsdkCallbacks->OnGetGuestBindingTokenResult.AddDynamic(this, &<YOUR_CALLBACK_FUNCTION>);
UMsdkLogin::GetGuestBindingTokenV2(Platform);

处理访客账户绑定结果

获取访客绑定令牌后，您需要将其发送到游戏服务器以执行实际的绑定操作。游戏服务器应调用GOP Server side API /game/guest/swap将访客账户绑定到平台账户。

在游戏服务器端完成绑定操作后，您需要使用以下平台特定方法通知SDK结果：

如果服务器返回访客绑定成功，游戏客户端需要调用

Android

accountManager.onBindGuestSuccess();

iOS

[MSDKLoginManager.shared onGuestBindWithCompletion:^(MSDKLoginRet * _Nonnull ret) {
    if (loginRet.flag == MSDKeFlagSucc) {
        NSLog(@"访客绑定流程已完成");
    } else {
        NSLog(@"错误代码: %ld", ret.flag);
    }
}];

Unity

GMSDKHandler.BindClient.OnBindGuestSuccess(ret =>
{
    if (ret.resultCode == ErrorCode.Success)
    {
        Debug.Log("Bind guest success");
        var loginToken = GMSDKHandler.LoginClient.GetLoginRecord();
        // 这里可以更新游戏状态，使用新的登录令牌继续游戏
    }
    else
    {
        Debug.LogError("OnBindGuestSuccess() failed: " + ret.message);
    }

});

Unreal

UMsdkLogin::OnBindGuestSuccess()

仅在Android上，如果服务器返回访客绑定失败，游戏客户端需要调用

Android

accountManager.onBindGuestFailure();

Unity

GMSDKHandler.BindClient.OnBindGuestFailed();

Unreal

UMsdkLogin::OnBindGuestFailure()