《插件自助开发——用户类插件》

用户系统包含用户帐号相关的接口,需要实现框架接口InterfaceUser,并通过框架的UserWrapper类实现登录验证、回调等。

类名及初始化

用户系统的类一般命名为"User+插件名"
以心动为例:

@interface UserXindong : NSObject <InterfaceUser>

- (void)configDeveloperInfo:(NSMutableDictionary *)cpInfo;

在init方法里调用configDeveloperInfo:方法,执行SDK的初始化操作。
cpInfo参数为字典,需要调用PluginHelper类的getParamsInfo方法,从打包工具里获取到。

以心动为例:

- (id)init {
      if ([super init]) {
         [self configDeveloperInfo:[PluginHelper getParamsInfo]];
   }
   return self;
}

- (void)configDeveloperInfo:(NSMutableDictionary *)devInfo {
     [[XindongWrapper getInstance] initSDK:self info:devInfo];
}

用户系统的初始化结果需要通过UserWrapper类的onActionResult:retCode:retMsg:方法回调出去。
如果SDK有初始化回调,则用户系统的初始化回调需要得到SDK的结果才进行回调,可能的传递方式有代理、通知、block等。如果SDK没有初始化的回调、且初始化过程中没有抛异常,则一般默认初始化成功。
用户系统的初始化回调有两种返回值:

以心动为例:

- (void)onInitResult:(NSString *)status msg:(NSString *)message {
   OUTPUT_LOG(@"onInitResult,status:%@, message:%@\n", status, message);
   if ([status isEqualToString:@"SUCCEED"]) {
       [self onActionResult:ACTION_RET_INIT_SUCCESS msg:message];
   } else if ([status isEqualToString:@"FAIL"]){
       [self onActionResult:ACTION_RET_INIT_FAIL msg:message];
     }
}
- (void)onActionResult:(int)status msg:(NSString *)message {
     OUTPUT_LOG(@"onActionResult,status:%@, message:%@\n",[NSNumber numberWithInt:status],message);
     [UserWrapper onActionResult:self retCode:status retMsg:message];
}

InterfaceUser

用户类插件需要实现接口InterfaceUser,在InterfaceUser接口中,有如下函数:

- (void)login;                     //登录
- (BOOL)isLogined;             //获取登录状态
- (NSString *)getUserID;                //获取用户 ID(登录成功时有效)
- (BOOL)isFunctionSupported:(NSString *)functionName;   //是否支持方法名为functionName的扩展函数
- (NSString *)getPluginId;             //获取插件 ID
- (void)setDebugMode:(BOOL)debug;        // 设置调试模式(已废弃)
- (NSString *)getSDKVersion;         //获取SDK 版本号
- (NSString *)getPluginVersion;      //获取插件版本号

登录

登录流程描述

下载页面
1)游戏客户端调用登陆接口(向渠道平台服务器发起登录请求)
      这个过程可以拆分为3步:
        1.用户调用 AnySDK框架的 login 函数;
        2.AnySDK框架调用插件的 login 函数;
        3.插件 login 函数中调用 SDK 的登录接口。
      第3步在插件客户端处理
2)用户登录成功,渠道平台服务器返回认证码       插件客户端处理:接收 SDK 登录的回调结果:如果不成功,回调失败;如果成功,进行登录验证。
3)AnySDK框架拿着认证码向游戏服务器请求登录验证
      这个过程可以拆分为2步:
        1.插件调用框架提供的函数UserWrapper类的getAccessToken方法
        2.AnySDK框架向游戏服务器发送登录验证请求。
      其中,第1步在插件客户端处理
4)游戏服务器将认证码转发给AnySDK服务器
      游戏服务器处理
5)AnySDK服务器向渠道平台服务器进行用户登录验证
      插件服务端处理
6)AnySDK服务器接收验证结果
      插件服务端处理
7)AnySDK服务器将结果转发给游戏服务器
      AnySDK服务端处理
8)游戏服务器通知AnySDK框架登录验证结果
      插件客户端处理:登录验证信息会回调给调用UserWrapper.getAccessToken时传入的监听函数
