GHOME SDK 开发手册 for IOS 国际版


1. 前言

本文用于指导游戏开发商接入GHomeSDK国际版,文中包含客户端的接入说明.

2. SDK包含功能:

  • 登录功能(包含FaceBook,GameCenter,苹果登录,游客模式)

  • 账号绑定功能(包含FaceBook,GameCenter)

  • 支付功能(除游客模式外用户登录后均可调用支付功能)

  • 账号注销账号功能

  • Firebase数据上报功能

  • 如果需要使用苹果登录功能请开启 targets设置中添加SignInwithApple

3. 开发环境要求

  • 对于iOS开发者,建议使用最新版本进行开发,iOS版本需求为8.0及以上.

3.1 引用SDK提供的Framework、资源包:

FBSDKCoreKit 和 FBSDKLoginKit 需要设置成Embed & Sign,Bolts.Framework 在最新的Facebook SDK中已经去掉!!!)

IOS4 IOS4

3.2 修改工程配置

1.注:确保 Build Settings -> Build Options-> always embed swift standard libraries 设置为 YES

2.在工程配置里头,找到Linking部分,修改Other Linker Flags,添加内容:-ObjC

3.在项目targets中打开GameCenter功能

4.在项目Info.plist文件中添加 LSApplicationQueriesSchemes:fbapi fb-messenger-share-api fbauth2 fbshareextension FacebookDisplayName : 你的项目名称 FacebookAppID : 你的FaceBookID NSAppTransportSecurity:NSAllowsArbitraryLoads YES

5.在URLType中添加 URLSchemes fbxxxxxxxxx(你的FaceBookSchemes)

6.在项目Info.plist文件中添加sdk对应域名: 18nBaseUrl:xxx.sdo.com 18nPayBaseUrl:xxx.sdo.com

7.Line 登陆接入(添加Growthy.framework Line日志上报 )

IOS7

IOS7

IOS7

8.AppDelegate.mm中添加一下方法(Unity导出工程叫做UnityAppController.mm)

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[GHomeAPI sharedGHome] application:application didFinishLaunchingWithOptions:launchOptions];
    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [[GHomeAPI sharedGHome] application:app openURL:url options:options];
}
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    return [[GHomeAPI sharedGHome] application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
}

- (void)applicationDidEnterBackground:(UIApplication *)application {
    [[GHomeAPI sharedGHome] applicationDidEnterBackground:application];
}

- (void)applicationWillEnterForeground:(UIApplication *)application {
    [[GHomeAPI sharedGHome] applicationWillEnterForeground:application];  
}

4. 基础功能

4.1. SDK初始化接口

  • 初始化接口定义
/**
 * 初始化
 * @param delegate       委托对象
 *        appId          游戏ID
 */
- (void)initialize:(id<GHomeAPIInitializeDelegate>)delegate
             appId:(NSString*)appId;
  • 初始化接口调用示例
[[GHomeAPI sharedGHome] initialize:self appId:@"1000"];
  • 初始化接口回调示例
- (void)initializeResult:(NSInteger)resultCode resultMsg:(NSString*)resultMsg
{
    showAlertView(@"initializeResult code[%@] msg[%@]", @(resultCode), resultMsg);
}
  • 初始化接口回调说明:

    当resultCode为 GHOMEAPI_CONSTANTS_SUCCESS 时表示成功。
    当resultCode为其他值时均表示失败,resultMsg为失败信息描述。
    当resultCode为 GHOMEAPI_CONSTANTS_SUCCESS 时方可进行其他SDK操作。

  • 初始化可以在AppDelegate中调用也可以在ViewController中调用,具体什么位置调用由接入方自行决定,只有保证在初始化成功后才能调用login接口

4.2 客户端登录接口

  • 登录接口定义
/**
 * 登录
 * @param delegate       委托对象
 */
- (void)login:(id<GHomeAPILoginDelegate>)delegate;
  • 登录接口说明:
    包含自动登录功能,调用者可直接调用登录接口无需做票据存储。

  • 登录接口调用示例:
[[GHomeAPI sharedGHome] login:self];
  • 登录接口回调示例
/**
 * 登录结果回调
 * @param resultCode   返回码
 * @param resultMsg   返回信息
 * @param ticket   票据
 * @param userId   用户ID
 * @param isGuest    是否游客
 * @param isBinded    是否绑定
 * @param loginType      登录类型  0:游客  501:苹果GameCenter 502:Google 503:Facebook 504:Appleid
 */
