04/29/2024 11:54:53
异账号、第三方渠道参数透传功能
一、功能说明
[info] 特别说明 以下功能需要进行详细的测试，以满足业务具体的需求
1.1 第三方渠道参数透传功能
在第三方 APP 中可以拉起游戏（比如通过玩家邀请，通过游戏中心拉起），游戏需要利用第三方 APP 携带的参数进行后续处理，MSDK 会将这些参数信息透传给游戏
应用场景举例：玩家通过点击其他好友通过微信发来的邀请信息，直接进入游戏并进入游戏队伍
1.2 异账号
游戏中授权的账号和第三方渠道中（如手Q/微信）中授权的账号不同。此种场景称之为异账号。
应用场景举例：当前游戏登录的微信账号与微信 APP 中的账号不同，玩家通过点击游戏中心拉起游戏后，游戏提示玩家选择哪个账号继续游戏
[info] 特别说明 一般情况下渠道（目前只有微信、QQ需要处理）不需要进行异账号处理。且异账号逻辑相对复杂，如没有特别需求，可以忽略。
二、客户端插件开发
2.1 Android 平台
2.1.1 类实现规则说明
异账号、第三方渠道参数透传需要首先配置生命周期监控，可参考 生命周期处理
使用生命周期监控同样的类（LifeCycleObserver），只需新增 IWakeup 接口实现即可
- 包名规则：固定为
com.tencent.gcloud.msdk - 类名规则：
渠道名（区分大小写） + LifeCycleObserver，如：GarenaLifeCycleObserver - 必须实现
IWakeup接口
2.1.2 回调字段说明
回调函数说明，可参考 客户端插件开发规则
observerID回调函数 IDMSDKObserverID.MSDK_PLATFORM_WAKE_UP用于第三方渠道拉起时返回登录态信息或者透传的参数信息
ret返回结构- 必须是
MSDKLoginPluginInfo数据结构 - 如果只开发第三方渠道参数透传功能，则只需填充
MSDKLoginPluginInfo中的seqID、channel、channelID、extraJson即可，不要填充channelOpenID和pluginData字段。 - 如果需要开发异账号功能，除了
seqID、channel、channelID字段，还需填充channelOpenID，可选填充pluginData，如果需要透传第三方渠道的参数，以 Json 格式写入extraJson即可
- 必须是
2.1.3 IWakeup 接口
notifyReceiveIntent 函数
处理第三方 APP 启动游戏时携带的信息，并返回相应的玩家登录态或特别参数信息。
2.1.4 代码示例
1、只提供第三方渠道参数透传功能
package com.tencent.gcloud.msdk;
public class GarenaLifeCycleObserver implements ILifeCycle, IWakeup {
// TODO
... 省略 ILifeCycle 需要实现的方法
@Override
public void notifyReceiveIntent(Intent intent){
try {
if(intent != null) {
// TODO 从 intent 中获取 Garena 特征信息
...
// 判断是否为 Garena APP 跳转，且为非登录请求
if(fromGarena) {
// TODO 从 intent 中获取 Garena 参数信息
...
// 拼装回调数据
MSDKLoginPluginInfo loginWakeupRet = new MSDKLoginPluginInfo();
loginWakeupRet.seqID = IT.createSequenceId();
// channel channelID 为必填参数
loginWakeupRet.channel = GarenaConst.Channel.MSDK_GARENA_CHANNEL;
loginWakeupRet.channelID = GarenaConst.Channel.MSDK_GARENA_CHANNEL_ID;
// 拼装透传给游戏的数据 extraJson
JSONObject extraJson = new JSONObject();
// 将第三方 APP 跳转获取的全部信息以 Json 格式放在 extraJson.params 字段中
JSONObject paramsData = new JSONObject();
paramsData.put("openid", openid);
// TODO ...
extraJson.put("params", paramsData.toString());
// 获取透传附带给游戏的数据信息，放在 game_data 字段中
extraJson.put("game_data", gameData);
// 将 extraJson 数据写入回调数据结构
loginWakeupRet.extraJson = extraJson.toString();
// 回调到 MSDKCore，进行后续的异账号、组队信息判断等
IT.onPluginRetCallback(MSDKObserverID.MSDK_PLATFORM_WAKE_UP, loginWakeupRet, loginWakeupRet.seqID);
}
} else {
MSDKLog.e("Garena notifyReceiveIntent is null ");
}
} catch (Exception e) {
MSDKLog.e("Garena notifyReceiveIntent error : " + e.getMessage());
}
}
}
如果不需要开发异账号功能，则只需填充 MSDKLoginPluginInfo 中的 seqID、channel、channelID、extraJson 即可，不要填充 channelOpenID 和 pluginData 字段
[info] 详情请参考示例代码
2、提供异账号和第三方渠道参数透传功能
package com.tencent.gcloud.msdk;
public class GarenaLifeCycleObserver implements ILifeCycle, IWakeup {
// TODO
... 省略 ILifeCycle 需要实现的方法
@Override
public void notifyReceiveIntent(Intent intent){
try {
if(intent != null) {
// TODO 从 intent 中获取 Garena 特征信息
...
// 判断是否为 Garena APP 跳转，且为非登录请求
if(fromGarena) {
// TODO 从 intent 中获取 Garena 参数信息
...
// 拼装回调数据
MSDKLoginPluginInfo loginWakeupRet = new MSDKLoginPluginInfo();
loginWakeupRet.seqID = IT.createSequenceId();
// channel channelID 为必填参数
loginWakeupRet.channel = GarenaConst.Channel.MSDK_GARENA_CHANNEL;
loginWakeupRet.channelID = GarenaConst.Channel.MSDK_GARENA_CHANNEL_ID;
// 如果可以获得当前渠道用户的 openid，可填充 channelOpenID。这将在 MSDKCore 中判断游戏当前登录的玩家是否与 APP 中登录的玩家相同
loginWakeupRet.channelOpenID = openid;
// 【可选】如果可以获得与登录时相同的渠道数据，可将数据填充到 pluginData 中，这些信息将透传给后台进行登录
JSONObject pluginData = new JSONObject();
pluginData.put("uid", uid);
pluginData.put("token", token);
loginWakeupRet.pluginData = pluginData.toString();
// 拼装透传给游戏的数据 extraJson
JSONObject extraJson = new JSONObject();
// 将第三方 APP 跳转获取的全部信息以 Json 格式放在 extraJson.params 字段中
JSONObject paramsData = new JSONObject();
paramsData.put("openid", openid);
// TODO ...
extraJson.put("params", paramsData.toString());
// 获取透传附带给游戏的数据信息，放在 game_data 字段中
extraJson.put("game_data", gameData);
// 将 extraJson 数据写入回调数据结构
loginWakeupRet.extraJson = extraJson.toString();
// 回调到 MSDKCore，进行后续的异账号、组队信息判断等
IT.onPluginRetCallback(MSDKObserverID.MSDK_PLATFORM_WAKE_UP, loginWakeupRet, loginWakeupRet.seqID);
}
} else {
MSDKLog.e("Garena notifyReceiveIntent is null ");
}
} catch (Exception e) {
MSDKLog.e("Garena notifyReceiveIntent error : " + e.getMessage());
}
}
}
如果需要开发异账号功能，除了 seqID、channel、channelID、extraJson 字段，还需填充 channelOpenID，可选填充 pluginData。
[info] 详情请参考示例代码
3、只提供异账号功能
此功能不特殊举例，参考第二个示例代码，不填充 extraJson 字段即可。
2.2 iOS 平台
2.2.1 类实现规则说明
异账号、第三方渠道参数透传需要首先配置生命周期监控，可参考 生命周期处理
在 MSDKApplicationDelegate 中，监听 openURL 函数，并增加第三方信息的处理逻辑。
- 文件名规则：
MSDKApplicationDelegate + 渠道，如MSDKApplicationDelegate+Garena.mm - 类名规则：
MSDKApplicationDelegate (渠道)，如：MSDKApplicationDelegate (Garena)
2.1.2 回调字段说明
回调函数说明，可参考 客户端插件开发规则
observerID回调函数 IDkObserverIDWakeUp用于第三方渠道拉起时返回登录态信息或者透传的参数信息
ret返回结构- 必须是
InnerLoginPluginRet数据结构 - 如果只开发第三方渠道参数透传功能，则只需填充
InnerLoginPluginRet中的seqID、channel、channelID、extraJson即可，不要填充channelOpenID和pluginData字段。 - 如果需要开发异账号功能，除了
seqID、channel、channelID字段，还需填充channelOpenID，可选填充pluginData，如果需要透传第三方渠道的参数，以 Json 格式写入extraJson即可
- 必须是
2.2.3 代码示例
公共逻辑代码
- (BOOL)garena_application:(UIApplication *_Nullable)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary *)options {
// TODO 从 url 中获取 Garena 特征信息
...
// 判断是否为 Garena APP 跳转，且为非登录请求
if(fromGarena) {
// 处理第三方渠道携带的信息
[self parseMediaTagNameByUrl:url];
}
// swizzle 机制必须返回调用方法自身
return [self garena_application:application openURL:url options:options];
}
- (BOOL)garena_application:(UIApplication *_Nullable)application openURL:(NSURL *_Nullable)url sourceApplication:(NSString *_Nullable)sourceApplication annotation:(id _Nullable)annotation {
// TODO 从 url 中获取 Garena 特征信息
...
// 判断是否为 Garena APP 跳转，且为非登录请求
if(fromGarena) {
// 处理第三方渠道携带的信息
[self parseMediaTagNameByUrl:url];
}
// swizzle 机制必须返回调用方法自身
return [self garena_application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
}
1、只提供第三方渠道参数透传功能
- (void)parseMediaTagNameByUrl:(NSURL *)url {
// TODO 从 url 中获取 Garena 参数信息
...
// 拼装回调数据
InnerLoginPluginRet wakeupRet;
wakeupRet.seqID = MSDK::CreateSequenceId();
// channel channelID 为必填参数
wakeupRet.channelID = MSDK_GARENA_CHANNEL_ID;
wakeupRet.channel = MSDK_GARENA_CHANNEL;
// 拼装透传给游戏的数据 extraJson
MSDKJsonManager extraJson;
// 将第三方 APP 跳转获取的全部信息以 Json 格式放在 extraJson.params 字段中
extraJson.PutIfAbsent("params", [params UTF8String]);
// 获取透传附带给游戏的数据信息，放在 game_data 字段中
extraJson.PutIfAbsent("game_data", [mediaTagNameString UTF8String]);
// 将 extraJson 数据写入回调数据结构
std::string extraStr(extraJson);
wakeupRet.extraJson = extraStr;
// 回调到 MSDKCore，进行后续的异账号、组队信息判断等
MSDKInnerObserverHolder<InnerLoginPluginRet>::CommitToTaskQueue(wakeupRet, kObserverIDWakeUp, wakeupRet.seqID);
}
如果不需要开发异账号功能，则只需填充 InnerLoginPluginRet 中的 seqID、channel、channelID、extraJson 即可，不要填充 channelOpenID 和 pluginData 字段
[info] 详情请参考示例代码
2、提供异账号和第三方渠道参数透传功能
- (void)parseMediaTagNameByUrl:(NSURL *)url {
// TODO 从 url 中获取 Garena 参数信息
...
// 拼装回调数据
InnerLoginPluginRet wakeupRet;
wakeupRet.seqID = MSDK::CreateSequenceId();
// channel channelID 为必填参数
wakeupRet.channelID = MSDK_GARENA_CHANNEL_ID;
wakeupRet.channel = MSDK_GARENA_CHANNEL;
// 如果可以获得当前渠道用户的 openid，可填充 channelOpenID。这将在 MSDKCore 中判断游戏当前登录的玩家是否与 APP 中登录的玩家相同
wakeupRet.channelOpenID = openid;
// 【可选】如果可以获得与登录时相同的渠道数据，可将数据填充到 pluginData 中，这些信息将透传给后台进行登录
MSDKJsonManager pluginData;
pluginData.PutIfAbsent("uid", uid);
pluginData.PutIfAbsent("token", token);
wakeupRet.pluginData = std::string(pluginData);
// 拼装透传给游戏的数据 extraJson
MSDKJsonManager extraJson;
// 将第三方 APP 跳转获取的全部信息以 Json 格式放在 extraJson.params 字段中
extraJson.PutIfAbsent("params", [params UTF8String]);
// 获取透传附带给游戏的数据信息，放在 game_data 字段中
extraJson.PutIfAbsent("game_data", [mediaTagNameString UTF8String]);
// 将 extraJson 数据写入回调数据结构
wakeupRet.extraJson = std::string(extraJson);
// 回调到 MSDKCore，进行后续的异账号、组队信息判断等
MSDKInnerObserverHolder<InnerLoginPluginRet>::CommitToTaskQueue(wakeupRet, kObserverIDWakeUp, wakeupRet.seqID);
}
如果需要开发异账号功能，除了 seqID、channel、channelID、extraJson 字段，还需填充 channelOpenID，可选填充 pluginData。
[info] 详情请参考示例代码
3、只提供异账号功能
此功能不特殊举例，参考第二个示例代码，不填充 extraJson 字段即可。
三、测试说明
建议业务从以下几个方面进行测试：
3.1 第三方渠道参数信息透传
- 当前游戏没有登录态，点击第三方 APP 的玩家邀请信息进入游戏
- 当前游戏已有登录态，点击第三方 APP 的玩家邀请信息进入游戏
3.2 异账号
- 当前游戏没有登录态，点击第三方 APP 的玩家邀请信息进入游戏
- 当前游戏登录的为非当前开发第三方渠道（如微信）账号，点击第三方 APP （如 Garena）的玩家邀请信息进入游戏
- 当前游戏登录的为第三方渠道 的 A 账号，第三方 APP 登录 B 账号，点击第三方 APP （如 Garena）的玩家邀请信息进入游戏
- 当前游戏登录的为第三方渠道账号与当前第三方 APP 登录账号相同，点击第三方 APP （如 Garena）的玩家邀请信息进入游戏
四、异账号逻辑深入理解
以上信息针对异账号和第三方渠道参数透传功能已经足够，更多的是需要对功能进行详细的测试，以满足业务具体的需求。
关于 MSDKCore 如何将插件透传给 Core 的数据进行处理，可以继续阅读一下内容。
**逻辑说明:**
【1】红色虚线框表示 MSDK 将告知游戏登录结果（通过 OnLoginRet 回调），等同于游戏执行了 SwitchUser(true) 操作
【2】蓝色虚线框表示 MSDK 将通过 WakeUp （通过 OnLoginBaseRet 回调）告知游戏需要如何进一步处理
【3】绿色虚线框表示除非存在需要透传的第三方 APP 信息，否则不会通过 WakeUp 给游戏回调，MSDK 进行静默处理
Copyright © 2024 MSDK.
All rights reserved.
All rights reserved.