国内游戏对接文档--IOS
版本
当前版本及SDK下载
当前版本 1.4.3
历史版本
SDK功能
1.登录、切换账号、退出、登录 2.实名认证 3.支付 4.广告 5.事件上报 6.数数科技信息上报与用户属性设置
1.工程配置
1.1 U8打包
项目需使用U8工具进行打包，请按照以下步骤进行U8打包
- 将U8打包工具放在任意位置，确认channels中MCODO和common目录下config.json参数是否正确
| 名称 | 描述 |
|---|---|
| product_name | 游戏简称，例如妙酷测试可写为mkcs |
| AppId | U8AppID，可和对接人员确认参数是否正确 |
| AppKey | U8AppKey，可和对接人员确认参数是否正确 |
| U8Url | U8Url，可和对接人员确认参数是否正确 |
MCOOS目录下config.js配置详解
| 名称 | 描述 |
|---|---|
| desc | 游戏介绍，可直接填入游戏名称，例如妙库测试 |
| CFBundleIdentifier | 项目bundleID |
| Channel | u8渠道，可和对接人员确认参数是否正确 |
| name | 渠道名称，默认为MCODO，请勿修改 |
| key | 渠道key，可和对接人员确认参数是否正确 |
| gameID | 渠道游戏id，可和对接人员确认参数是否正确 |
| payKey | 渠道游戏支付key，可和对接人员确认参数是否正确 |
| channel | 渠道，可为空 |
| appsFlyerDevKey | AppsFlyer devKey值，需要在appsFlyer进行申请 |
| appleAppID | 苹果应用ID，需要在苹果应用后台获取。苹果登录或者绑定与AppsFlyer信息上报必填 |
| googleClientID | 谷歌应用ClientID，需要在谷歌应用后台获取。谷歌登录或者绑定必填 |
| fbAppId | Facebook应用ID，需要在Facebook应用后台获取。Facebook登录或者绑定必填 |
| fbDisplayNAame | Facebook应用名称，需要在Facebook应用后台获取。Facebook登录或者绑定必填 |
| gooleAppId | 谷歌应用AppID，需要在谷歌应用后台获取。谷歌登录或者绑定必填 |
- cd进入buildscript目录，执行以下代码
./build.py 游戏工程的xcodeproj文件地址 ../u8test -n
- 运行后会选择渠道，输入‘MCODO’
- 成功后会生成 工程名.MCODO包
- 使用XCode打开 工程名.MCODO包，填入开发者账号
2.SDK接口
2.1 初始化(必接)
初始化应该在程序启动时调用, 也就是在didFinishLaunchingWithOptions方法里
#import <U8SDKCore/U8SDK+AppDelegate.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
NSDictionary *sdkconfig = [[NSBundle mainBundle] objectForInfoDictionaryKey:@"U8SDK"];
[[U8SDK sharedInstance] initWithParams:sdkconfig];
[[U8SDK sharedInstance] application:application didFinishLaunchingWithOptions:launchOptions];
[[U8Analytics sharedInstance] startLevel:@"1"];
return YES;
}
2.2 登录接口（无账号体系）
登录接口需要在 OnPlatformInit 回调内调用
[[U8SDK sharedInstance] loginCustom:@"test001"];
2.3 登录接口（有账号体系）
登录接口需要在 OnPlatformInit 回调内调用
[[U8SDK sharedInstance] login];
2.4 个人中心接口
[[U8SDK sharedInstance] showAccountCenter];
2.5 激励视频广告接口
2.5.1 拉取广告
其中参数为NSString类型的广告位ID，只需要第一次启动游戏时候调用。
[[U8SDK sharedInstance] loadTopOnAd:@"xxxx"];
2.5.2播放广告
其中ads_type广告位置ID，例如宝贝有转盘、登录、探险等广告位置 placementId 广告位ID
NSDictionary *dic = @{
@"ads_type" : @"zhuanpan",
@"placementId":@"xxx",
};
[[U8SDK sharedInstance] rewardedVideo:dic];
信息上报(必接)
U8UserExtraData* extraData = [[U8UserExtraData alloc] init];
extraData.dataType = TYPE_ENTER_GAME;
extraData.roleID = @"testRole";
extraData.roleName = @"角色名称";
extraData.serverID = 1;
extraData.serverName = @"第一区";
extraData.roleLevel = @"1";
extraData.moneyNum = 100;
extraData.roleCreateTime = time(NULL);
extraData.roleLevelUpTime = time(NULL);
[[U8SDK sharedInstance] submitExtraData:extraData];
2.6 数据上报接口
调用 U8User.getInstance().submitExtraData(UserExtraData extraData)，其中，UserExtraData就是游戏内玩家的数据，比如在选择服务器时，extraData中的dataType为
| data_type值 | 含义 |
|---|---|
| TYPE_SELECT_SERVER | 选择服务器 |
| TYPE_CREATE_ROLE | 角色创建 |
| TYPE_ENTER_GAME | 进入游戏 |
| TYPE_LEVEL_UP | 角色升级 |
| TYPE_EXIT_GAME | 退出游戏 |
| TYPE_SHOW_RV | 看完广告 |
| TYPE_DEVICE_START | 设备启动 |
| TYPE_LOGIN_PID | 设备PID登陆成功 |
| TYPE_BIND_ACCOUNT | 绑定账号成功 |
| TYPE_DEVICE_ENTER_GAME | 设备成功进入游戏 |
| TYPE_DEVCIE_ENTER_SERVER | 设备开始进入服 |
| TYPE_OTHER_EVENT | 其他上报信息 |
| TYPE_TUTORIAL_COMPLETION | 角色完成引导 |
| TYPE_LOGIN_ROLE | 角色登录 |
| TYPE_DEVICE_LOAD | 设备加载过程,可能会分几步,所以此上报需要填写lodingEvent字段 |
| TYPE_RETENTION_2 | 留存两天 |
| TYPE_RETENTION_3 | 留存三天 |
!> 选择服务器时，因为还没有进入游戏，无法知道角色数据，extraData中只需要传入服务器信息即可。
关于U8UserExtraData 数据结构，其中设备加载过程需填写loadingEvent字段值
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| dataType | int | 调用时机 |
| serverID | String | 玩家所在服务器的ID |
| serverName | String | 玩家所在服务器的名称 |
| roleID | String | 玩家角色ID |
| roleName | String | 玩家角色名称 |
| roleLevel | String | 玩家角色等级 |
| moneyNum | String | 当前角色身上拥有的游戏币数量 |
| roleCreateTime | long | 角色创建时间，从1970年到现在的时间，单位秒,必须传入真实的数据，否则UC审核不过 |
| roleLevelUpTime | long | 角色等级变化时间，从1970年到现在的时间，单位秒 |
| vip | String | 玩家VIP等级 |
| loadingEvent | String | 表示加载过程的不同阶段，格式为loading_xxx |
| eventName | String | 当data_type值为TYPE_OTHER_EVENT时必填，af上报的事件名 |
| param | NSDictionary | af上报事件的参数 |
2.7 订阅恢复(选接)
//用户点击订阅恢复时，游戏需传入的参数
//params(NSDictionary类型)中的参数如下：
//extra:订阅恢复时，游戏透传的参数
//serverId:玩家所在服id
[[U8SDK sharedInstance] restoreCompletedTransactions:params];
2.8 获取商品信息(选接)
[[U8SDK sharedInstance] getProductsInfo];
2.9 支付充值(必接)
U8ProductInfo* productInfo = [[U8ProductInfo alloc] init];
productInfo.productName = @"礼包1";
productInfo.productDesc = @"礼包1";
productInfo.productId = @"libao1";
productInfo.price = [NSNumber numberWithInt:30];
productInfo.buyNum = 1;
productInfo.coinNum = 900;
productInfo.userName = @"test001";
productInfo.roleId = @"12345";
productInfo.roleName = @"角色";
productInfo.roleLevel = @"66";
productInfo.serverId = @"1";
productInfo.serverName = @"桃源";
productInfo.vip = @"1";
productInfo.notifyUrl = @"http://110.54.33.45/game/pay/notify";
[[U8SDK sharedInstance] pay:productInfo];
关于U8ProductInfo对象：
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| productId | NSString | 充值商品ID，游戏内的商品ID |
| productName | NSString | 商品名称，比如100元宝，500钻石... |
| productDesc | NSString | 商品描述，比如 充值100元宝，赠送20元宝 |
| price | NSNumber | 充值金额(单位：元) |
| buyNum | NSInteger | 购买数量，一般都是1 |
| coinNum | NSInteger | 玩家当前身上剩余的游戏币 |
| userName | NSString | 玩家唯一标识 |
| serverId | NSString | 玩家所在服务器的ID |
| serverName | NSString | 玩家所在服务器的名称 |
| roleID | NSString | 玩家角色ID |
| roleName | NSString | 玩家角色名称 |
| roleLevel | NSString | 玩家角色等级 |
| vip | NSString | 玩家vip等级 |
| notifyUrl | NSString | 游戏服务器支付回调地址，渠道SDK支付成功，异步通知U8Server，U8Server根据该地址，通知游戏服务器发货 |
| extension | NSString | 支付成功之后，U8Server通知游戏服务器时，原样返回给游戏服务器 |
上面代码写好之后, 这个xcode就是以后打渠道包的母工程。 接下来，就可以通过U8SDK一键打包工具， 打出各个渠道的渠道包。
2.10 获取用户信息(选接)
-(void)getUserInfoBack:(void (^)(id result))successCallBack failCallBack:(void(^)(id error))failCallBack
参考：
[[U8SDK sharedInstance] getUserInfoBack:^(id result) {
NSLog(@"获取用户信息成功，info = %@",result);
} failCallBack:^(id error) {
NSLog(@"获取用户信息失败，error = %@",error);
}];
其中获取用户信息成功返回内容
| 参数名称 | 参数说明 |
|---|---|
| userID | 用户唯一标识 |
| sdkUserID | 平台userid |
| country | 国家 |
| firstChargeTime | 首次付费时间 |
| lastChargeTime | 最近一次付费时间 |
| regTime | 注册时间 |
| retainedDays | 活跃天数 |
| sdkUserID | 平台userid |
| totalCharge | 总充值金额 |
| totalChargeNum | 总充值次数 |
2.11 实名认证接口(自定义实名认证必接)
2.11.1 实名认证流程
2.11.2 上报实名认证信息
游戏是否需要弹出游戏自定义实名认证界面，请结合登录成功回调(4.3)与可以进入游戏回调(4.12)进行判断联合判断。
//name:名字
//idCard:身份证号
/**
successCallBack 实名认证成功
NSDictionary值包含userID、idCardStatus玩家身份状态 1:小于8岁; 2:大于8岁小于16岁;3:大于18岁;4:假身份(格式符合要求的身份证);5:大于16岁小于18岁
*/
/**
failCallBack 实名失败
NSDictionary值包含userID、idcardStatus 玩家身份状态 0:没有身份认证; 1:小于8岁; 2:大于8岁小于16岁;3:大于18岁;4:假身份(格式符合要求的身份证);5:大于16岁小于18岁
*/
-(void)checkUserRealName:(NSString *)name idCard:(NSString *)idCard successCallBack:(void (^)(id result))successCallBack failCallBack:(void(^)(id error))failCallBack;
2.12 注销账号接口
-(void)cancelAccount;
2.13 切换账号接口
-(void)switchAccount;
2.14 绑定账号接口
-(void)bindAccount;
2.15 AppsFlyer自定义事件上报接口
-(void) gameEvent:(NSString *)eventName withValues:(NSDictionary *)values;
2.16 分享接口
!> 分享说明
用户设置的图片大小最好不要超过250k，最好不要分享1M以上的图片。
用户分享消息给微信好友，以及分享到朋友圈，开发者将无法获知用户是否分享完成，默认分享成功。
用户分享消息给QQ好友，以及分享到QQ空间，若选择关闭分享，将无法跳转回游戏，开发者将无法获知用户是否分享完成。
若需要支持抖音分享平台，videoData参数不可为空。
支持平台分享样式总览
平台 支持样式 微信好友 纯文本、图片、视频 微信朋友圈 纯文本、图片、视频 新浪微博 纯文本、图片、视频 QQ 纯文本、图片、视频 QQ空间 纯文本、图片、视频 抖音 图片、视频
U8ShareInfo参数内容
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| shareType | U8ShareType | 其中纯文本为U8ShareTypeText=0，图片为U8ShareTypeImage=1，视频为U8ShareTypeVideo=2 |
| text | NSString | 文字内容，当shareType为U8ShareTypeText（纯文本）该值必传 |
| imgData | id | 图片，支持UIImage、NSData，image_url。当type为U8ShareTypeImage（图片）时必传 |
| title | NSString | 标题，当shareType为U8ShareTypeVideo（视频）该值必传 |
| descr | NSString | 描述，当shareType为U8ShareTypeVideo（视频）该值必传 |
| thumbImg | id | 缩略图,UIImage或者NSData类型，或者image_url。当type为U8ShareTypeVideo（视频）该值必传 |
| videoName | NSString | 视频名称，当shareType为U8ShareTypeVideo（视频）该值必传 |
| videoUrl | NSString | 视频网页的url，若shareType为U8ShareTypeVideo（视频）该值必传 |
| videoData | NSData | 视频数据，若shareType为U8ShareTypeVideo（视频）且需要支持抖音平台时该值必传。 |
-(void)share:(U8ShareInfo*)params;
3.AppDelegate事件处理
需要在AppDelegate以下对应的生命周期方法中调用U8SDK种对应这些方法：
-(void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
[[U8SDK sharedInstance] application:application didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}
-(void)application:(UIApplication *)application didReceiveRemoteNotification:(nonnull NSDictionary *)userInfo
{
[[U8SDK sharedInstance] application:application didReceiveRemoteNotification:userInfo];
}
-(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
[[U8SDK sharedInstance] application:application didReceiveRemoteNotification:userInfo];
}
-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
[[U8SDK sharedInstance] application:application didReceiveLocalNotification:notification];
}
- (void)applicationWillResignActive:(UIApplication *)application {
[[U8SDK sharedInstance] applicationWillResignActive:application];
}
- (void)applicationDidEnterBackground:(UIApplication *)application {
[[U8SDK sharedInstance] applicationDidEnterBackground:application];
}
- (void)applicationWillEnterForeground:(UIApplication *)application {
[[U8SDK sharedInstance] applicationWillEnterForeground:application];
}
- (void)applicationDidBecomeActive:(UIApplication *)application {
[[U8SDK sharedInstance] applicationDidBecomeActive:application];
}
- (void)applicationWillTerminate:(UIApplication *)application {
[[U8SDK sharedInstance] applicationWillTerminate:application];
}
-(BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
return [[U8SDK sharedInstance] application:application handleOpenURL:url];
}
-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
return [[U8SDK sharedInstance] application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
}
4.设置SDK回调代理
在初始化成功后, 还需要设置U8SDK的回调函数, 回调对象需要实现U8SDKDelegate的各个接口
[[U8SDK sharedInstance] setDelegate:self];
渠道SDK中初始化成功，登录成功，登出成功，支付成功等，会回调到该接口。比如u8sdkdemo中DemoViewController.m中这些接口的实现。
4.1
-(UIView *)GetView
{
return [self GetViewController].view;
}
-(UIViewController *)GetViewController
{
return self;
}
4.2 初始化成功回调
//初始化成功回调。 渠道SDK初始化成功，无回调该参数
-(void) OnPlatformInit:(NSDictionary*)param
{
[self SendCallback:"OnInitSuc" withParams:param];
}
4.3 登录成功回调
//param(NSDictionary类型)中的参数如下：
//userID:U8Server生成的唯一用户ID
//sdkUserID:渠道SDK平台用户唯一ID，游戏服务器需要将游戏账户ID和该sdkUserID进行绑定。
//isAdult:布尔值，若为成年人返回为true，其他(未成年或未实名)返回false
//username:U8Server生成的用户名，比如234234234.uc,4353453453.baidu,65756756756.360
//sdkUserName:渠道SDK平台用户名，可能为空，部分渠道SDK没有返回用户名
//token:U8Server生成的会话ID，游戏服务器拿该字段去U8Server做二次登录验证
//extension:U8Server返回的扩展字段，部分渠道SDK需要，游戏中无需使用该字段的值
//timestamp:U8Server生成的时间戳，游戏服务器去U8Server做二次登录验证时，传给U8Server
//third_login_type 第三方登陆类型 0:游客,3:apple,4:weixin,5:qq,6:jiguang
//isCustomRealName 是否需要游戏自定义实名认证界面 Bool值
//idcardStatus 玩家身份状态 0:没有身份认证; 1:小于8岁; 2:大于8岁小于16岁;3:大于18岁;4:假身份(格式符合要求的身份证);5:大于16岁小于18岁
//shareOpen 是否开启分享功能 0.不开启 1.开启
-(void) OnUserLogin:(NSDictionary*)param
{
[self SendCallback:"OnLoginSuc" withParams:param];
}
4.4 支付成功回调
//客户端调用渠道SDK支付成功，一般不需要做逻辑处理，最终支付成功，以U8Server回调通知到游戏服务器为准。
//无参数
param返回值包括state与extension
其中state为支付状态
|state值|参数说明|
|--|--|
|0|成功|
|1|用户取消支付|
|2|支付失败，网络错误|
|3|支付失败，支付标识非法|
|4|支付失败，支付信息缺失|
-(void) OnPayPaid:(NSDictionary*)param
{
[self SendCallback:"OnPaySuc" withParams:param];
}
4.5 事件上报回调
-(void)OnEventCustom:(NSString *)eventName params:(NSDictionary *)params{
NSLog(@"event Name %@ params %@",eventName,params);
}
4.6 数数科技信息上报与用户属性设置
//eventType: 0:发送事件；1：用户数据上报set；2：用户数据上报setOnce；3：用户数据上报add；4.公共属性上报；6.一次性事件上报
//trackName:事件名称，当eventType=0或eventType=6时必传，其他情况可不传
//infoDic :上报属性数据。当eventType=0或eventType=6时，infoDic可不传；其他情况必传，字典项
-(void)submitTAInfo:(int)eventType trackName:(NSString *)trackName info:(NSDictionary *)infoDic
4.6 激励视频load广告回调
//激励视频load广告回调
//state:success 广告拉取成功 fail 广告拉取失败
//placementId:广告位ID
-(void)OnLoadAdBack:(NSDictionary *)info{
NSLog(@"激励视频初始化返回 %@",info);
}
4.7 激励视频成功回调
//state:success:视频观看成功，fail：视频观看失败，open：视频打开，end：视频结束，star：视频开始，close:视频关闭，click：视频点击
//若视频观看成功返回奖励金额：rewardAmount
//若视频观看成功返回奖励名称：rewardName
//若视频观看失败返回错误码和错误信息：error、msg
-(void)OnRewardedVideoBack:(NSDictionary *)videoInfo{
NSLog(@"激励视频返回 %@",videoInfo);
}
4.8 账号绑定回调
//param(NSDictionary类型)中的参数如下：
//userID:U8Server生成的唯一用户ID
//sdkUserID:渠道SDK平台用户唯一ID，游戏服务器需要将游戏账户ID和该sdkUserID进行绑定。
//username:U8Server生成的用户名，比如234234234.uc,4353453453.baidu,65756756756.360
//sdkUserName:渠道SDK平台用户名，可能为空，部分渠道SDK没有返回用户名
//token:U8Server生成的会话ID，游戏服务器拿该字段去U8Server做二次登录验证
//extension:U8Server返回的扩展字段，部分渠道SDK需要，游戏中无需使用该字段的值
//timestamp:U8Server生成的时间戳，游戏服务器去U8Server做二次登录验证时，传给U8Server
//third_login_type 第三方登陆类型 0:游客 1:Google,2:facebook,3:apple,4:weixin,5:qq,6:jiguang
-(void)OnBindAccountBack:(NSDictionary *)accountInfo{
NSLog(@"绑定账号 %@",accountInfo);
}
4.8 切换账号回调
//param(NSDictionary类型)中的参数如下：
//userID:U8Server生成的唯一用户ID
//sdkUserID:渠道SDK平台用户唯一ID，游戏服务器需要将游戏账户ID和该sdkUserID进行绑定。
//username:U8Server生成的用户名，比如234234234.uc,4353453453.baidu,65756756756.360
//sdkUserName:渠道SDK平台用户名，可能为空，部分渠道SDK没有返回用户名
//token:U8Server生成的会话ID，游戏服务器拿该字段去U8Server做二次登录验证
//extension:U8Server返回的扩展字段，部分渠道SDK需要，游戏中无需使用该字段的值
//timestamp:U8Server生成的时间戳，游戏服务器去U8Server做二次登录验证时，传给U8Server
//third_login_type 第三方登陆类型 0:游客 1:Google,2:facebook,3:apple,4:weixin,5:qq,6:jiguang
-(void)OnSwitchAccountBack:(NSDictionary *)accoutInfo{
NSLog(@"切换账号 %@",accoutInfo);
}
4.9 SDK自带实名认证弹窗 实名成功回调
-(void) OnRealNameRegister:(NSDictionary *)params
{
NSLog(@"%@", params);
}
4.10 订阅恢复客户端回调
//state:回调状态，0：成功，1：失败
//restoreArray：成功时返回需要恢复订阅的商品id
-(void) OnRestoreCallback:(NSInteger)state restoreArray:(NSMutableArray *)restoreArray{
NSLog(@"demo点击订阅恢复返回");
}
4.11 获取商品回调
//productArray(NSMutableArray类型)（包含NSDictionary数据的数组）：
//NSDictionary中的参数如下：
//product_id：商品id
//price：价格
//symbol：货币符号
//title：标题
-(void) OnProductsInfoBack:(NSMutableArray*)productArray
{
NSLog(@"%@", productArray);//
}
返回值举例：
[
{
price = 198;
"product_id" = "com.mco.game.ppx.m198";
symbol = "\U00a5";
title = "1980\U94bb\U77f3";
},
{
price = 30;
"product_id" = "com.mco.game.ppx.m30";
symbol = "\U00a5";
title = "300\U94bb\U77f3";
}
]
4.12 可以进入游戏回调
当用户登陆返回isAdult为false时，必须结合此回调方法判断玩家是否可以进入游戏，若收到该回调表示可进入游戏。 当游戏自定义实名认证成功且为非成年人时，必须结合此回调方法判断玩家是否可以进入游戏，若收到该回调表示可进入游戏。
- (void)OnIntoGameBack{
NSLog(@"可以进入游戏");
}
4.13 分享结果回调
shareInfo值
| 参数名称 | 参数说明 |
|---|---|
| state | 0=成功；1=失败；2=取消；3=开始分享；4=分享参数不齐全 |
| platform | 0=新浪;1=微信聊天;2=微信朋友圈;4=QQ聊天页面;5=qq空间;37=抖音 |
| msg | 若state=0，返回成功；若state!=0，返回错误原因 |
-(void) OnShareInfoBack:(NSDictionary *)shareInfo{
NSLog("share back %@",shareInfo);
}