- (void)loginResult:(NSInteger)resultCode resultMsg:(NSString *)resultMsg ticket:(NSString *)ticket userId:(NSString *)userId isGuest:(BOOL)isGuest isBinded:(BOOL)isBinded loginType:(NSInteger)loginType
{
    showAlertView(@"loginResult code[%@] msg[%@] ticket[%@] useId[%@] isGuest[%@] isBinded[%@]", @(resultCode), resultMsg, ticket, userId, @(isGuest), @(isBinded);
}
  • 登录接口回调说明:
    当resultCode为 GHOMEAPI_CONSTANTS_SUCCESS 时表示成功,回调值有效。 当resultCode不为GHOMEAPI_CONSTANTS_SUCCESS时,游戏可以显示错误内容,然后再次调用登录接口,让用户继续登录。

4.3 客户端绑定接口

/**
 *绑定接口
 */
- (void)bindAccountWithCallback:(void (^)(NSInteger code,NSString *msg, NSDictionary *dic))callback;
  • 绑定接口说明: 游客模式登录后方可调用该功能(绑定账号包含FaceBook,GameCenter)。 当code为 0 时表示绑定成功。

4.4 Line 校验Token接口

/**
* 验证Line票据
* @param delegate       委托对象
*/
- (void)lineVerifyToken:(id <GHomeAPILineVerifyTokenDelegate>)delegate;
/**
* 验证Line票据回调
* 
*/
- (void)lineVerifyTokenResult:(NSInteger)resultCode resultMsg:(NSString *)resultMsg

示例代码:
//一般是app启动和进入前台时候调用验证Line票据
- (void)applicationDidBecomeActive:(UIApplication *)application {
    [[GHomeAPI sharedGHome] lineVerifyToken:self];
}

- (void)lineVerifyTokenResult:(NSInteger)resultCode resultMsg:(NSString *)resultMsg {
    NSLog(@"lineVerifyTokenResult-%ld %@",(long)resultCode,resultMsg);
    //resutltcode -100001 表示line sdk初始化失败   无需处理
    //resutltcode -100002 表示上一次登陆不是Line,  无需处理
    //resutltcode -100003  表示正在验证Line。       无需处理
    //resutltcode 0       表示Line验证成功         无需处理
    //其他情况需要退出登陆(调用Loginout方法)
    if(resultCode !=  -100001 && resultCode !=  -100002 && resultCode !=  -100003 && resultCode !=  0) {
        [[GHomeAPI sharedGHome] logout:self]; //执行游戏退出登陆
          UIAlertView *alertV = [[UIAlertView alloc] initWithTitle:nil
                                                           message:[NSString stringWithFormat:@"code --%ld -- msg %@  已退出登陆",resultCode,resultMsg]
                                                              delegate:nil
                                                     cancelButtonTitle:@"确认"
                                                     otherButtonTitles:nil];
        [alertV show];
    }

}
  • Line 校验Token接口 一般是app启动和进入前台时候调用验证Line票据,当返回 -100001 -100002 -100003 0 时候 不需要处理,当返回其他错误吗时,表示token验证失败,需要退出登陆

4.5 客户端注销接口

  • 注销接口定义
/**
 * 注销(切换账号)
 * @param delegate       委托对象
 */
- (void)logout:(id<GHomeAPILogoutDelegate>)delegate;
  • 注销接口调用示例
[[GHomeAPI sharedGHome] logout:self];
  • 注销接口回调示例
- (void)logoutResult:(NSInteger)resultCode resultMsg:(NSString*)resultMsg
{
    showAlertView(@"logoutResult code[%@] msg[%@]", @(resultCode), resultMsg);
}
  • 注销接口回调说明
    当resultCode 为 GHOMEAPI_CONSTANTS_SUCCESS 时表示成功。
    当resultCode 为其他值时表示失败,resultMsg为失败信息描述。

5. 账号功能

5.1. 账号体系说明

  • 注册&登录原理

    1) 在游戏登录界面打开SDK注册&登录界面;

    2) 用户完成注册&登录之后,SDK把用户id和ticket票据返回游戏;

    3) 游戏如果有服务器,需要把客户端获取到ticket票据发送到"登录票据验证接口"(参考5.4节)进行验证,然后把返回的用户信息(用户id和账号)保存到游戏服务器;

  • 注册&登录时线图
    IOS6

