Integration/接口说明

1.开始前准备工作

1.1 软件版本

使用Xcode 15 目标iOS15.0或更高版本

1.2 SDK安装

获取运营提供的SDK安装包

在Target的General标签页选择Embedded Binaries下的加号➕ ->Add Other ->选择framework文件 点击导入

选择 Embed方式为Embed & Sign

在需要调用SDK接口的文件中 #import ：例如

OC:

#import <uluGameSDK/uluGameSDK.h>

swift:

import uluGameSDK

在Signing & Capabilities中增加Push Notifications和Sign in with Apple

1.3 出包注意事项

1、使用Xcode构建包时，Manage Version and Build Number不要勾选

1.4 info.plist配置

提示：部分重要的参数是sdk正常运行的基础，请提前配置

URL Types中部分配置字段:

facebook：
identifier：使用com.ulugame.xxxxx.facebook，xxxxx替换成游戏名的英文简拼
URL Schemes：格式为fb+FacebookAppID（示例：fb1591466175xxxxxxx）

google：
identifier：使用com.ulugame.xxxxx.google，xxxxx替换成游戏名的英文简拼
URL Schemes：使用GoogleService-Info.plist文件中REVERSED_CLIENT_ID字段的值

注意事项：

1、运营人员提供的谷歌 GoogleService-Info.plist文件需要导入到项目的根目录下
2、uluGameSDK.framework和uluEventSDK.framework必须导入，其他的sdk模块根据自己的业务和需求

2.初始化SDK（必选）

您需要在AppDelegate文件中的- (BOOL)application:(UIApplication )application didFinishLaunchingWithOptions:(NSDictionary )launchOptions方法中开始初始化

2.1 接口定义

+ (ULManager * _Nullable) initWithGameID:(NSString *)gameID gameVersion:(NSString *)version

2.2 示例代码

#import <uluGameSDK/uluGameSDK.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    //调用启动逻辑
    [ULManager initWithGameID:@"" gameVersion:@"1.0.0"];
    BOOL success = [[ULManager shared] application:application didFinishLaunchingWithOptions:launchOptions];
    BOOL other = ... (其他程序启动参数)
    return success & other ;
}

调用SDK初始化

[ULManager shared].delegate = ...; // 设置回调监听对象
[ULManager initWithGameID:@"" gameVersion:@"1.0.0"];

3.添加生命周期接口（必选）

请在AppDelegate文件中的生命周期接口中调用ULUSDK所需的生命周期接口。

3.1 示例代码

@implementation AppDelegate

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    BOOL handled = [[ULManager shared] application:app openURL:url options:options];
    BOOL other = ... （其他程序逻辑）
    return handled | other ;
}

