# 1 功能介绍

本文将介绍如何快速实现登陆、数据上报与支付,让开发者简单了解一个完整的接入。

完成本文必接功能,你可以实现:

  • 初始化
  • 闪屏上报
  • 协议
  • 回调方法
  • 登录
  • 角色上报
  • 退出登录
  • 支付

# 2 前置条件

在开始接入前你需要确保以下条件已完成:

  • 保证快速接入的第一步已完成

  • 首先明确自己接入的是什么版本的SDK,以下的接入代码都是最新版本的接入指导,请保证当前获取的SDK为最新版本

  • 联系接入方游戏运营在ultraSDK管理后台 (opens new window)中获取初始化所必须的参数,详见各章节

# 3 接口接入时序图

uml diagram

# 4 接入步骤

接入步骤可以参考 3 时序图

# 4.1 初始化

操作步骤

第一步: 获取初始化接口参数

第二步:配置参数

  • 获取到参数后,将对应的参数在调用示例中进行更改

调用方法

- initWithProject:(UltraProject *) project
1

调用示例

初始化需要设置项目参数。

说明

此方法必须要在项目delegate文件的 -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions方法中调用


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	
    UltraProject *project = [[UltraProject alloc] init];
    // 12345678 为示例
    project.ultraProductId = @"12345678";
    // 12345678 为示例
    project.ultraProductKey = @"12345678";
    project.application = application;
    project.launchOptions = launchOptions;
    // 新增屏幕支持方向,默认是 UIInterfaceOrientationMaskAll,可以根据实际需求设置,这里设置成只支持横屏
    project.supportedInterfaceOrientations = UIInterfaceOrientationMaskLandscape;
    [[UltraPlatform sharedInstance] initWithProject:project];

    return YES;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

参数说明

  • UltraProject类字段说明
参数 含义 原类型 默认值 是否必须
ultraProductKey UltraSDK appKey NSString -
ultraProductId UltraSDK 产品ID NSString -
application - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions方法中的application UIApplication -
launchOptions - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions方法中的launchOptions方法中的application NSDictionaryring -
supportedInterfaceOrientations 屏幕方向
竖屏:UIInterfaceOrientationMaskPortrait
横屏,home键在左方:UIInterfaceOrientationMaskLandscapeLeft
横屏,home键在右方:UIInterfaceOrientationMaskLandscapeRight
横屏,2个方向:UIInterfaceOrientationMaskLandscape
所有方向:UIInterfaceOrientationMaskAll
UIInterfaceOrientationMask UIInterfaceOrientationMaskAll

# 4.2 闪屏上报

场景介绍

由于需要统计闪屏结束后的用户留存,在闪屏结束后需要上报状态,将调用示例中代码复制到闪屏结束后即可

调用方法

- (void)postSplashScreenEndSuccess:(void (^)(id obj))success
                             faild:(void (^)(id obj))faild;
1
2

调用示例

[[UltraPlatform sharedInstance] postSplashScreenEndSuccess:^(id obj) {
    //上报成功,游戏可不做处理
} faild:^(id obj) {
    
}];
1
2
3
4
5

# 4.3 弹窗协议接入

协议弹窗用于国家对隐私政策的要求,必须要同意相关协议,才能获取用户隐私,否则可能导致应用审核不过,或者被下架

  • 若游戏方用自己的弹窗协议,直接跳至4.3.3 点击同意通知

  • 若游戏方使用UltraSDK的弹窗协议,则必须接入4.3.2 同意协议通知

# 4.3.1 获取协议内容

场景介绍

用于在游戏主界面或者设置界面,需要使用UltraSDK协议内容的场景

用户在中台配置了对应渠道的协议和权限内容,可通过此方法获取到配置的协议和权限JSON串,包含协议url、名称和权限说明等

中台配置协议与权限的位置

中台协议与权限配置地址 (opens new window)

操作步骤

第一步: 获取UltraSDK协议内容,根据UltraSDK后台的配置,可能返回多个协议(具体字段说明详见下表),每个协议包括协议名称及协议url

第二步:将调用示例代码复制到使用的地方即可

调用方法

- (NSDictionary *)getProtocolResult;
1

调用示例

NSDictionary* resultDic = [[UltraPlatform sharedInstance] getProtocolResult];
1

返回示例

