KUUKI文档中心

# 海外 iOS 游戏 SDK 对接文档

阅读对象：游戏方 iOS 接入
更新时间：2021.10.27
修订版本：1.0.2
修订人员：QQ-3008792067

# 温馨提示

游戏方根据文档对接完后请提供工程包哦。

# 版本更新说明

日期 接口 备注
22020-12-01 支付下订单 下单接口上报计费点 tradecode
22021-10-27 接口新增与改动 详情如下

# 海外 iOS SDK 下载

HwYzxiOSGameSDK-v1.0.2

# Xcode 工程的配置

  1. 将SDK文件拖入Xcode工程中，如图所示：

1

  1. Target->Build Settings->Enable Bitcode 设置为NO，如图所示：

2

  1. Target->Build Settings->Linking->Other Linker Flags 添加-ObjC，如图所示：

3

  1. Target->Signing & Capabilities 点击添加 Capability，如图所示：

4

  1. Target->Info，添加行App Transport Security Settings，设置Allow Arbitrary Loads为YES，如图所示：

5

  1. Target->Build Phases->Link Binary With Libraries，设置 FacebookSDK 的状态Status为Optional，如图所示：

6

# SDK 代码接入

  • 导入 SDK 头文件
#import <TopSDK/Top2Port.h>

# AppDelegate 生命周期（必接）

  • 在AppDelegate.m中的接入方法，如下所示：
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [Top2Port application:application didFinishLaunchingWithOptions:launchOptions];

    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options{

    return [Top2Port application:app openURL:url options:options];
}

- (void)applicationDidBecomeActive:(UIApplication *)application {

    [Top2Port activateApp];
}

# 初始化接口（必接）

  • 其他接口在此接口返回成功后才可调用，如下所示：
    [Top2Port activateClient:^(BOOL isSuccess) {
        if (isSuccess) {
            //SDK初始化，通知游戏处理...

        }
    }];

# 登录接口（必接）

  • 只有登录成功后result有数据，否则为nil，如下所示：
    [Top2Port interfaceWithLogin:^(NSDictionary * _Nullable result) {
        /**
         *  登录成功，返回参数 NSDictionary 类型
         *  {
         *      channelid = 10231;  //渠道ID
         *      openid = "10231-9f5c18edb982331e8f6d44a739d7d0ac";
         *      sign = b4b9234ac3018541ecd12cb80803a9d1;
         *      ts = 1609988474361; //时间戳
         *  }
         */
    } observerSwitch:^{
        //SDK主动登出，通知游戏处理

    }];

# 登出（必接）

  • 游戏方主动调用 SDK 的登出接口，实现登出或切换账号，如下所示：
    [Top2Port logoutClient:^{
        //已登出完成，通知游戏处理...

    }];

# 支付下订单（必接）

  • 游戏方传入参数不能为nil，为空时传入空字符串，如下所示：
    NSString *count = @"1";              //数量，默认为1
    NSString *paybill = @"60";           //金额，单位为美分
    NSString *warename = @"元宝";         //商品名称
    NSString *extstr = @"";              //拓展参数，一般是游戏方订单号
    NSString *tradecode = @"com.yzx.6";  //计费点
    NSString *signature = @"xsfg";       //签名，服务端生成
    NSString *roleid = @"10000";         //角色id
    NSString *rolelevel = @"99";         //角色等级
    NSString *rolename = @"德玛西亚之力";  //角色名
    NSString *serverid = @"1";           //区服id
    NSString *servername = @"峡谷之巅";   //区服名称

    [Top2Port paymentWithCount:count
                       paybill:paybill
                      warename:warename
                        extstr:extstr
                     tradecode:tradecode
                     signature:signature
                        roleid:roleid
                     rolelevel:rolelevel
                      rolename:rolename
                      serverid:serverid
                    servername:servername];

