集成 SDK

目前暂时仅支持手动集成方式。
后续计划添加更多的集成方式，例如 CocoaPods 和 Swift Package Manager。

手动集成步骤

危险

• 接入前请 删除 所有旧版本 SDK 相关的 Framework，不要将不同版本的 Framework 混接
• 不要将 混淆 后的 Framework 和未混淆的 Framework 混接

获取 SDK 版本

请从 版本更新说明 下载 SDK 的最新版本。

v3.2.0 or later

警告

• OmniCore、OmniAPI为 OmniSDK iOS 核心组件，核心组件为必接项。
• 接入渠道组件是必需的，且仅允许接入一个渠道组件。

v3.2.0 及以上版本重构了组件模块，并集成了三个独立的渠道组件：

• OmniPassport (金山通行证)
• OmniSeayooAccount (世游通行证)
• OmniOversea (海外SDK)

下载并解压后，将得到如下图的目录结构：

History Version (低版本)

提示

v3.2.0 以下版本无渠道概念，按需集成组件即可。

v3.2.0 以下版本下载并解压后，将得到如下图的目录结构：

SDK 初始化参数

危险

以下配置为 SDK 初始化核心参数，未配置将导致 SDK 无法正常运行。

v3.2.0 or later

提示

每个渠道对应一个 OmniSDKChannel 值，请根据接入渠道配置对应值：

• OmniPassport : kspassport
• OmniSeayooAccount : seayoo
• OmniOversea : oversea

在 info.plist 文件中添加如下配置，参数获取请联系 SDK 开发人员

Key	类型	是否必填	说明
OmniSDKAppId	String	Y	appid
OmniSDKAppKey	String	Y	appkey
OmniSDKPlanId	String	Y	发布计划
OmniSDKChannel	String	Y	渠道名称

示例：

v2.6.0 ~ v3.1.0

v2.6.0+ 版本已废弃** omnisdk_config.json **配置文件，只需要在 info.plist 文件中添加如下配置，参数获取请联系 SDK 开发人员

Key	类型	是否必填	说明
OmniSDKAppId	String	Y	appid
OmniSDKAppKey	String	Y	appkey
OmniSDKPlanId	String	Y	发布计划

示例：

History Version(低版本)

请将配置文件** omnisdk_config.json **添加至项目中

• SDK 会从 iOS 应用中内嵌的一个配置文件 omnisdk_config.json 读取功能所需的配置项。

• 这个配置文件不需要手动编辑，而是在 SDK 的管理后台进行项目配置并生成下载的。

• 请联系 SDK 开发人员获取配置文件，再集成到游戏工程中即可。

集成至 Xcode 工程

将要使用的 XCFrameworks 文件夹 与 omnisdk_config.json拖入工程，拖入的时候 Xcode 会弹出如下图选项框，请按照下图在选项框中勾选：

Xcode 工程配置

嵌入动态库

危险

不配置此项，会导致应用在启动时因为缺少动态库而 crash

OmniSDK iOS v2 已从静态库切换为动态库的形式，因此需要将动态库文件嵌入到最终发布的 App 中。

如果不做这一步，应用会在启动时会因为找不到动态库而 crash (image not found)。

在 Xcode 工程路径中 General -> Frameworks, Libraries, and Embedded Content 中把选项 Do Not Embed 改为 Embed & Sign，如图所示：

关闭 Bitcode

信息

Apple 目前已废弃 Bitcode，所以 SDK 也不会考虑对 Bitcode 提供支持。

在 TARGETS -> Build Settings 中，搜索 Enable Bitcode，将参数设置为 No，如图所示：

启用 Sign in with Apple

Unity 工程配置

如果游戏工程使用的引擎是 Unity，则在上述手动集成的基础上，还需要针对 Unity 做以下配置。

嵌入动态库

危险

不配置此项，会导致游戏客户端在启动时因为缺少动态库而 crash

在 Target Unity-iPhone 中，嵌入以下动态库（把选项 Do Not Embed 改为 Embed & Sign）

• 添加 OmniSDK 的 XCFramework（如果使用多个组件就添加多个）

在 Target UnityFramework 中，添加以下动态库（Do Not Embed）

• 添加 OmniSDK 的 XCFramework（如果使用多个组件就添加多个）

链接配置

危险

• 不配置此项，有概率 会出现游戏客户端启动时黑屏，并在 20 秒后被 iOS 系统的 watchdog 强行杀掉，黑屏的原因是类加载初始化时死锁。
• 此现象 非必现，和 SDK、游戏客户端的代码实现，以及所集成的第三方依赖的代码实现相关。
• 由于第三方依赖的代码存在不可控性，稳妥起见建议使用 Unity 的游戏客户端都配置此项。