{
	"userAgrName": "Ultra用户协议",
	"sdkAgrUrl": "",
	"swPermission": "1",
	"sdkAgrName": "腾讯QQ协议",
	"priAgrName": "Ultra隐私",
	"childAgrName": "Ultra儿童个人信息保护政策",
	"swStatus": "1",
	"childAgrUrl": "",
	"version": "1.0",
	"permissions": [{
		"des": "用于接收验证码、推送等功能",
		"name": "短信",
		"icon": "",
		"id": 1
	}, {
		"des": "游戏内上传图片",
		"name": "相册",
		"icon": "",
		"id": 16
	}],
	"userAgrUrl": "",
	"priAgrUrl": "",
	"ptitle": "为了保证您游戏体验,我们将在游戏服务的过程中,申请并调用部分以下权限。您可以在弹出权限调用时,选择同意或者拒绝开启相关权限。若是拒绝则会影响部分功能,但同时您可在手机设置中随时再次调用相关权限。权限可能包括:"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

协议返回值字段说明

  • 如果没有协议,返回nil
字段 类型 说明 备注
priAgrName String 隐私协议名称 例:Ultra隐私协议
priAgrUrl String 隐私协议地址 例:https://www.ultrasdk.com/p/per_adu.html
userAgrName String 用户协议名称 例:Ultra用户协议
userAgrUrl String 用户协议地址
childAgrName String 儿童信息保护政策 例:Ultra儿童个人信息保护政策
childAgrUrl String 儿童信息保护政策地址
sdkAgrName String 三方SDK协议 例:小米XXX协议
sdkAgrUrl String 三方SDK协议地址
version String 当前协议的版本 当协议版本与之前获取到的协议版本不一致时,建议重新提示用户协议更改
permissions-des String 当前权限的描述 例:游戏内上传图片
permissions-name String 当前权限的名称 例:相册
permissions-icon String 当前权限的图标地址
permissions-id int 当前权限的id排序 可忽略排序

# 4.3.2 同意协议通知

场景介绍

此接口仅用于游戏使用UltraSDK的协议弹出框,用于监听协议弹出框用户是否点击了同意。

  • 备注:游戏未收到用户同意协议的回调前,自身及接入的其他三方SDK都不能产生任何获取隐式数据行为,如不能调用init,login等接口,该要求为国家合规性要求,请务必严格遵守!

注册通知

  [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(clickProtocol)
                                                 name:GAME_PUBLIC_NOTIFICATION_NAME_PROTOCOL
                                               object:nil];
1
2
3
4

通知回调方法

- (void)clickProtocol{
    //这里处理同意协议后的逻辑
}
1
2
3

# 4.3.3 点击同意通知

场景介绍

  • 此接口仅用于游戏使用自己的协议弹出框,而不使用UltraSDK的。在用户点击同意后,游戏需要调用此接口通知UltraSDK,以便UltraSDK继续走登录流程。

  • 需要游戏自己绘制协议界面

调用方法

- (void)setAgreeProtocol;
1

调用示例

[[UltraPlatform sharedInstance] setAgreeProtocol];
1

# 4.4 设置回调

设置回调部分用于监听各种场景事件,比如第三方登录回调,必须接入

# 4.4.1 添加OpenUrl响应代码

场景介绍

该步骤用于监听第三方回调事件

  • 注意:由于在程序内部可能会调用第三方应用, 此时需要处理OpenUrl,必须实现以下四个回调方法,因为要适配iOS多个版本系统

接入步骤

复制下面代码到UnityAppController控制器中

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
	[[UltraPlatform sharedInstance] ultra_application:application handleOpenURL:url] ;
	return YES;
}

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
	[[UltraPlatform sharedInstance] ultra_application:application handleOpenURL:url] ;
	return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
	[[UltraPlatform sharedInstance] ultra_application:app handleOpenURL:url] ;
	return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray<id<UIUserActivityRestoring>> * __nullable restorableObjects))restorationHandler
{
    [[UltraPlatform sharedInstance] handleOpenUniversalLink:userActivity];
    return YES ;
}

- (void)applicationDidBecomeActive:(UIApplication *)application{
    [[UltraPlatform sharedInstance] applicationDidBecomeActive:application];
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 4.4.2 监听登录事件

功能介绍

监听登录事件,游戏方可以知道SDK的登录状态,然后做一些登录后的操作

操作步骤

开发者通过调用提供的接口, 监听GAME_PUBLIC_NOTIFICATION_NAME_LOGIN, 来监听登录事件,直接复制调用示例通知回调中的代码使用即可

调用示例

//监听用户登陆成功的通知 单机版游戏不用监听
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(loginNotification:) name:GAME_PUBLIC_NOTIFICATION_NAME_LOGIN object:nil];
1
2

通知回调