5.2. 服务器登录票据验证接口

  • 用法说明

    为了保证游戏服务器的安全性,游戏服务器在登记用户登录信息之前需要到国际版服务器做一个验证

  • 接口地址

    https://abroad.sdo.com/fh/open/ticket

  • 传值方式

    GET

  • 参数列表

    appid: 游戏对应的APPID

    timestamp: 精确到秒的unix时间戳

    sequence: 不重复的请求序列号(全局唯一)

    ticket_id: 从客户端登录接口返回的ticket字符串;

    sign: 签名串(参考:“附录A:服务器端签名算法”,签名原始串示例:appid=xxx&sequence=xxx&ticket_id=xxx & timestamp=xxxappsecretkey)

  • 返回结果

    返回结果按json编码,数据格式为:

{
  code:0, #返回状态,0为成功,1为失败,2  签名错误7 osap商户不存在,3001 票据不存在或超过有效期或被反复验证,1003 票据申请的appId和验证的APPID不一致
  msg:"ok", #错误信息
  data:{
    userid:123456, #平台用户id,纯数字,无类型。
    token:"40E00263-16A7-8CFA-D0E8-C951D683EA24", #平台TOKEN,36位字符串,暂时不用
    phone:"+86-139****6893" #手机帐号,带国际区号,可用于显示帐号
    invitation_code:"34343"  #邀请码
  }
}

6. 支付功能

6.1 支付原理说明

6.2 客户端支付接口

  • 支付接口定义
/**
 * 显示支付页面
 * @param delegate       委托对象
 *        productId      产品ID
 *        areaId         区ID
 *        gameOrderId    游戏订单ID
 *        extendInfo     附加参数
 */
- (void)pay:(id<GHomeAPIPayDelegate>)delegate
  productId:(NSString*)productId
     areaId:(NSString*)areaId
gameOrderId:(NSString*)gameOrderId
 extendInfo:(NSString*)extendInfo;
  • 支付接口调用示例
[[GHomeAPI sharedGHome] pay:self productId:@"p0001" areaId:@"1" gameOrderId:@"abc123" extendInfo:nil];
  • 支付接口回调示例
- (void)payResult:(NSInteger)resultCode resultMsg:(NSString*)resultMsg
{
    showAlertView(@"payResult code[%@] msg[%@]", @(resultCode), resultMsg);
}
  • 支付接口回调说明
    当resultCode 为 GHOMEAPI_CONSTANTS_SUCCESS 时表示成功。
    当resultCode 为其他值时表示失败,resultMsg为失败信息描述。

6.3 服务器订单通知接口

  • 用法说明

    用于将用户支付结果通知给游戏。

  • 接口地址

    接口地址需要游戏提供,可以在开发商后台"我的游戏 > 区服管理"中配置。

  • 传值方式

    POST

  • 参数列表

    orderNo: 服务器的订单号

    userId:用户ID

    gameOrderNo: 游戏的订单号

    product: 产品ID(在开发商后台"我的游戏 > 充值管理"中配置)当游戏服务器发货是按照游戏自己记录的商品id发货时,请保证这里返回的商品id是否与游戏自己记录的商品id一致,方可发货;如不一致,游戏可以拒绝发货!

    extend:游戏发送过来的扩展信息,原格式返回

    sign:签名串(参考"附录A:服务器端签名算法")

    time:到账时间

  • 参数示例
orderNo=791000012PP016140210105937000001&userId=18178&gameOrderNo=NONE&product=com.winggod.jingzhuan&extend=NONE&time=1392004960&sign=ad08d9e2d7b7df6603bc431392d1c707
  • 返回结果

    返回字符串success表示成功,其他表示失败。

7. firebase接入:

到firebase官网下载项目对应GoogleService-Info.plist文件放置游戏工程plist文件旁 IOS4

8. SDK返回code描述:

具体可参见GHomeAPIConstants.h 和 GHomePayConstant.h

  • 获取设备唯一标示接口调用示例
NSString* deviceString = [[GHomeAPI sharedGHome] deviceId];

9. 附录A:服务器端签名算法

  • 参数说明:

    1) timestamp为调用接口时的unix时间戳(精确到秒)

    2) sequence为请求序列号(游戏服务器端需要保证两次调用接口生成的sequence不重复)

  • 签名算法:

    1) 调用方首先需要将请求的参数根据参数的key(ASCII码值)进行升序排序

    2) 将排序好的接口请求参数和参数值按key=val&key2=val2…这样得格式拼装成一个字符串,并在最后加上与APPID对应的APPKEY

    3) 对上述拼接好的字符串进行md5编码,获得最终的签名串

  • 代码示例(PHP):
