# IOS游戏SDK-对接文档
# 注意
此SDK对接文档，标注必接的接口请在第一次接入时则必须接入，其余未标注说明必接的接口，可视运营情况及相关说明，再进行对接。
# 获取对接物料
开始对接时，我方会提供如下3个参数，如未获取，请联系我方运营或技术获取
| 参数字段 | 参数说明 | 示例 |
|---|---|---|
| unionPacketCode | 对接的唯一包ID | 10000 |
| unionGameId | 游戏ID | 10000 |
| gameKey | 登录加密Key | 1111 |
| gamePayKey | 支付加密Key | 1111 |
# 集成IOS客户端SDK
# SDK下载
# SDK 配置
导入资源
- 导入 framework ，
Target->General->Embedded Binaries, 点击添加按钮导⼊Frameworks文件夹里的所有 Framework。 实际详情请参考Demo。
Target->Build Settings->Enable Bitcode设置为NO
Target->Build Settings->Linking->Other Linker Flags添加-ObjC
配置Info.plist
在 info.plist 下面添加如下代码
以下
unionGameId/unionPacketCode参数我方运营提供
<key>unionGameId</key>
<string>11111</string>
<key>unionPacketCode</key>
<string>1000023121213549</string>
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
# 接口说明
# 对接 SDK 文件中引入 SDK 头文件
#import "union/UnionGameSDK.h"
# 显示IOS Webview
常用于弹出用户协议 登录协议，分级
[[UnionGameSDK share] openBrowserWithURL:@"https://baidu.com"];
# AppDelegate 生命周期接口(必接)
#import "AppDelegate.h"
#import "union/UnionGameSDK.h"
@interface AppDelegate ()
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
return [[UnionGameSDK share]application:application didFinishLaunchingWithOptions:launchOptions];
}
- (void)openWebviewWithURL:(nonnull NSString *)url {
[[UnionGameSDK share] openWebviewWithURL:url];
}
- (void)openBrowserWithURL:(nonnull NSString *)url {
[[UnionGameSDK share] openBrowserWithURL:url];
}
- (void)applicationWillResignActive:(UIApplication *)application{
[[UnionGameSDK share] applicationWillResignActive:application];
}
- (void) applicationDidEnterBackground:(UIApplication *)application{
[[UnionGameSDK share] applicationDidEnterBackground:application];
}
- (void) applicationWillEnterForeground:(UIApplication *)application{
[[UnionGameSDK share] applicationWillEnterForeground:application];
}
- (void) applicationDidBecomeActive:(UIApplication *)application{
[[UnionGameSDK share] applicationDidBecomeActive:application];
}
- (void) applicationWillTerminate:(UIApplication *)application{
[[UnionGameSDK share] applicationWillTerminate:application];
}
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
[[UnionGameSDK share] application:application didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error{
[[UnionGameSDK share] application:application didFailToRegisterForRemoteNotificationsWithError:error];
}
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(nonnull NSDictionary *)userInfo{
[[UnionGameSDK share] application:application didReceiveRemoteNotification:userInfo];
}
-(UIInterfaceOrientationMask)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(nullable UIWindow *)window{
return [[UnionGameSDK share] application:application supportedInterfaceOrientationsForWindow:window];
}
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{
return [[UnionGameSDK share] application:application handleOpenURL:url];
}
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
return [[UnionGameSDK share]application:annotation openURL:url sourceApplication:sourceApplication annotation:annotation];
}
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options{
[[UnionGameSDK share]application:application openURL:url options:options];
return YES;
}
@end
# 监 SDK注销(必接)
[[UnionGameSDK share]addLogoutCallback:^(BOOL status, NSString * _Nullable msg, NSDictionary * _Nullable result) {
if(status){
NSLog(@"SDK注销成功,回到登录界面");
}else{
NSLog(@"SDK注销失败");
}
}];
# SDK初始化(必接)
所有其他接口均需要在初始化成功回调后使用
# 调用说明
[[UnionGameSDK share]initSDK:^(BOOL status, NSString * _Nullable msg, NSDictionary * _Nullable result) {
if(status){
NSLog(@"SDK初始化成功");
}else{
NSLog(@"SDK初始化失败");
}
}];
# 登录接口(必接)
# 调用说明
[[UnionGameSDK share]login:^(BOOL status, NSString * _Nullable msg, NSDictionary * _Nullable result) {
if(status){
NSLog(@"SDK登录成功成功");
}else{
NSLog(@"SDK登录失败");
}
}];
# 回调示例
result
{
"signVer": 1,
"ts": "1722235986982",
"sign": "344e5d3152d8b08379806d2dd0001e27",
"publishName": "出版单位",
"gameId": 100005,
"icp": "2323",
"tags": "",
"isbn": "ISBN",
"auth": 0,
"cid": "10000",
"privacyUrl": "https:\/\/ai-bot.cn\/sites\/4189.html",
"softName": "著作权人",
"softNo": "软件登记号",
"authNo": "审批文号",
"operName": "运营单位",
"serviceUrl": "https:\/\/ai-bot.cn\/sites\/4189.html",
"extend": "{}",
"openId": "u-10000-579b2fe6d188e1a82dcb06cfff96ebf6",
"pcode": "1000023121213549"
}
# 返回的参数说明
| 方法 | 返回类型 | 例子 | 备注 |
|---|---|---|---|
| openId | String | u-10000-579b2fe6d188e1a82dcb06cfff96ebf | 用户唯一标识 |
| gameId | int | 100000 | 游戏ID |
| cid | String | 100000 | 渠道ID |
| ts | String | 1701931432675 | 毫秒级时间戳 |
| signVer | int | 1 | 签名版本，当前默认1 |
| sign | String | 642029cf0c290e38a95ef59d232b338f | 登录签名 |
| privacyUrl | String | xx | 隐私协议url |
| serviceUrl | String | xx | 用户协议url |
| isbn | String | xx | ISBN |
| softName | String | xx | 著作权人名称 |
| publishName | String | xx | 出版单位名称 |
| authNo | String | 10000 | 批文号 |
| operName | String | 10000 | 运营单位 |
| softNo | String | 10000 | 软著登记号 |
| icp | String | 10000 | Icp备案号 |
| pcode | String | 10000 | 游戏渠道包ID |
| getExtend() | String | {"age":"16 年龄分级","ageUrl":"16 年龄分级地址"} | 附加控制参数 |
# 服务端登录验证(必接)
根据登录接口返回的UnionTK字段参数判断以下等式是否成立，成立则通过验证，务必在服务端进行
sign=md5(openId+"|"+gameId+"|"+ts+"|"+gameKey)
# 角色上报接口(必接)
# 调用说明
[[UnionGameSDK share] report:dict callback:^(BOOL status, NSString * _Nullable msg, NSDictionary * _Nullable result) {
if(status){
NSLog(@"SDK上报成功");
}else{
NSLog(@"SDK上报失败");
}
}];
# 参数说明
方法传入参数UnionAnalyticsParams，其属性如下
| 方法 | 类型 | 例子 | 备注 |
|---|---|---|---|
| openId | String | u-10000-579b2fe6d188e1a82dcb06cfff96ebf | 用户唯一标识 |
| gameId | int | 100000 | 游戏ID |
| ts | String | 1701931432675 | 毫秒级时间戳 |
| signVer | int | 1 | 签名版本，当前默认1 |
| sign | String | 642029cf0c290e38a95ef59d232b338f | 上报签名，看下面签名规则 |
| roleId | String | 147176212 | 角色ID |
| roleName | String | 齐天大圣 | 角色名称 |
| roleLevel | String | 10 | 角色等级 |
| roleVipLevel | String | 2 | 角色VIP等级 |
| roleFight | String | 12612 | 角色战力 |
| serverId | String | 1001 | 区服ID |
| serverName | String | 1001服 | 区服name |
| gameExtend | String | "{}" | json格式字符串,扩展参数 |
# 签名规则
sign=md5(gameId+"|"+openId+"|"+roleId+"|"+serverId+"|"+ts+"|"+gameKey);
# 退出登录(必接)
当游戏内含有退出按钮或游戏发生顶号时，游戏方可主动调用退出接口
# 调用说明
[[UnionGameSDK share]logout];
# 支付接口(必接)
# 调用说明
[[UnionGameSDK share] purchase:dict callback:^(BOOL status, NSString * _Nullable msg, NSDictionary * _Nullable result) {
if(status){
NSLog(@"SDK支付成功:%@",[self json2Str:result]);
}else{
NSLog(@"SDK支付失败");
}
}];
# 参数说明
方法传入参数NSDictionary，其key如下
| 方法 | 类型 | 例子 | 备注 |
|---|---|---|---|
| openId | String | u-10000-579b2fe6d188e1a82dcb06cfff96ebf | 用户唯一标识 |
| gameId | int | 100000 | 游戏ID |
| ts | String | 1701931432675 | 毫秒级时间戳 |
| signVer | int | 1 | 签名版本，当前默认1 |
| sign | String | 642029cf0c290e38a95ef59d232b338f | 支付下单签名，看下面签名规则 |
| roleId | String | 147176212 | 角色ID |
| roleName | String | 齐天大圣 | 角色名称 |
| roleLevel | String | 10 | 角色等级 |
| roleVipLevel | String | 2 | 角色VIP等级 |
| roleFight | String | 12612 | 角色战力 |
| serverId | String | 1001 | 区服ID |
| serverName | String | 1001服 | 区服名称 |
| gameOrderCode | String | 16253651265x17631212 | 游戏订单号 |
| gameOrderCustomInfo | String | 16253651265x17631212 | 订单自定义字符串，支付回调时会原样返回 |
| gameProductCode | String | 1001 | 游戏商品计费点 |
| gameProductName | String | 100元宝 | 游戏商品名称 |
| gameProductPrice | int | 100 | 支付金额，单位（分） |
| gameExtend | String | 100 | json格式字符串,扩展参数 |
# sign签名规则
sign=md5(gameId+"|"+openId+"|"+roleId+"|"+serverId+"|"+gameOrderCode+"|"+gameProductCode+"|"+gameProductPrice+"|"+ts+"|"+gamePayKey);
# 服务端支付回调(必接)
游戏方需要根据下面文档对接完成后提供URL地址给到我方进行配置，游戏在正常支付完成后，游戏方会收到我方接口调用。
# 回调通知方式
HTTP POST
# 回调通知格式
application/json
# 回调参数说明
本协议中所有字符串使用UTF8编码
| 参数 | 类型 | 例子 | 备注 |
|---|---|---|---|
| openId | String | u-10000-579b2fe6d188e1a82dcb06cfff96ebf | 用户唯一标识 |
| gameId | int | 100000 | 游戏ID |
| ts | String | 1701931432675 | 毫秒级时间戳 |
| signVer | int | 1 | 签名版本，当前默认1 |
| sign | String | 642029cf0c290e38a95ef59d232b338f | 支付下单签名，看下面签名规则 |
| roleId | String | 147176212 | 角色ID |
| serverId | String | 1001 | 区服ID |
| orderCode | String | i-10000010000-20231109150147645-745gm | 我方订单号 |
| gameOrderCode | String | 16253651265x17631212 | 游戏方调起支付时传入的游戏订单号 |
| gameOrderCustomInfo | String | 16253651265x17631212 | 游戏方调起支付时传入的游戏自定义参数 |
| gameProductCode | String | 1001 | 游戏商品计费点 |
| gameProductPrice | int | 100 | 支付金额，单位（分） |
| isSandBox | int | 0 | 是否测试订单，1-是测试订单，0-否 |
| discountPrice | int | 0 | 优惠金额，单位(分) |
# 回调签名说明
sign=md5(`${gameId}|${gameOrderCode}|${orderCode}|${gameProductPrice}|${gameProductCode}|${serverId}|${roleId}|${openId}|${ts}|${gamePayKey}`);
# 回调返回说明
返回类型：字符串
- 成功返回小写字母："ok"
- 失败返回："失败原因"
# 回调接口其他注意事项
- 游戏接入时，必须验证订单信息跟游戏方本地下订单信息进行匹配，防止中途被人串改
- sign值必须要验证，
gamePayKey必须由服务端保存，防止泄漏 - 订单有可能会出现多次同步，请做好幂等性，并返回“ok”
- 同步失败情况，我方会根据定义好的规则进行多次尝试