-(void)loginNotification:(NSNotification*)notification
{
	BOOL isLoginSuccess = [notification.object[GAME_PUBLIC_TAG_LOGIN_IS_SUCCESS] boolValue];
    if (isLoginSuccess) {
        NSString * accessCode = notification.object[GAME_PUBLIC_TAG_ACCESS_CODE];
        NSString * accessToken = notification.object[GAME_PUBLIC_TAG_ULTRA_ACCESS_TOKEN];//在Ultra后台取用户信息
        NSLog(@"用户登陆成功!");
        NSLog(@"==> AccessCode: %@", accessCode);
        NSLog(@"==> AccessToken: %@", accessToken);
        NSLog(@"==> sdkuserid: %@", [[UltraPlatform sharedInstance] getUserId]);
        NSLog(@"==> username: %@", [[UltraPlatform sharedInstance] getUserName]);
    }
    else
    {
        NSLog(@"用户登陆失败!");
        int errorCode = [notification.object[GAME_PUBLIC_TAG_LOGIN_ERROR_CODE] intValue];
        if (errorCode == GAME_PUBLIC_CODE_LOGIN_ERROR_USER_NOT_EXIST)
        {
            NSLog(@"用户不存在");
        }
        else if (errorCode == GAME_PUBLIC_CODE_LOGIN_ERROR_WRONG_PASSWORD)
        {
            NSLog(@"密码错误");
        }
        else
        {
            NSLog(@"未知Login 错误 code");
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

返回参数说明

字段 类型 说明
ultraSdkUserId NSString 用户ID
channel NSString 渠道名称
channelId int 渠道ID
cUid NSString sdkID
cName NSString 用户名
login_is_success BOOL 是否登录成功
firstLgn int 是否是第一次登录,1代表首次登录

# 4.4.3 监听点击切换账号

场景介绍

可以监听SDK切换账号逻辑,常用于SDK切换账号时,游戏方可以退出到主登录界面

操作步骤

直接复制调用示例通知回调中的代码使用即可

调用示例

//监听点击切换账号
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(changeAccountNotification:) name:GAME_PUBLIC_NOTIFICATION_NAME_CHANGE_ACCOUNT object:nil];
1
2

通知回调

- (void)changeAccountNotification:(NSNotification*)notification{
    NSLog(@"切换账号成功");
}
1
2
3

# 4.4.4 CP踢出玩家下线通知

场景介绍

根据国家政策必须接入此代码,收到通知后,游戏方必须调用cpKickOffCallBackWithResult接口上报给SDK,并且游戏界面需要回到登录界面

操作步骤

直接复制调用示例通知回调中的代码使用即可 注:这里登录失效和踢下线通知在一个回调中处理,详细见示例

调用示例

 // 登录失效通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(loginFaildNotification:) name:GAME_PUBLIC_NOTIFICATION_NAME_LOGONINVALID object:nil];
1
2

通知回调:


- (void)loginFaildNotification:(NSNotification *)noti
{
    //获取踢下线的理由
	NSString *message = noti.userInfo[GAME_PUBLIC_CP_KICKOFF_REASON];
    // 有message则为踢下线的通知
    if (message.length > 0) {
    	//如果消息内容不为空,则需要CP制作弹框显示
       NSMutableDictionary *params = [[NSMutableDictionary alloc] init];
       //上报踢玩家下线结果,0-失败、1-成功
       params[GAME_PUBLIC_CP_KICKOFF_RESULT] = @"1" ;
       //必须上报给SDK,且直到CP上报成功过后,SDK才会停止消息通知,
       [[UltraPlatform sharedInstance] cpKickOffCallBackWithResult:params]; 
       
       //CP上报后,需要回退到未登录账号的页面
       UnitySendMessage(xxxx)
    } else {
    	// 没有message,为登录失效,账号在不同设备上同时登录或者token失效(正常token有2天有效期),会发生登录失效的情况,需要回退到未登录账号的页面
    	
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 4.4.5 IAP内购状态监听

场景介绍

监听内购事件,用于接收支付成功或者失败的消息

调用接口

开发者可通过提供的接口, GAME_PUBLIC_NOTIFICATION_NAME_IAPPURCHASE_FINISH, 来监听平台支付事件。

操作步骤

直接复制调用示例通知回调中的代码使用即可

调用示例

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(iapPaymentFinished:) name:GAME_PUBLIC_NOTIFICATION_NAME_IAPPURCHASE_FINISH object:nil];
1

通知回调

-(void)iapPaymentFinished:(NSNotification*)notification
{
    BOOL isIapPurchaseSucess = [notification.object[GAME_PUBLIC_TAG_IAPPURCHASE_IS_SUCCESS] boolValue];
    UltraPaymentOrder * paymentOrder = notification.object[GAME_PUBLIC_TAG_PAYMENT_ORDER];
    if (isIapPurchaseSucess) {
        NSLog(@"iap购买成功");
        NSLog(@"===> 支付成功订单:");
        NSLog(@"===> iap订单id: %@", paymentOrder.orderId);
    } else {
        NSLog(@"iap购买失败");
        if(paymentOrder != nil){
	        NSLog(@"===> 支付失败订单:");
   		    NSLog(@"===> iap订单id: %@", paymentOrder.orderId);
            NSLog(@"===> iap订单errorCode: %ld", (long)paymentOrder.errorCode);
	        NSLog(@"===> iap订单errorDescription: %@", paymentOrder.errorDescription);
        }
        
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

说明

isIapPurchaseSucessYES时,证明付款成功了,但是并不代表道具发送成功,道具发送状态以cp服务器通知为准

isIapPurchaseSucessNO时,可能是付款失败,或者下单失败等原因。

# 4.5 登陆

场景介绍

用于游戏方调起登录界面,给玩家提供登录操作,如果调用成功会弹出登录界面

调用方法

- (void)enterLoginView;
1

调用示例

 [[UltraPlatform sharedInstance] enterLoginView];
1

单机游戏则调用以下方法:

[[UltraPlatform sharedInstance] enterAloneGame];
1

# 4.6 角色上报

说明

基础数据设置,在上报数据前,必须先初始化初始数据,数据必须真实有效

场景介绍

角色上报接口用于统计游戏方的角色等信息,主要是方便UltraSDK根据角色查询业务异常,必须在完成登录后方可调用

参数说明

UltraHDCBaseGameRoleInfo类字段说明

字段 类型 说明
channelUserId String 渠道用户ID(玩家登录账号) (必传)
gameUserId String 游戏生成的账号ID (必传)
serverId String 区服ID (必传)
serverName String 区服名称 (必传)
roleId String 角色ID (必传)
roleName String 角色名 (必传)
roleAvatar String 头像 (选传)

# 4.6.1 设置角色基础信息

此接口为角色上报基础接口,必须接入此接口才能执行下一步

调用示例

UltraHDCBaseGameRoleInfo *base = [UltraHDCBaseGameRoleInfo sharedInstance];
base.channelUserId = @""; //渠道用户ID(玩家登录账号)
base.gameUserId = @""; //游戏生成的账号ID
base.serverId = @"";//区服ID
base.serverName = @"";//区服名称
base.roleId = @"";//角色ID
base.roleName = @"";//角色名
base.roleAvatar = @"";//角色头像(有则传,无则不传)
//(设置这个很重要)
[[UltraPlatform sharedInstance] setBaseRoleInfoWithData:base];
   
1
2
3
4
5
6
7
8
9
10
11

# 4.6.2 角色登录

场景介绍

用于角色登录时,调用此接口,上报前需要先调用角色上报基础接口,具体参数的值必须真实有效

参数说明

  • UltraHDCGameRoleInfo类字段说明(必传字段)
字段 类型 说明
level String 角色等级 选传
vipLevel String VIP等) 选传
gold1 String 当前一级货币数量(充值获得)) 选传
gold2 String 当前二级货币数量(游戏内产出)) 选传
sumPay String 累计充值金额 选传

调用示例

UltraHDCGameRoleInfo *roleInfo = [[UltraHDCGameRoleInfo alloc] init];
roleInfo.level = @""; //角色等级
roleInfo.vipLevel = @""; //VIP等级
roleInfo.gold1 = @"";//当前一级货币数量(充值获得)
roleInfo.gold2 = @"";//当前二级货币数量(游戏内产出)
roleInfo.sumPay = @"";//累计充值金额
[[UltraPlatform sharedInstance] roleLoginWithGameRoleInfo:roleInfo];

1
2
3
4
5
6
7
8

# 4.6.3 角色注册

场景介绍

用于角色注册时,调用此接口,上报前需要先调用角色上报基础接口,具体参数的值必须真实有效

调用示例

UltraHDCGameRoleInfo *roleInfo = [[UltraHDCGameRoleInfo alloc] init];
roleInfo.level = @""; //角色等级
roleInfo.vipLevel = @""; //VIP等级
roleInfo.gold1 = @"";//当前一级货币数量(充值获得)
roleInfo.gold2 = @"";//当前二级货币数量(游戏内产出)
roleInfo.sumPay = @"";
[[UltraPlatform sharedInstance] roleRegisterWithGameRoleInfo:roleInfo]

1
2
3
4
5
6
7
8

# 4.6.4 角色升级

场景介绍

用于角色升级时,调用此接口,上报前需要先调用角色上报基础接口,具体参数的值必须真实有效

调用示例

UltraHDCGameRoleInfo *roleInfo = [[UltraHDCGameRoleInfo alloc] init];
roleInfo.level = @""; //角色等级
roleInfo.vipLevel = @""; //VIP等级
roleInfo.gold1 = @"";//当前一级货币数量(充值获得)
roleInfo.gold2 = @"";//当前二级货币数量(游戏内产出)
roleInfo.sumPay = @"";
[[UltraPlatform sharedInstance] roleLevelUpWithGameRoleInfo:roleInfo]

1
2
3
4
5
6
7
8

# 4.7 退出登录

场景介绍

适用于游戏退出登录时,清空SDK的登录信息

说明:退出登录有2个接口,开发者可以根据实际情况选择接入

  • 直接退出登陆:直接退出登录不做任何操作,会清除登录token等信息,不会回到登录界面
  • 退出登陆到历史登陆界面:退出登陆后将会回到历史登陆界面

# ** 直接退出登录 **

  • 调用方法
/**
 @brief  注销、退出登陆
 */
- (void)logout;
1
2
3
4
  • 调用示例
 [[UltraPlatform sharedInstance] logout];
1

# ** 退出登录到历史登录界面 **

  • 调用方法
/**
 @brief  注销、退出登陆
 */
- (void)logoutAndSowLoginView;
1
2
3
4
  • 调用示例
 [[UltraPlatform sharedInstance] logoutAndSowLoginView];
1

# 4.8 支付

# 4.8.1 内购时序图

以下是整个内购流程时序图,可供开发者理解整个购买流程

uml diagram

# 4.8.2 购买流程介绍

以下是对购买流程的详细介绍内容,可供开发者理解参数传递

流程说明

第一步:

购买时,开发者传入对应的参数gamePropIDgamePropID由Ultra提供。)、游戏所给道具ID(道具id例如是“1”)、gameRole(角色名:例如gameRole)和cpOrder(cp订单号(保证唯一)

第二步:

SDK服务器获取一一对应配置在苹果服务器的道具ID(例如获取到的是com.ultra.sdk.energy);

第三步:

完成前两步后,即可发起购买。

说明

在沙盒测试环境下,真机模拟内购。所用的Bundle ID必须和iTunes Connect中的Bundle ID一致才行。

选择使用沙盒用户登录或者处于注销状态,但是一定注意不能使用真实用户登录,否则购买测试不会成功。

# 4.8.3 IAP发起购买

场景介绍

该步骤调用后,即可拉起苹果支付,请保证在开始前在UltraSDK管理后台 (opens new window)中已完成游戏商品配置

调用方法

- (int)iapPurchaseWithData:(GamePaymentParameters *)paymentParametersData;
1

调用示例

//配置测试参数值:
GamePaymentParameters *parameterData = [[GamePaymentParameters alloc] init];
parameterData.gamePropID = @"1000" ;
parameterData.gameRole = @"gameRole" ;
parameterData.cpOrder =  @"传入CP订单号(没有则传一个能保证唯一的,不要传时间戳,可能多个用户同时购买)" ;
parameterData.callbackUrl = @"xxxxxxx";//内购回调地址,可由运营后台配置,如果后台配置了,此参数无效(固定回调可不设置,需要同时满足多个回调地址可使用)
[[UltraPlatform sharedInstance] iapPurchaseWithData:parameterData];
1
2
3
4
5
6
7

参数说明

  • GamePaymentParameters类字段说明
字段 类型 说明
gamePropID String 游戏传过来的产品ID
gameRole String 透传参数
cpOrder String CP订单号
callbackUrl String 内购回调地址,两种配置方式:1、可由运营在后台-游戏管理中进行配置,若运营在后台进行了配置则此参数无效;2、可由开发者在代码中写入

# 5 测试指南

# 如何验证登入功能接入成功?

登陆接入是否的验证,只需要开发者在代码中检查在用户登陆后是否有登陆回调,若有,即表示该功能接入成功

# 如何验证支付功能接入成功?

支付成功的验证,只需要点击商品购买后,确保界面拉起ios支付验证界面即表示该功能接入成功。

# 恭喜你完成SDK集成,让我们开始《第三步:使用工具打包》吧~

本文档对解决你的问题有所帮助?