单机版手游存档发货SDK 开发手册 for IOS


1. 前言

本文用于指导游戏开发商接入GameSDK,文中包含客户端的接入说明,以及服务器接口的介绍;

2. SDK接入流程概述

  • 搭建SDK开发环境

  • 初始化SDK

  • 初始化成功

  • 其他功能接口,可根据业务需要适时调用

3. 开发环境要求

3.1. 引用SDK提供的静态库、头文件、资源包

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

  • 解压SDK包得到framework文件。

  • 将SDK文件导入工程。

3.2. 添加所需要的库文件

将系统库UIKit.framework、Foundation.framework、CoreGraphics.framework、CoreTelephony.framework、AdSupport.framework、libz.tbd导入工程。

4. 基础功能

4.1. SDK接口统一回调

  • 接口回调定义
// 接口统一回调
typedef void(^GameSDKCallback)(NSInteger code,
                               NSString * _Nonnull msg,
                               NSDictionary* _Nullable data);
  • 接口回调说明

    code 为回调状态码,等于0时表示成功,其余均表示失败。
    msg 为回调状态的描述。
    data 为回调的结果数据。

4.2. 获取网络状态接口

  • 可获取当前设备的网络状态,根据网络状态来决定是否调用GHomeSDK的登录接口获取ticket等相关信息。

  • 获取网络状态接口定义
/**
 获取网络状态
 @param callback    回调
 */
+ (void)getNetworkState:(GameSDKCallback _Nullable)callback;
  • 获取网络状态接口调用示例
[GameSDK getNetworkState:^(NSInteger code, NSString * msg, NSDictionary * data) {
    NSLog(@"Current network state: %@", data[@"networkState"]);
}];
  • 获取网络状态接口回调说明

    网络状态将在data中返回,可通过data.get("networkState")获得网络状态的字符串: noNetwork 无网络 WiFi 无线局域网 WWAN 无线广域网 unknow 未知网络

4.3. SDK初始化接口

  • 初始化可以在AppDelegate中调用也可以在ViewController中调用,具体什么位置调用由接入方自行决定,只要保证在初始化成功后才能调用登录、注销及其他业务接口,推荐在AppDelegate中游戏启动后调用。

  • 初始化接口定义
/**
 初始化
 @param appId       游戏Id
 @param callback    回调
 */
+ (void)initialize:(NSString * _Nonnull)appId
          callback:(GameSDKCallback _Nullable)callback;
  • 初始化接口调用示例
[GameSDK initialize:@"1000" callback:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"GameSDK initialize succeed!");
    } else {
        NSLog(@"GameSDK initialize failed, %@.", msg);
    }
}];

5. SDK登录/注销功能

5.1. SDK登录接口

  • 调用SDK登录接口,需先调用SDK初始化接口。需要在游戏登录成功获取ticket之后调用,具体什么位置调用由接入方自行决定,只要保证在SDK登录成功后才能调用其它业务接口,推荐在游戏登录成功之后立即调用。

  • 登录接口定义
/**
 登录
 获取业务接口所需用户相关参数
 @param areaId      区服Id
 @param groupId     组群Id
 @param ticket      票据
 @param callback    回调
 */
+ (void)login:(NSString * _Nonnull)areaId
      groupId:(NSString * _Nullable)groupId
       ticket:(NSString * _Nonnull)ticket
     callback:(GameSDKCallback _Nullable)callback;
  • 登录接口调用示例
[GameSDK login:@"1000" groupId:@"1000" ticket:@"abc" callback:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Login succeed!");
    } else {
        NSLog(@"Login failed, %@.", msg);
    }
}];

5.2. SDK注销接口

  • 调用SDK注销接口,需先调用SDK初始化接口。注销成功后将会清除账户相关数据,无法正常调用其它业务接口。

  • 注销接口定义
/**
 注销
 注销用户相关参数
 @param callback    回调
 */
+ (void)logout:(GameSDKCallback _Nullable)callback;
  • 注销接口调用示例
[GameSDK logout:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Logout succeed!");
    } else {
        NSLog(@"Logout failed, %@.", msg);
    }
}];

6. 存档上传/下载功能

6.1. 存档下载接口

  • 下载接口定义
/**
 下载存档接口
 @param callback    回调, data={"filePath":""}
 */
+ (void)downloadSavedata:(GameSDKCallback _Nullable)callback;
  • 下载接口调用示例
[GameSDK downloadSavedata:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Savedata download succeed, file path: %@!",data[@"filePath"]);
    } else {
        NSLog(@"Savedata download failed, %@.", msg);
    }
}];
  • 下载回调结果说明

    下载成功时,文件路径将在data中返回,可通过data.get("filePath")获得文件路径的字符串。文件位于tmp目录下,使用完之后有可能会被删除,建议下载成功后立即拷贝到document或library目录下保存。如果返回错误码GameSDKErrorNotPermittedGtoken,则表明登录态失效,需要重新调用登录接口。

6.2. 存档上传接口

  • 上传接口定义
/**
 上传存档接口
 @param filePath    存档文件路径
 @param callback    回调
 */
+ (void)uploadSavedata:(NSString * _Nonnull)filePath
              callback:(GameSDKCallback _Nullable)callback;
  • 上传接口调用示例