此配置能够将 UnityFramework 和游戏客户端的主程序一起加载（而非默认的延迟加载），从而避免一些由于类加载初始化时死锁导致的启动黑屏问题。

在 Target Unity-iPhone 中，将 Build Phases -> Link Binary with Libraries 添加 UnityFramework.framework

Swift 标准库适配

危险

只有在 Xcode 工程的 iOS Deployment Target < 12.2 时，才需要进行以下配置。
参见 https://www.swift.org/blog/abi-stability-and-apple/

嵌入 Swift 标准库

如果不做这一步，应用在低版本的 iOS 上 (< 12.2) 启动时会因为找不到 Swift 标准库而 crash (image not found)。

在 Target Unity-iPhone 中，将 Build Settings -> Always Embed Swift Standard Libraries to Yes

Runpath Search Paths

提示

如果游戏工程使用了 CocoaPods，则此步骤可省略。
因为 CocoaPods 会自动添加/usr/lib/swift 到 Runpath 中。

这是针对低版本的 iOS (< 12.2) 做的适配，避免应用启动时遇到 libswiftCore.dylib 相关的问题。

在 Target Unity-iPhone 中，添加 /usr/lib/swift to Build Settings -> Runpath Search Paths, 特别要注意的是只能在 首行配置。

可选组件的配置

OmniReyun (热云)

• 将 OmniReyun.xcframework 添加到 Xcode，设置 Embed & Sign

OmniWhale (蓝鲸)

• 将 OmniReyun.xcframework 添加到 Xcode，设置 Embed & Sign
• info.plist 需要额外添加配置项：
  • XgDataUrl: 蓝鲸数据上报的 URL 地址，填写 https://data.xgsdk.com
  • xgsdk_sdkAppid: OmniSDK 分配的应用 ID，请联系 SDK 开发人员 获取

<key>XgDataUrl</key>
<string>https://data.xgsdk.com</string>
<key>xgsdk_sdkAppid</key>
<string>demo</string>

OmniDouyinUOP (抖音直播联运)

SDK Version 2.1.0+

危险

抖音直播联运模块不是一个单独的 xcframework，而是一个资源集合的文件夹。
注：接入此模块必须实现API application: didFinishLaunch

Xcode 工程配置

Frameworks 添加到 Xcode，设置 Embed & Sign

• OmniDouyinUOP.xcframework
• TTNetworkManager.framework，
• UnionOpenPlatform.framework

Bundle

危险

Unity: Bundle 文件只放到 Target Unity-iPhone 中

• UOPSDKResource.bundle
• APMInsightCore.bundle
• APMInsightCrash.bundle
• RangersAppLog.bundle

请求权限

在 Custom iOS Target Properties -> Privacy - Tracking Usage Description

添加自定义描述文字，例如: 该标识符用于向您推送个性化服务

描述文字可以按照接入方的意愿修改让用户更容易接受的文案

Linking

在 Build Settings -> Linking -> Other Linker Flags 添加 -ObjC，注意区分大小写

OmniTopOn (TopOn广告)

SDK Version 3.3.0+

危险

OmniTopOn 模块不是一个单独的 xcframework，而是一个资源集合的文件夹。

Xcode 工程配置

Frameworks 添加到 Xcode，设置 Embed & Sign

• KSAdSDK.xcframework
• OmniTopOn.xcframework

请求权限

在 Custom iOS Target Properties -> Privacy - Tracking Usage Description

添加自定义描述文字，例如: 该标识符用于向您推送个性化服务

描述文字可以按照接入方的意愿修改让用户更容易接受的文案

OmniBDASignal（巨量引擎归因）

SDK Version: 2.4.6+

危险

OmniBDASignal 模块不是一个单独的 xcframework，而是一个资源集合的文件夹。

Xcode 工程配置

Frameworks 添加到 Xcode，设置 Embed & Sign

• BDASignalSDK.framework
• OmniBDASignal.xcframework
• Protobuf.framework

API 接入

接入此模块必须要调用 SDK 以下两个 API，否则将影响投放归因的准确性

• application:didFinishLaunchingWithOptions:
• application:open:options:

URL Scheme 配置

在 info.plist 中按照下图所示步骤添加 URL Scheme

URL Scheme 的值为当前应用的包名

例如：假设一个包的包名为：com.test.example，则配置对应的URL scheme： com.test.example

OmniFacebookLogin（FB 登录）

• 将 OmniFacebookLogin.xcframework 添加到 Xcode，设置 Embed & Sign
• 配置 Facebook 相关参数，参考：配置项目

OmniShare（分享）

注意：需要安装 Facebook 应用才可拉起分享

• 将 OmniShare.xcframework 添加到 Xcode，设置 Embed & Sign
• 在 info.plist 中添加以下配置

  <key>LSApplicationQueriesSchemes</key>
  <array>
    <string>fbauth2</string>
  </array>