# 上报角色信息（必接）

  • 游戏方传入参数不能为nil，为空时传入空字符串，如下所示：
    NSString *type = @"1";               //数据类型: 1-选服,2-创角,3-登录,4-升级,5-退出
    NSString *combat = @"10000";         //战力值
    NSString *roleid = @"10000";         //角色id
    NSString *rolelevel = @"99";         //角色等级
    NSString *rolename = @"德玛西亚之力";  //角色名
    NSString *serverid = @"1";           //区服id
    NSString *servername = @"峡谷之巅";   //区服名称

    [Top2Port submitReportType:type
                        combat:combat
                        roleid:roleid
                     rolelevel:rolelevel
                      rolename:rolename
                      serverid:serverid
                    servername:servername];

# 分享功能（必接）

  • 游戏需要添加分享按钮，分享成功后发放奖励
    //分享类型（ 1-链接话题   2-文本图片 ）
    UIImage *img = [UIImage imageNamed:@"icon_apple"];
    NSString *link = @"http://kuukigame.com/";
    NSString *text = @"快来一起玩耍~";

    [Top2Port shareWithType:1 image:img links:link quote:text handle:^(BOOL isSuccess) {
        if (isSuccess) {
            //分享成功，通知游戏发放奖励...
        }
    }];

# 游戏埋点（必接）

  • 由我方运营提供详情文档，游戏调用 SDK 打点接口，如下所示：
    [Top2Port reportEvent:@"xxx"];

# 服务端支付回调（必须接入）

支付回调验证（因数据都是模拟的，所以需要调试支付回调，请联系我方的技术，进行手动回调结果，进行测试 用户在游戏中成功充值后，SDK 平台服务器将调用游戏方提供的支付回调地址通知游戏方订单支付状态

  • # 通知方式

HTTP POST

  • # 请求回调地址：

http://cp.xx.com/cburl 接入方提供

请求参数示例：

feemoney=600&orderid=b%26c&openid=a%25b&appid=10001&paystatus=1&sign=4bf106f47cdbe30e5e3793b77788cd22&extstr=abc%25abc&paytime=1551668337286&serverid=1&prover=1

通知接口请求时的详细参数定义如下(本协议中所有字符串要求 UTF-8 字符串)：

参数名 参数类型 是否必须 示例 参数说明
appid string 是 11111 应用 ID
extstr string 是 aasdfagagaga 在客户端由 CP 应用指定的额外参数，一般为 CP 订单号 encode
feemoney string 是 100 金额（分）
openid string 是 aasdfagagaga 用户唯一标识 encode
orderid string 是 aasdfagagaga KUUKIGAME的订单号 encode
paystatus string 是 1 支付状态 1-支付成功,2-支付失败
paytime string 是 1532168473000 支付时间，时间戳
prover string 是 1 协议版本号
serverid string 是 1 充值区服 ID
sign string 是 aasdfagagaga 上述内容的数字签名，方法在下文会说明

sign 签名规则

  • # 对接收到的 encode 的字段进行 decode，decode 后的 post 内容如下

feemoney=600&orderid=b&c&openid=a%b&appid=10001&paystatus=1&sign=4bf106f47cdbe30e5e3793b77788cd22&extstr=abc%abc&paytime=1551668337286&serverid=1&prover=1

  • # 去除 sign 后对所有字段进行字典排序,得到待签名串如下

appid=10001&extstr=abc%abc&feemoney=600&openid=a%b&orderid=b&c&paystatus=1&paytime=1551668337286&prover=1&serverid=1

  • # 对签名串进行签名,方法如下

sign=md5(上面去除sign后字典排序的字符串+{SecretKey} )

  • # 游戏方处理返回数据

  1. 游戏方拿到参数，必须做 sign 的验证，并对 feemoney 金额做匹配,以防止恶意串改。
  2. 游戏方在接收到通知后，必须在 HTTP 正文中响应返回 OK，否则我方会视为错误并重新发起。
  3. 游戏方根据 orderid 字段做排重处理,防止多次发放道具.如果为重复的订单则返回 OK 字符串。

  • # 同步失败重新发起回调机制

无论是 HTTP 连接失败还是 CP 服务器端没有返回 OK，支付服务器都会负责进行重新发起回调，服务器会按照一定的时间间隔重新发起回调同步接口，时间间隔为：10 秒,30 秒,1 分钟,5 分钟,30 分钟,1 小时,2 小时,6 小时,12 小时,24 小时。

← 三、海外H5游戏SDK对接文档 →