9)AnySDK框架回调给游戏客户端是否登陆成功
      插件客户端处理:根据登录验证结果回调成功/失败

插件客户端需要执行的操作

1、登录
- (void)login;
登录方法里,需要调用SDK的登录方法。
以心动为例

- (void)login {
    OUTPUT_LOG(@"login invoked!\n");
    if (![[XindongWrapper getInstance] bIsInited]) {
       [self onActionResult:ACTION_RET_INIT_FAIL msg:@"init failed"];
       return;
     }
    [[XindongWrapper getInstance] login:self sel:@selector(onLoginResult:msg:)];
 }
 - (void)login:(id)target sel:(SEL)sel {
    _loginTarget = target;
    _loginSEL = sel;

    // call login function
    [[XDCore getInstance] login:@"1"];
 }

2、登录验证
登录验证需要调用UserWrapper类的
+ (void) getAccessToken:(NSMutableDictionary*)data target:(id)target sel:(SEL)sel;方法
      data参数为需要传递的参数,需要转成字典,其中必填的参数有:
        1.channel:与服务端定义的通讯字段,一般为插件名
        2.plugin_id:插件id
        3.此外,还有用于登录验证的字段,这些字段取决于服务端向SDK服务端做登录验证需要的数据,如 token,uid 等。
      target参数为指定回调的对象
      sel参数为指定回调的方法
      以心动为例,SDK的登录验证代码如下:

- (void)getAccessToken {
    NSMutableDictionary *data = [[NSMutableDictionary alloc] init];
    [data setObject:kPluginID forKey:@"plugin_id"];
    [data setObject:kXindong forKey:@"channel"];
    [data setObject:_access_token forKey:@"access_token"];

    OUTPUT_LOG(@"getAccessTokenParams: %@",data);
    [UserWrapper getAccessToken:data target:self sel:@selector(onGetAccessToken:)];
 }

3、登录的回调       登录的回调有三种返回值:
        1.ACTION_RET_LOGIN_SUCCESS:登录成功,必须是登录验证成功后才会回调,回调消息中的 msg 为登录验证是收到的ext字段的值。如心动的登录。
        2.ACTION_RET_LOGIN_FAIL:登录失败,在登录过程中失败、出现错误的情况下,均回调登录失败。
        3.ACTION_RET_LOGIN_CANCEL:取消登录,无法区分是取消还是失败时,回调失败。

登录状态

- (void)login;
      获取登录状态,为登录、登录失败、登录取消、登出等状态下,登录状态为 YES;登录成功后,登录状态为 NO。
      以心动为例

    - (BOOL)isLogined {
       OUTPUT_LOG(@"isLogined invoked!\n");
       return [[XindongWrapper getInstance] isLogined];
    }

获取用户ID

- (NSString *)getUserID;
获取用户 ID,登录成功后才能获取到正确的值。用户ID是SDK中用户的唯一标志,具体名称可能不一致,如 uID,openID 等 。 如果SDK有相应的接口,则以SDK的为准,如果SDK没有提供相应的接口,则需要插件在登录的时候把UserID保存。
以心动为例

- (NSString *)getUserID {
  OUTPUT_LOG(@"getUserID invoked!\n");
  return [[XindongWrapper getInstance] userID];
}

是否支持该函数

- (BOOL)isFunctionSupported:(NSString *)functionName;
是否支持函数名为functionName的扩展函数
返回值为是否支持该函数

- (BOOL)isFunctionSupported:(NSString *)functionName {
    OUTPUT_LOG(@"isFunctionSupported invoked!");
    NSString *temp  = [functionName stringByAppendingString:@":"];
    SEL sel = NSSelectorFromString(functionName);
    SEL sel_param = NSSelectorFromString(temp);
    BOOL ret = [self respondsToSelector:sel] || [self respondsToSelector:sel_param];
    return ret;
}

获取插件ID

- (NSString *)getPluginId;
插件的唯一标志,多支付时判断支付方式的标识。

设置Debug模式

- (void)setDebugMode:(BOOL)debug;
     已废弃,实现方式参照模板。

获取SDK版本号

