跳到主要内容

v3

API​

所有的 API 使用都需要引入头文件 #import <OmniAPI/OmniAPI-Swift.h>

警告

v3.2.0 以上版本还需要引入头文件 #import <OmniCore/OmniCore-Swift.h>

1. 初始化​

提示
  • SDK 初始化 API, 必须首先调用
  • App 生命周期内只需要调用一次
  • SDK 所有接口都必须在初始化成功后才能调用
OmniSDKOptions *options = [[OmniSDKOptions alloc] init];
options.delegate = self; // self 需要实现 OmniSDKDelegate 协议
[[OmniSDKv3 shared] startWithOptions:options];
API 回调结果监听 
- (void)onStartWithResult:(OmniSDKStartResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

参数​

OmniSDKOptions​
参数是否必填类型说明
delegateYOmniSDKDelegate实现 OmniSDKDelegate 协议方法，监听 SDK 回调

返回值​

OmniSDKStartResult​
参数类型说明
appIdstringOmniSDK AppId
planIdstringOmniSDK 发布计划
sdkVersionstringOmniSDK 版本号

2. 登录​

提示
  • 推荐在游戏内点击登录时调用 (SDK 必须初始化成功)
[[OmniSDKv3 shared] loginWithController:self options:nil];
API 回调结果监听

回调监听​

- (void)onLoginWithResult:(OmniSDKLoginResult *)result error:(OmniSDKError *)error  {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

参数​

参数是否必填类型说明
controllerYUIViewController
optionsNOmniSDKLoginOptions登录参数, 传 nil 则使用默认的 SDK 登录界面
OmniSDKLoginOptions​
参数是否必填类型说明
authMethodYOmniSDKAuthMethod登录类型

返回值​

OmniSDKLoginResult​
参数类型说明
loginInfoOmniSDKLoginInfo登录信息

3. 获取用户信息​

提示
  • 用户登录成功后，可获取登录信息 (如 userId 等等)
  • 登录失败时，此方法将返回 nil
  • 由于不同的分发渠道或平台，OmniSDKLoginInfo 中的某些字段可能会返回空值

接口调用​

OmniSDKLoginInfo *info = [[OmniSDKv3 shared] getLoginInfo];

返回值​

OmniSDKLoginInfo

4. 登出​

提示
  • 当收到退出成功回调后, 游戏需要退出到游戏登录界面
  • 登出后，getLoginInfo 将会返回 nil 需要重新 login
[[OmniSDKv3 shared] logout];
API 回调结果监听 
- (void)onLogoutWithResult:(OmniSDKLogoutResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

返回值​

OmniSDKLogoutResult​
参数类型说明
userIdString用户 id

5. 打开账号中心​

修改密码, 绑定手机, 切换账号...

接口调用​

[[OmniSDKv3 shared] openAccountCenterWithController:self];

参数​

参数是否必填类型说明
controllerYUIViewController
提示
  • 当用户以游客身份登录应用时，可能需要进行更安全或持久的身份验证方式，如绑定第三方账号（例如Facebook，AppleId等）。此时，可以调用此特定接口来触发对应的第三方账号授权页面。这将允许用户在安全的第三方环境中验证他们的身份，并将其与您的应用关联
  • 如果在调用此接口时，options 参数被设置为 nil ，则弹出SDK的关联账号页面。这是一个内建的页面，允许用户选择他们希望关联的账号类型。然后用户可以在此页面上选择第三方账号授权登录，进行身份验证和账号绑定

接口调用​

OmniSDKLinkAccountOptions *options = [[OmniSDKLinkAccountOptions alloc] initWithIdp:OmniSDKIdentityProviderApple];
[[OmniSDKv3 shared] linkAccountWithOptions:options];
API 回调结果监听 
- (void)onLinkAccountWithResult:(OmniSDKLinkAccountResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

参数​

参数是否必填类型说明
optionsNOmniSDKLinkAccountOptions关联账号参数, 传 nil 则拉起 SDK 绑定账号界面
OmniSDKLinkAccountOptions​
参数是否必填类型说明
idpYOmniSDKIdentityProvider关联账号类型

返回值​

OmniSDKLinkAccountResult​
参数类型说明
idpOmniSDKIdentityProvider关联账号类型

7. 注销账号​

提示

此接口目前无需传参, options 传 nil 即可

[[OmniSDKv3 shared] deleteAccountWithOptions:nil];
API 回调结果监听 
- (void)onDeleteAccountWithResult:(OmniSDKDeleteAccountResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

返回值​

OmniSDKDeleteAccountResult​
参数类型说明
userIdString用户 id

8. 恢复账号​

提示

此接口目前无需传参, options 传 nil 即可

[OmniSDKv3.shared restoreAccountWithOptions:nil];
API 回调结果监听 
- (void)onRestoreAccountWithResult:(OmniSDKRestoreAccountResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

返回值​

OmniSDKRestoreAccountResult​
参数类型说明
userIdString用户 id

9. 购买商品​

提示
OmniSDKPurchaseOptions *options = [[OmniSDKPurchaseOptions alloc] init];
options.productId = @"product01";
options.productName = @"魔石";
options.productDesc = "100 魔石";
options.productUnitPrice = 6;
options.purchaseAmount = 6;
options.purchaseQuantity = 1;
options.purchaseCallbackUrl = "http://callback.com";
options.gameCurrencyUnit = @"魔石";
options.gameOrderId = "7234895279837489";
options.gameRoleId = @"123";
options.gameRoleName = @"小王";
options.gameRoleLevel = @"99";
options.gameRoleVipLevel = @"v8";
options.gameZoneId = @"1区";
options.gameServerId = @"8服";
options.extJson = @"";

[[OmniSDKv3 shared] purchaseWithOptions:options];
API 回调结果监听 
- (void)onPurchaseWithResult:(OmniSDKPurchaseResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

参数​

OmniSDKPurchaseOptions

返回值​

OmniSDKPurchaseResult​
参数类型说明
orderIdStringOmniSDK 生成的订单号
purchaseInfoOmniSDKPurchaseOptions购买信息

10. 数据上报​

提示

上报游戏内的一些关键行为到 SDK

OmniSDKRoleInfo *role = [[OmniSDKRoleInfo alloc] init];
role.userId = @"123";
role.gameRoleId = @"11";
role.gameRoleName = @"小王";
role.gameRoleLevel = @"4";
role.gameRoleVipLevel = @"v8";
role.gameServerName = @"1服";
role.gameServerId = @"8区";
role.extJson = @"";

OmniSDKEnterGameEvent *event = [[OmniSDKEnterGameEvent alloc] init];
event.roleInfo = role;
[[OmniSDKv3 shared] trackEventWithEvent:event];

参数​

进入游戏事件​

OmniSDKEnterGameEvent

参数是否必填类型说明
roleInfoYOmniSDKRoleInfo游戏角色信息
创建角色事件​

OmniSDKCreateRoleEvent

参数是否必填类型说明
roleInfoYOmniSDKRoleInfo游戏角色信息
角色升级事件​

OmniSDKRoleLevelUpEvent

参数是否必填类型说明
roleInfoYOmniSDKRoleInfo游戏角色信息
购买商品事件​

OmniSDKPurchaseEvent

参数是否必填类型说明
purchaseYOmniSDKPurchaseOptions购买信息
orderIdYStringSDK 订单号
userIdYStringSDK 账号 id

11. 捕获异常(选接)​

捕获游戏内异常信息到 Sentry

OmniSDKCaptureMessage *message = [[OmniSDKCaptureMessage alloc] init];
message.payload = @"Test message for sentry capture.";
message.level = OmniSDKCaptureLevelError;
NSDictionary* extraData = @{
    @"StackTrace": @"Stack trace information.",
    @"Other": @"Other data."
};
message.extra = extraData;
[[OmniSDKv3 shared] captureWithMessage: message];

参数​

参数是否必填类型说明
messageYOmniSDKCaptureMessage异常信息内容

效果参考​

img

12. 社交分享(选接)​

分享游戏内信息到第三方平台

OmniSDKSocialShareOptions *options = [[OmniSDKSocialShareOptions alloc] init];
options.platform = platform;
options.linkUrl = [NSURL URLWithString:@"https://developers.facebook.com"];
options.text = @"test share";
options.imageUrl = [NSURL URLWithString:@"https://lmg.jj20.com/up/allimg/4k/s/02/2109250006343S5-0-lp.jpg"];
[OmniSDKv3.shared socialShareWithController:self options:options];
API 回调结果监听 
- (void)onSocialShareWithResult:(OmniSDKSocialShareResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        // 成功
    } else {
        // 失败
        NSLog(@"%@", error.message);
    }
}

参数​

参数是否必填类型说明
controllerYUIViewController
optionsYOmniSDKSocialShareOptions分享参数
OmniSDKSocialShareOptions​
参数是否必填类型说明
platformYOmniSDKSocialSharePlatform分享平台类型
textNString分享内容
imageUrlNNSUrl图片 url
linkUrlNNSUrl链接 url
quoteNString引用
tagsNString标签
OmniSDKSocialSharePlatform​

分享平台类型

类型说明
OmniSDKSocialShareOptionsSystem调用系统分享
OmniSDKSocialShareOptionsFacebook分享到 facebook
OmniSDKSocialShareOptionsLine分享到 line

返回值​

OmniSDKSocialShareResult​

参数类型说明
optionsOmniSDKSocialShareOptions分享参数

13. APP启动初始化(选接)​

程序启动时调用，在 App 生命周期函数 didFinishLaunchingWithOptions 内调用

备注：Unity 工程 didFinishLaunchingWithOptions 函数在 UnityAppController.mm 类中

[OmniSDKv3.shared application:application didFinishLaunchingWithOptions:launchOptions];

参数​

字段说明
application系统参数
launchOptions系统参数

14. APP 跳转(选接)​

提示
  • 程序跳转第三方 App 后返回游戏，在 App 生命周期函数 application 内调用

备注：Unity 工程 applicationOpenURLWithOptions 函数在 UnityAppController.mm 类中

[OmniSDK.shared application:app open:url options:options];

参数​

字段说明
app系统参数
url系统参数
options系统参数

15. 预加载广告(选接)​

SDK Version 3.3.0+

提示

此 API 需要添加 OmniTopOn 模块,集成方式详见 集成 SDK

  • 预加载只是提前加载广告,并不会显示广告,只有调用 showAd 接口才会显示广告
  • 建议在游戏加载场景的时候调用此接口

注意: 需要登录成功才能调用此接口

OmniSDKAdOptions *option = [[OmniSDKAdOptions alloc] init];
option.placementId = @"test_ios_RV_1";
[[OmniSDKv3 shared] preloadAdWithController:self options:option callback:^(OmniSDKPreloadAdResult * _Nullable result, OmniSDKError * _Nullable error) {
    if (error != nil) {
        // 失败
        NSInteger code = error.code; // 错误码
        NSString *message = error.message; // 错误信息
        NSString *detailMessage = error.description; // 错误详细信息
    } else {
        // 成功
        NSString *placementId = result.placementId;
    }
}];

参数​

参数是否必填类型说明
controllerYUIViewControllerUnity Controller
optionsYOmniSDKAdOptions预加载广告参数
callbackYBlock预加载广告回调
OmniSDKAdOptions​
参数是否必填类型说明
placementIdYString广告位 ID, 由 OmniSDK 管理后台配置生成

返回值​

OmniSDKPreloadAdResult​
参数类型说明
placementIdString广告位 ID

16. 显示广告(选接)​

SDK Version 3.3.0+

提示

此 API 需要添加 OmniTopOn 模块,集成方式详见 集成 SDK

  • 此 API 并不依赖 preloadAd 接口, 可以直接调用此 API 来显示广告
  • 为了优化体验, 建议先调用预加载广告接口提前加载广告

注意: 需要登录成功才能调用此接口

OmniSDKAdOptions *option = [[OmniSDKAdOptions alloc] init];
option.placementId = @"test_ios_RV_1";
[[OmniSDKv3 shared] showAdWithController:self options:option callback:^(OmniSDKShowAdResult * _Nullable result, OmniSDKError * _Nullable error) {
    if (error != nil) {
        // 失败
        NSInteger code = error.code; // 错误码
        NSString *message = error.message; // 错误信息
        NSString *detailMessage = error.description; // 错误详细信息
    } else {
        // 成功
        OmniSDKShowAdStatus status = result.status;
        NSString *token = result.token;
    }
}];

参数​

参数是否必填类型说明
controllerYUIViewControllerUnity Controller
optionsYOmniSDKAdOptions显示广告参数
callbackYBlock显示广告回调
OmniSDKAdOptions​
参数是否必填类型说明
placementIdYString广告位 ID, 由 OmniSDK 管理后台配置生成

返回值​

OmniSDKShowAdResult​
参数类型说明
statusOmniSDKShowAdStatus广告显示状态
tokenString第三方广告平台标识
OmniSDKShowAdStatus​
参数类型说明
OmniSDKShowAdStatusStartEnum开始显示广告
OmniSDKShowAdStatusClickedEnum广告被点击
OmniSDKShowAdStatusClosedEnum广告被关闭
OmniSDKShowAdStatusRewardedEnum广告播放完成,发放奖励

SDK 数据结构​

购买信息​

OmniSDKPurchaseOptions​
参数是否必填类型说明
productIdYString商品ID
productNameYString商品名称
productDescYString商品描述
productUnitPriceYFloat商品单价，单位：元
purchaseAmountYFloat预期支付总额，单位：元
purchaseQuantityYInt购买数量
purchaseCallbackUrlYString支付回调地址
gameOrderIdYString游戏订单ID，必传
extJsonNString交易扩展参数，JSON 格式字符串
gameCurrencyUnitYString游戏货币单位(如: 魔石, 钻石......)
gameRoleIdYString角色ID
gameRoleNameYString角色名称
gameRoleLevelYString角色等级
gameRoleVipLevelNString角色的VIP等级
gameZoneIdNString区ID
gameServerIdNString服ID

游戏角色信息​

OmniSDKRoleInfo​

参数是否必填类型说明
userIdYString账号ID
gameRoleIdYString角色ID
gameRoleNameYString角色名称
gameRoleLevelYString角色等级
gameRoleVipLevelNString角色VIP等级
gameServerNameYString服务器名称
gameServerIdYString服务器ID
extJsonNString角色扩展参数, JSON 字符串

SDK 登录信息​

OmniSDKLoginInfo​

参数类型说明
userIdString用户 ID
tokenStringtoken
channelIdString渠道 ID
authTimeStringUnix timestamp (服务端安全性验证使用)
signatureString签名 (服务端安全性验证使用)
authMethodOmniSDKAuthMethod登录类型
identityProviderOmniSDKIdentityProvider关联类型
stateOmniSDKAccountState账号状态

SDK 登录类型​

OmniSDKAuthMethod​

类型说明
OmniSDKAuthMethodGuest游客登录
OmniSDKAuthMethodAppleApple ID 登录
OmniSDKAuthMethodFacebookFacebook 登录

SDK 关联账号类型​

OmniSDKIdentityProvider​

类型说明
OmniSDKIdentityProviderApple关联 Apple ID
OmniSDKIdentityProviderFacebook关联 Facebook 账号
OmniSDKIdentityProviderUnknown未关联账号

SDK 账户状态​

OmniSDKAccountState​

类型说明
OmniSDKAccountStateNormal正常账号
OmniSDKAccountStateDeleting正在注销中

异常信息​

OmniSDKCaptureMessage​
参数是否必填类型说明
payloadYString详细记录异常或错误的信息，可提供关于发生问题的具体描述
levelYOmniSDKCaptureLevel定义异常或错误的严重性级别，可帮助分类和优先处理问题
extraNDictionary用于提供额外的上下文数据，可以包括任何有助于理解和解决问题的键值对信息

异常级别​

OmniSDKCaptureLevel​
类型说明
OmniSDKCaptureLevelDebug主要用于开发和调试过程中记录详细信息
OmniSDKCaptureLevelInfo用于记录常规操作和常规信息，这些信息在日常操作中可能有用
OmniSDKCaptureLevelWarning用于记录可能会导致问题的情况，但不一定会影响系统的正常运行
OmniSDKCaptureLevelError用于记录错误情况，这些错误可能会打断当前操作或者导致系统不能正常运行
OmniSDKCaptureLevelFatal用于记录严重错误或者称为致命错误的情况，这些错误可能会导致系统崩溃

OmniSDKError​

数据结构​

字段类型说明
codeIntSDK 错误码
messageString错误描述, 可用于弹出 toast
descriptionString详细错误信息, 可用于输出日志定位错误

使用场景​

  • SDK 回调失败, 获取 SDK 错误信息

代码示例​


- (void)onLoginWithResult:(OmniSDKLoginResult *)result error:(OmniSDKError *)error {
    if (error == nil) {
        NSString *userId = result.userId;
        NSString *token = result.token;
        ...
    } else {
        NSInteger code = error.code
        if (code == OmniSDKErrorCodeUserCancelled) {
            // User Cancel.
            return;
        } else {
            //.....
        }
    }
}

错误码​

错误码枚举值错误描述
1000OmniSDKErrorCodeUnknownError未知错误
1001OmniSDKErrorCodeUserCancelled用户主动取消了操作
1002OmniSDKErrorCodeSystemError操作系统层面返回的错误
1003OmniSDKErrorCodeNetworkError网络错误
1004OmniSDKErrorCodeInvalidArgument参数不合法
1005OmniSDKErrorCodeServerError服务端错误
1006OmniSDKErrorCodeChannelError渠道侧 SDK 错误
2000OmniSDKErrorCodeInvalidAppBundlePlist应用的 Info.plist 参数配置错误
2001OmniSDKErrorCodeFetchAppConfigFailed向服务端请求应用参数失败
2002OmniSDKErrorCodeUnInitializedSDK 未初始化
3000OmniSDKErrorCodeLoginRestricted账号登录暂时被关闭，请稍后再试
3001OmniSDKErrorCodeUnsupportedAuthMethod不支持的登录方式
3002OmniSDKErrorCodeUnderageUserRestricted未成年人禁止登录
4000OmniSDKErrorCodePurchaseRestricted应用内购买暂时被关闭，请稍后再试
4001OmniSDKErrorCodeCreateOrderFailed创建订单失败
4002OmniSDKErrorCodeJailbreakRestricted越狱设备禁止购买
4003OmniSDKErrorCodeFetchProductsFailed获取商品信息失败
4004OmniSDKErrorCodeProductNotFound待购买的商品不存在
4005OmniSDKErrorCodeRegionRestricted当前国家或地区无法购买此商品
4006OmniSDKErrorCodeVerifyTransactionFailed支付订单验证失败
5000OmniSDKErrorCodeLoadAdvertisementFailed加载广告异常
5001OmniSDKErrorCodeShowAdvertisementFailed显示广告异常
最后于 更新