[GameSDK uploadSavedata:@"/Documents/Savedata.sav" callback:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Savedata upload succeed!");
    } else {
        NSLog(@"Savedata upload failed, %@.", msg);
    }
}];
  • 上传回调结果说明

    如果返回错误码GameSDKErrorNotPermittedGtoken,则表明登录态失效,需要重新调用登录接口。

7. 订单功能

7.1. 获取未发货订单信息接口

  • 获取未发货订单信息接口定义
/**
 获取未发货订单信息接口
 @param callback    回调,data={"orderList":[{"orderId":"","traceNo":"","areaId":"","productId":"","quantity":0,"extend":""}]}
 */
+ (void)requestUndeliveredOrderInfo:(GameSDKCallback _Nullable)callback;
  • 获取未发货订单信息接口调用示例
[GameSDK requestUndeliveredOrderInfo:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Request undelivered order info succeed!");
    } else {
        NSLog(@"Request undelivered order info failed, %@.", msg);
    }
}];
  • 获取未发货订单信息接口回调说明

    获取成功时,订单信息将在data中返回,可通过data.get("orderList")获得订单信息的字符串,JSON格式。示例:

[
  {"orderId" = "1000","traceNo" = "1000","areaId" = "1000","productId" = "1000","quantity" = 1,"extend" = "1000"},
  {"orderId" = "1001","traceNo" = "1001","areaId" = "1001","productId" = "1001","quantity" = 1,"extend" = "1001"},
  {"orderId" = "1002","traceNo" = "1002","areaId" = "1002","productId" = "1002","quantity" = 1,"extend" = "1002"}
]

如果返回错误码GameSDKErrorInvalidGtoken,则表明登录态失效,需要重新调用登录接口。

7.2. 上报发货订单的发货结果接口

  • 上报发货订单的发货结果接口定义
/**
 上报发货订单的发货结果接口
 @param orderList   订单号数组
 @param callback    回调
 */
+ (void)reportOrderResult:(NSArray<NSString *> * _Nonnull)orderList
                 callback:(GameSDKCallback _Nullable)callback;
  • 上报发货订单的发货结果接口调用示例
[GameSDK reportOrderResult:@[@"1000"] callback:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Report order result succeed!");
    } else {
        NSLog(@"Report order result failed, %@.", msg);
    }
}];
  • 上报发货订单的发货接口回调说明

    如果返回错误码GameSDKErrorInvalidGtoken,则表明登录态失效,需要重新调用登录接口。

7.3. 获取领奖信息接口

  • 获取领奖信息接口定义
/**
 获取领奖信息接口
 @param callback    回调,data={"orderList":[{"orderId":"","traceNo":"","areaId":"","productId":"","quantity":0,"extend":""}]}
 */
+ (void)requestAwardInfo:(GameSDKCallback _Nullable)callback;
  • 获取领奖信息接口调用示例
[GameSDK requestAwardInfo:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Request award info succeed!");
    } else {
        NSLog(@"Request award info failed, %@.", msg);
    }
}];
  • 获取领奖信息接口回调说明

    获取成功时,订单信息将在data中返回,可通过data.get("orderList")获得订单信息的字符串,JSON格式。示例:

[
  {"orderId" = "1000","traceNo" = "1000","areaId" = "1000","productId" = "1000","quantity" = 1,"extend" = "1000"},
  {"orderId" = "1001","traceNo" = "1001","areaId" = "1001","productId" = "1001","quantity" = 1,"extend" = "1001"},
  {"orderId" = "1002","traceNo" = "1002","areaId" = "1002","productId" = "1002","quantity" = 1,"extend" = "1002"}
]

如果返回错误码GameSDKErrorInvalidGtoken,则表明登录态失效,需要重新调用登录接口。

7.4. 上报领奖信息结果接口

  • 上报领奖信息结果接口定义
/**
 上报领奖信息结果接口
 @param orderList   订单号数组
 @param callback    回调
 */
+ (void)reportAwardResult:(NSArray<NSString *> * _Nonnull)orderList
                 callback:(GameSDKCallback _Nullable)callback;
  • 上报领奖信息结果接口调用示例
[GameSDK reportAwardResult:@[@"1000"] callback:^(NSInteger code, NSString * msg, NSDictionary * data) {
    if (code == GameSDKSucceed) {
        NSLog(@"Report award result succeed!");
    } else {
        NSLog(@"Report award result failed, %@.", msg);
    }
}];
  • 上报领奖信息结果接口回调说明

    如果返回错误码GameSDKErrorInvalidGtoken,则表明登录态失效,需要重新调用登录接口。

8. 错误码说明

| code | definition | 描述 |
| ----- |:-----------------------------------:|:----------:|
| 0 | GameSDKSucceed | 成功 |
| -1011 | GameSDKErrorBadServerResponse | 坏的服务器响应 |
| -1015 | GameSDKErrorCannotDecodeRawData | 无法解析响应原始数据 |
| -1016 | GameSDKErrorCannotDecodeContentData | 无法解析响应data数据 |
| -101 | GameSDKErrorEmptyAppId | AppId为空 |
| -102 | GameSDKErrorNotInitialized | SDK未初始化 |
| -103 | GameSDKErrorNotLogined | SDK未登录 |
| 3001 | GameSDKErrorTicketTimeout | 登录ticket过期 |
| 67 | GameSDKErrorInvalidGtoken | 获取和上报订单时gtoken失效 |
| 401 | GameSDKErrorNotPermittedGtoken | 上传和下载存档时gtoken无权限 |