public function sign ($params, $secret_key) { // $params数组必须包含timestamp
  $in = ksort($params);
  $pairs = array();
  foreach($in as $k => $v){
    $pair[] = $k. '=' .$v;
  }
  $str = implode('&', $pair); // 拼接字符串
  $str = $str.$secret_key; // 把APPKEY补充到最后
  return md5($str);
}

10. 扩展功能

10.1. 客户端获取游戏区服列表接口

  • 获取区服信息接口定义
/**
 * 获取区服信息
 * @param delegate       委托对象
 */
- (void)getAreaConfiguration:(id<GHomeAPIGetAreaConfigrationDelegate>)delegate;
  • 获取区服信息接口调用示例
[[GHomeAPI sharedGHome] getAreaConfiguration:self];
  • 获取区服信息接口回调示例
- (void)getAreaConfigrationResult:(NSInteger)resultCode resultMsg:(NSString*)resultMsg info:(NSDictionary*)info
{
    showAlertView(@"getAreaConfigrationResult code[%@] msg[%@] info[%@]", @(resultCode), resultMsg, info);
}
  • 获取区服信息接口回调说明
    当resultCode 为 GHOMEAPI_CONSTANTS_SUCCESS 时表示成功,返回info值。
    当resultCode 为其他值时表示失败,resultMsg为失败信息描述,info值无效。
  info[{
        message =         (
                        {
                "area_code" = 1;
                "name" = "\/U5996\/U7cbe\/U4e4b\/U6e56";
                "notify_url" = "http://qa.dev.mygm.sdo.com/test/gamenotify";
            }
        );
        result = 0;    //当result =0时表示成功
}]

10.2. 客户端获取游戏商品列表接口

  • 获取支付产品信息接口定义
/**
 * 获取支付产品信息
 * @param delegate       委托对象
 */
- (void)getProductConfiguration:(id<GHomeAPIGetProductConfigrationDelegate>)delegate;
  • 获取支付产品信息接口调用示例
[[GHomeAPI sharedGHome] getProductConfiguration:self];
  • 获取支付产品信息接口回调示例
- (void)getProductConfigurationResult:(NSInteger)resultCode resultMsg:(NSString*)resultMsg info:(NSDictionary*)info
{
    showAlertView(@"getProductConfigurationResult code[%@] msg[%@] info[%@]", @(resultCode), resultMsg, info);
}
  • 获取支付产品信息接口回调说明

    当resultCode 为 GHOMEAPI_CONSTANTS_SUCCESS 时表示成功,返回info值。
    当resultCode 为其他值时表示失败,resultMsg为失败信息描述,info值无效。

  info[{
        message =         (
                        {
                "item_name" = 10mc;
                "money" = "6.00";
                "product_code" = "com.product.tenGold";
                "type":1  // 0:Android游戏,1:IOS游戏,2:Android和IOS游戏
            },
                        {
                "item_name" = 10mc;
                "money" = "0.01";
                "product_code" = p0001;
                "type":2  // 0:Android游戏,1:IOS游戏,2:Android和IOS游戏
            }
        );
        result = 0;     //result = 0时表示成功
}]

10.3. 客户端获取一次性登录票据接口

  • 获取票据接口定义
/**
 * 获取票据,登录后有效
 * @param delegate       委托对象
 *        appId          游戏ID
 *        areaId         区ID
 */
- (void)getTicket:(id<GHomeAPIGetTicketDelegate>)delegate
            appId:(NSString*)appId
           areaId:(NSString*)areaId;
  • 获取票据接口调用示例
[[GHomeAPI sharedGHome] getTicket:self appId:@"1000" areaId:@"1"];
  • 获取票据接口回调示例
- (void)getTicketResult:(NSInteger)resultCode resultMsg:(NSString*)resultMsg ticket:(NSString*)ticket
{
    showAlertView(@"getTicketResult code[%@] msg[%@] ticket[%@]", @(resultCode), resultMsg, ticket);
}
  • 获取票据接口回调说明

    当resultCode 为 GHOMEAPI_CONSTANTS_SUCCESS 时表示成功,返回ticket值。
    当resultCode 为其他值时表示失败,resultMsg为失败信息描述,ticket值无效。