- (NSString *)getSDKVersion;
     SDK版本是指第三方SDK的版本号,格式可能都不一样,如6.0、1.0.3、2.1.0.4等,这个版本号格式不需要任何改动。

获取插件版本号

- (NSString *)getPluginVersion;
     格式『版本序号_SDK版本号』,版本序号从『2.0.0』开始,每次更新+0.0.1

扩展接口

扩展函数是对InterfaceUser接口的扩展,不同的 SDK 支持的扩展接口不同。目前比较通用的扩展接口如下:

- (void)logout;                 //登出
- (void)accountSwitch;          //切换账号
- (void)enterPlatform;          //进入平台中心
- (void)showToolBar:(NSNumber *)toolbarPlace;    //显示悬浮工具栏
- (void)hideToolBar;             //隐藏悬浮工具栏
- (void)pause;                    //暂停游戏
- (void)exit;                     //退出游戏
- (void)submitLoginGameRole:(NSMutableDictionary*)roleInfo; //提交游戏数据
- (void)realNameRegister;         //实名注册
- (void)antiAddictionQuery;       //防沉迷查询

登出

- (void)logout;
在logout方法中调用SDK提供的注销登录的接口。
如果SDK有提供登出的回调,则需要在收到回调之后,调用UserWrapper类的onActionResult:retCode:retMsg:方法,把登出的回调结果传递出去。如果SDK没有提供登录回调,则需要在调用SDK登出接口的同时把UserID置空、把登录状态改为NO。
登出回调有两种返回值:

切换账号

- (void)accountSwitch;
切换账号。在该函数中调用 SDK 提供的切换账户的接口。切换账户接口和登录接口一样,在收到 SDK 的成功回调后,需要进行登录验证,登录验证成功,切换帐号才算成功。
切换账号的回调有两种返回值:

进入平台中心

- (void)enterPlatform;
进入平台中心。在该函数中调用 SDK 提供的进入平台中心的接口。
登录的回调有两种返回值:

显示悬浮工具栏

- (void)showToolBar:(NSNumber *)toolbarPlace;
显示悬浮工具栏。需要注意SDK 是否要去必须登录后才能显示悬浮窗,有些 SDK 在未登录的情况下调用后,会出现悬浮窗不显示,显示出悬浮窗后点击或移动会崩溃的情况,这时,需要在 README.md文档中的注意事项中注明。
参数toolbarPlace为工具栏的位置,需要根据SDK的接口对数据类型做相应转换。

隐藏悬浮工具栏

- (void)hideToolBar;
隐藏悬浮工具栏。在悬浮窗未显示的情况下调用该函数是否有崩溃或卡死等问题,如果有,需要在 README.md文档中的注意事项中注明。

暂停游戏

- (void)pause;
暂停游戏。常见模式为,调用暂停接口后,弹出SDK 的暂停界面。
当玩家关闭暂停界面,重新进入游戏时,回调ACTION_RET_PAUSE_PAGE。

退出游戏

- (void)exit; 退出游戏。退出游戏接口指的是,玩家主动退出游戏时,通过调用 SDK 的该接口,弹出确定退出游戏的界面,询问玩家。
当玩家确认要退出游戏时,回调ACTION_RET_EXIT_PAGE。
注意:
该接口与注销SDK释放资源接口的区别。注销SDK,释放资源接口在控制器的dealloc方法里调用。

提交游戏数据

- (void)submitLoginGameRole:(NSMutableDictionary*)roleInfo;
从用户传入的数据,选择需要的数据并转换为相应的格式后,调用提交数据接口。
用户传入的数据如下:

参数 是否必传 参数说明
roleId Y 角色ID
roleName Y 角色名称
roleLevel Y 角色等级
zoneId Y 服务器ID
zoneName Y 服务器名称
dataType Y 数据类型,1为进入游戏,2为创建角色
ext Y 扩展字段

实名认证

- (void)realNameRegister;
调用SDK提供的实名认证接口。实名认证完成后回调ACTION_RET_REALNAMEREGISTER。

防沉迷查询

- (void)antiAddictionQuery;
调用SDK提供的防沉迷接口。实名认证完成后回调ACTION_RET_ANTIADDICTIONQUERY。