- (void)applicationDidBecomeActive:(UIApplication *)application {
    [[ULManager shared] applicationDidBecomeActive:application];
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler {
    return [[ULManager shared] application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation  {
    return [[ULManager shared] application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
}

通知注册方法

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [[ULManager shared] application:application didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

4.登录接口（必选）

调用这个接口进行登录操作（例如：在点击登录按钮时调用），如未登录会显示登录窗口，已有登录信息则会自动登录。

4.1 接口定义

- (void)loginInViewController:(UIViewController *)viewController;

4.2 示例代码

@implementation GameViewController

- (void)viewDidLoad {
    [ULManager shared].delegate = self;
}
- (void)touchButton {
    [[ULManager shared] loginInViewController:self];
}

5.登录成功回调（必选）

登录成功回调，返回user对象。设置ULManger的delegate属性来监听登录回调，这个方法返回表示登录成功

5.1 接口定义

- (void)loginDidSuccess:(ULGameUser * _Nullable)user;

5.2 示例代码

@implementation GameViewController

- (void)loginDidSuccess:(ULGameUser *)user {
    // 用户自定义逻辑
}

6.登录失败回调（必选）

登录失败回调，自动登录或者正常登录失败都会返回

6.1 接口定义

- (void)loginDidFail:(ULCode)code;

6.2 示例代码

@implementation GameViewController

- (void)loginDidFail:(ULCode)code {
    // 用户自定义逻辑
}

7.退出登录接口（必选）

用户在用户中心点击切换账号会触发登出逻辑，登出成功或失败时会通过对应方法通知代理对象。

7.1 接口定义

- (void)logoutDidSuccess;
- (void)logoutDidFail:(ULCode)code;

7.2 示例代码

@implementation GameViewController

// 登出成功回调
- (void)logoutDidSuccess {
    // 用户自定义逻辑
}
// 登出失败回调
- (void)logoutDidFail:(ULCode)code {
    // 用户自定义逻辑
}

8.支付接口（必选）

调用商品内购接口，回调方法会发送到初始化传入的delegate 对象上（例如：上面示例中的GameViewController），建议： 收到支付回调之后再发起下一次支付。

8.1 接口定义

- (void)payWithULUOrder:(ULUOrder *)order andRole:(ULURole *)roleInfo;

8.2 示例代码

@implementation GameViewController

//用户点击支付后
//配置角色信息
ULURole *role = [[ULURole alloc] init];
role.roleId = @"q123ios";
role.playername = @"ext";
role.serverid = @"westunion";
role.servername = @"name";
role.roleLevel = @"1300";
role.vipLevel = 5;

//配置订单信息
ULUOrder *order = [[ULUOrder alloc] init];
order.productid = @"ulu_xxxxx_100"; // ulu内购技术id，详见内购参数表
order.quantity = 1;
order.extraData = @"sank";
[[ULManager shared] payWithULUOrder:order andRole:role];

8.3 支付成功回调

- (void)payDidSuccess:(NSString *)orderId extraData:(NSString *)extraData{
    NSLog(@"订单支付成功");
}

8.4 支付失败回调

- (void)payDidFailwithOrderId:(NSString *)orderId code:(ULCode)code extraData:(NSString *)extraData {
    NSLog(@"订单支付失败，错误码：%ld", (long)code );
}

9.进入用户中心（必选）

需要在游戏内自行添加用户中心按钮并调用此接口。

9.1 接口定义

- (BOOL)openUserCenterfromViewController:(UIViewController *)viewController;

9.2 示例代码

@implementation GameViewController

[[ULManager shared] openUserCenterfromViewController:self];

10.客服中心接口（必选）

需要在游戏内自行添加客服中心按钮并调用此接口

10.1 接口定义

- (void)openCustomerServiceInViewController:(UIViewController *)viewController withRoleInfo:(ULURole *)roleInfo;

10.2 示例代码

@implementation GameViewController

ULURole *role = [[ULURole alloc] init];
role.roleId = @"q123ios";
role.playername = @"ext";
role.serverid = @"westunion";
role.servername = @"name";
role.roleLevel = @"1300";
role.vipLevel = 5;
[[ULManager shared] openCustomerServiceInViewController:self withRoleInfo:role];

11.埋点接口（必选）

请在游戏内需要的位置自行调用埋点接口 1、将uluEventSDK.framework拖入工程 2、在需要使用埋点接口的文件中引入文件

11.1 接口定义

埋点需要同时调用以下2个方法，2个方法的参数传相同即可

<!-- ULEventManager类中方法 -->
- (void)trackEvent:(NSString *)name withValues:(nullable NSDictionary *)values;

<!-- ULManager类中方法 -->
- (void)logEventWithNameByChannelType:(NSString *)eventName andValues:(NSDictionary * _Nullable)extraData channelType:(UL_Event_Channel)channelType;

11.2 示例代码

@implementation GameViewController

<!-- ULEventManager示例1 -->
[[ULEventManager shared] trackEvent: @"enterinstance" withValues:nil]; 
<!-- ULEventManager示例2 -->
[[ULEventManager shared] trackEvent: @"level_up" withValues: @{
    @"uid" :  @"12345678",
    @"role_id"  : @"22345678",
    @"role_name" : @"小明",
    @"server_id" : @"123",
    @"server_name"  : @"游陆提审服",
    @"level" : @(20)
}]

<!-- ULManager示例1 -->
[[ULManager shared] logEventWithNameByChannelType:@"level_up" andValues:nil channelType:UL_Event_Channel_FacebookAndFirebase];
<!-- ULManager示例2 -->
[[ULManager shared] logEventWithNameByChannelType:@"level_up" andValues:@@{
    @"uid" :  @"12345678",
    @"role_id"  : @"22345678",
    @"role_name" : @"小明",
    @"server_id" : @"123",
    @"server_name"  : @"游陆提审服",
    @"level" : @(20)
} channelType:UL_Event_Channel_FacebookAndFirebase];

12.礼包兑换功能（可选）

在游戏内需要礼包兑换的地方调用接口

12.1 接口定义

- (void)showGiftReceiveWithRole:(ULURole *)role;

12.2 示例代码

@implementation GameViewController

ULURole *role = [[ULURole alloc] init];
role.roleId = @"q123ios";
role.playername = @"ext";
role.serverid = @"westunion";
role.servername = @"name";
[[ULManager shared] showGiftReceiveWithRole:role];

13.问卷调查功能（可选）

接入问卷调查时必须同时接入服务端的发放礼包接口，否则问卷调查功能将不能使用

13.1 接口定义

- (void)openSurveyServiceInViewController:(nullable UIViewController *)viewController withRoleInfo:(ULURole *)roleInfo;

13.2 示例代码

@implementation GameViewController

ULURole *role = [[ULURole alloc] init];
role.roleId = @"q123ios";
role.playername = @"ext";
role.serverid = @"westunion";
role.servername = @"name";
[[ULManager shared] openSurveyServiceInViewController:self withRoleInfo:role];

14.分享（可选）

在用户点击分享 ，并选择图片后，创建ULShareContent对象，图片并设置图片和文字。

类ULShareContent

方法： 打开分享卡片

- (void)openShareDialogwithCallback:(void (^)(ULShareStatus status,NSError *_Nullable error))shareCallback;

示例：

ULShareContent *content = [[ULShareContent alloc] initWithTag:@"share001"];
content.image = [[UIImage alloc] initWithContentsOfFile:self.image.contentURL.path];
content.text = @"hahahahah";
[content openShareDialogwithCallback:^(ULShareStatus status, NSError * _Nullable error) {
    NSLog(@"status %ld", (long)status);
}];

回调中检查 status 字段获取分享状态。

ULShareStatus 类型:

15.评分功能（可选）

通过此方法可以直接调用系统评分接口，引导玩家进行游戏评分

15.1 接口定义

+ (void)requestReview:(NSString *)storeID;

15.2 示例代码

@implementation GameViewController

- (void)userTapReview {
    [ULManager requestReview:@"1554607991"];
}

16.激励广告功能（可选）

激励广告模块集成了Admob渠道和Topon渠道，根据运营要求，选择一种渠道进行参数配置

16.1 配置参数

1、Admob 渠道 在游戏的 Info.plist 文件中加入 GADApplicationIdentifier 字段，填入Admob app ID

2、Topon 渠道 在游戏的Info.plist文件中加入以下字段

3、在info.plist中添加SKAdNetworkItems

<key>SKAdNetworkItems</key>
    <array>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>cstr6suwn9.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>22mmun2rn5.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>uw77j35x4d.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>7ug5zh24hu.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>9t245vhmpl.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>kbd757ywx3.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>a8cz6cu7e5.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>578prtvx9j.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>5tjdwbrq8w.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>hs6bdukanm.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>k674qkevps.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>dbu4b84rxf.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>v9wttpbfk9.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>n38lu8286q.skadnetwork</string>
        </dict>
        <dict>
           <key>SKAdNetworkIdentifier</key>
           <string>4dzt52r2t5.skadnetwork</string>
        </dict>
        <dict>
           <key>SKAdNetworkIdentifier</key>
           <string>su67r6k2v3.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>gta9lk7p23.skadnetwork</string>
        </dict>
</array>

16.2 代码示例

工程引入uluLTV.framework，在用到的文件中导入uluLTV（@import uluLTV）

1、初始化及设置回调对象

@import uluLTV;

@interface GameViewController () <ULADRewardedAdDelegate>
@property (strong, nonatomic) ULADRewardedAd *rewardedAd;
@end

@implementation GameViewController
- (void)viewDidLoad {
    self.rewardedAd = [[ULADRewardedAd alloc] init:@"1002922xxxx"];
    self.rewardedAd.delegate = self;
    [self.rewardedAd loadNextAd];
}
@end

2、启动广告

@import uluLTV;

@interface GameViewController () <ULADRewardedAdDelegate>
@property (strong, nonatomic) ULADRewardedAd *rewardedAd;
@end

@implementation GameViewController
<!-- 点击观看广告按钮，调用此方法 -->
- (void)loadUluAd {
    if (self.rewardedAd) {
        if ([self.rewardedAd isReady]) {
            [self.rewardedAd presentFromRootViewController:self];
        }
        } else {
            [self.rewardedAd presentFromRootViewController:self];
        }
}
@end

3、接收广告回调

- (void)rewardedAdDidLoadFail:(ULADRewardedAd *)rewardedAd withError:(NSError *)error {
    <!-- 可以通过error.userInfo[NSUnderlyingErrorKey] 获取渠道方错误代码 -->
   NSLog(@"rewardedAd load error");
}

- (void)rewardedAdDidLoadSuccess:(ULADRewardedAd *)rewardedAd {
   NSLog(@"rewardedAd load success");
}

- (void)rewardedAd:(nonnull ULADRewardedAd *)rewardedAd didFailToPresentWithError:(nonnull NSError *)error {
    NSLog(@"rewardedAd:didFailToPresentWithError");
}

<!-- 根据运营需求，在收到此回调时，内部调用logAdRevenue，传递对应参数-->
- (void)rewardedAd:(ULADRewardedAd *)rewardedAd userDidEarnReward:(ULAdReward *)reward  monetizationNetwork:(NSString *)monetizationNetwork mediationNetwork:(NSInteger)mediationNetwork revenueCurrency:(NSString *)revenueCurrency eventRevenue:(NSNumber *)eventRevenue additionalParameters:(nullable NSDictionary *)additionalParameters {
    NSLog(@"rewardedAd:userDidEarnReward:");

    [[ULEventManager shared] logAdRevenue: ……]; 
}

- (void)rewardedAdDidDismiss:(nonnull ULADRewardedAd *)rewardedAd {
    NSLog(@"rewardedAdDidDismiss:");
}
- (void)rewardedAdDidPresent:(nonnull ULADRewardedAd *)rewardedAd {
    NSLog(@"rewardedAdDidPresent:");
}

4、错误码

在有error 参数的回调方法中， error.code 代表了错误码 具体数值如下：

typedef NS_ENUM(NSUInteger, ULADRewardedAdError) {
    ULADRewardedAdErrorNotReady = 1,
    ULADRewardedAdErrorFailToDisplay = 2,
    ULADRewardedAdErrorNoChannelOpen = 3,
    ULADRewardedAdErrorNotInitialized = 4,
    ULADRewardedAdErrorFailToLoad = 5
};