iOS SDK (v4)

GitHub Tag

提示

本指南介绍如何安装和设置 iOS SDK(v4)。如需了解旧版本,请参阅 iOS SDK(旧版本)

iOS SDK 安装

您可以通过以下方法安装 Airbridge iOS SDK。安装后,您可以通过 测试 iOS SDK 来检查 SDK 是否正确安装。

1. 请在 Xcode 中导航至 [File]>[Add Packages...]。

2. 请在搜索栏中输入以下地址,并点击 [Add Package]。

3. 请再次点击 [Add Package]。

4. 请在 Xcode 的 [Package Dependencies] 中确认 Airbridge iOS SDK 已成功添加。

Restricted SDK

提示

请根据需求选择一般 SDK 或 Restricted SDK, 只能安装其中一个。

根据政策或环境,可能需要对收集 设备 ID(例如 GAID 或 IDFA)进行限制。如果安装 Restricted SDK,Airbridge SDK 不会收集设备 ID。

请按照以下说明安装 Restricted SDK:

1. 请在 Xcode 中导航至 [File]>[Add Packages...]。

2. 请在搜索栏中输入以下地址,并点击 [Add Package]。

3. 请再次点击 [Add Package]。

4. 请在 Xcode 的 [Package Dependencies] 中确认 Airbridge iOS SDK 已成功添加。

SDK 初始化

SDK 初始化方法因系统方式而异。SceneDelegate Lifecycle 或 AppDelegate Lifecycle 请参考 AppDelegate,SwiftUI Lifecycle 请参考 SwiftUI。

YOUR_APP_NAMEYOUR_APP_SDK_TOKEN 可在 Airbridge 面板的 [设置]>[Token] 获取。

请在 AppDelegateapplication(_:didFinishLaunchingWithOptions:) 函数顶部调用 Airbridge.initializeSDK 函数。

123456789101112131415
import UIKit
import Airbridge

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
            .build()
        Airbridge.initializeSDK(option: option)
        return true
    }
}

ATT 弹窗提供

提示

为确保遵守隐私政策所需的功能,应与法律顾问共同审查。

在 iOS 环境中,只有在通过 ATT(App Tracking Transparency,应用跟踪透明度)弹窗征得用户同意后,才能收集 IDFA

收集安装事件应延迟到用户允许追踪后进行。IDFA 会与安装事件一同收集,因此如果在用户通过 ATT 弹窗允许追踪之前收集安装事件,IDFA 将缺失,影响绩效监测。建议设置足够的延迟时间,以确保 IDFA 被正确收集。

1. 请准备好您将在 ATT 弹窗中使用的文本。

2. 请在 Info.plist 文件的 NSUserTrackingUsageDescription 值中输入准备好的文本。

  1. 请导航至 [Xcode]>[YOUR_PROJECT]>[Info]>[Custom iOS Target Properties]。

  2. 请将鼠标悬停在 Key 的项目,点击出现的 “+”,并输入 Privacy - Tracking Usage Description

  3. 请将准备好的 ATT 弹窗文本作为值输入。

3. 请设置 ATT 弹窗的弹出时间。

4. 如果未收集到安装事件,Airbridge iOS SDK 会在每次 App 启用时延迟 30 秒尝试收集安装事件,直到用户允许追踪为止。如果用户在决定是否允许追踪之前关闭 App,SDK 将不会收集安装事件,并会在下次启用 App 时重试。

安装事件默认收集延迟时间为 30 秒。您可以使用 setAutoDetermineTrackingAuthorizationTimeout 函数修改此值,最长可达 3600 秒(1 小时)。

1234567
import Airbridge
...
let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME",
                                    token: "YOUR_APP_SDK_TOKEN")
    .setAutoDetermineTrackingAuthorizationTimeout(second: 30)
    .build()
Airbridge.initializeSDK(option: option)

注意

请确保为延迟收集安装事件预留足够时间。在用户通过 ATT 弹窗允许追踪之前,如果延迟时间到期,SDK 将会收集不包含 IDFA 的安装事件。

Opt-in

提示

此功能并非必需功能,请在设置前确认需求。

Opt-in 政策是指在用户同意之前不使用用户信息。

请将 setAutoStartTrackingEnabled 函数设置为 false 后,在可以收集事件时调用 startTracking 函数。从调用 startTracking 函数的时刻起,才开始收集事件。

12345678
import Airbridge
...
let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
    .setAutoStartTrackingEnabled(false)
    .build()
Airbridge.initializeSDK(option: option)
...
Airbridge.startTracking()

Opt-out

提示

此功能并非必需功能,请在设置前确认需求。

Opt-out 政策是指在用户拒绝之前使用用户信息。

setAutoStartTrackingEnabled 函数设置为 true 后,在无法再收集事件时调用 stopTracking 函数。从调用 stopTracking 函数的时刻起,将不再收集事件。

12345678
import Airbridge
...
let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
    .setAutoStartTrackingEnabled(true)
    .build()
Airbridge.initializeSDK(option: option)
...
Airbridge.stopTracking()

SDK 签名 (SDK Signature) 设置

提示

此功能并非必需功能,请在设置前确认需求。

您可以通过 SDK 签名防止 SDK 伪造 (SDK Spoofing)。

SDK 签名设置需要 SDK 签名凭证。SDK 签名凭证包括 Secret 和 Secret ID。您可以在 Airbridge 面板中获取所需的 SDK 签名凭证。SDK 签名凭证的更多信息,请参阅 本指南

您可以通过在 SDK 初始化代码之前调用 setSDKSignature 函数来设置 SDK 签名。

123456789
import Airbridge
...
let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
    .setSDKSignature(
        id: "YOUR_SDK_SIGNATURE_SECRET_ID",
        secret: "YOUR_SDK_SIGNATURE_SECRET"
    )
    .build()
Airbridge.initializeSDK(option: option)

SDK 设置需要以下信息:

  • YOUR_APP_NAME:Airbridge App 名称,可以在 Airbridge 面板的 [设置]>[Token] 中获取。

  • YOUR_APP_SDK_TOKEN:Android SDK Token,可以在 Airbridge 面板的 [设置]>[Token] 中获取。

  • YOUR_SDK_SIGNATURE_SECRET:Secret,可以在 Airbridge 面板的 [规则管理]>[作弊验证规则]>[SDK 签名] 中获取。

  • YOUR_SDK_SIGNATURE_SECRET_ID:Secret ID,可以在 Airbridge 面板的 [规则管理]>[作弊验证规则]>[SDK 签名] 中获取。

您可以通过设置深度链接,将点击包含追踪链接的广告的用户跳转至 App 的特定页面。此外,还可以基于追踪链接收集的信息,在 Airbridge 面板查看通过深度链接产生的绩效。

Airbridge 深度链接的工作原理

Airbridge 会根据环境自动选用最适合的 Airbridge 深度链接来实现用户跳转。用于实现用户跳转的链接被称为 URI Scheme 深度链接。

示例:

  • Airbridge 深度链接:https://YOUR_APP_NAME.airbridge.io/~~~

  • URI Scheme 深度链接:YOUR_SCHEME://product/12345

当 App 已安装时,用户点击追踪链接后,App 将通过 Airbridge 深度链接打开。随后,Airbridge SDK 会将该 Airbridge 深度链接转换为追踪链接中配置的 URI Scheme 深度链接,并将转换后的 URI Scheme 深度链接传递给 App。

当 App 未安装时,用户点击追踪链接后,Airbridge 会保存深度链接信息。用户被发送至应用商店或网站安装并打开 App 后,Airbridge SDK 会将保存的 Airbridge 深度链接转换为 URI Scheme 深度链接,并将转换后的 URI Scheme 深度链接传递给 App。

深度链接设置

请按照以下步骤设置深度链接。请准备在 Airbridge 面板中注册的深度链接信息和用户跳转目的地的 App 内页面地址。

首先,请在 Airbridge 面板注册深度链接信息。

在 Airbridge 面板注册深度链接信息后,需要在 App 中设置深度链接。请根据 App 的系统方式,查看相应的深度链接设置流程。

当 App 未安装时,如果用户点击了设置了延迟深度链接的追踪链接,Airbridge 会保存深度链接信息。Airbridge SDK 会通过以下方法来获取保存的深度链接:

Airbridge.handleDeferredDeeplink 函数在获取已保存的 Airbridge 深度链接后,会将 Airbridge 深度链接转换为 URI Scheme 深度链接,并将转换后的 URI Scheme 深度链接传递给 App。转换后的 URI Scheme 深度链接将用户发送至设置的目的页面。

1234567891011
import Airbridge
...
let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
    .build()
Airbridge.initializeSDK(option: option)
...
let isHandled = Airbridge.handleDeferredDeeplink() { url in
    if let url {
        // show proper content using url (YOUR_SCHEME://...)
    }
}

Airbridge.handleDeferredDeeplink 函数在 App 安装后首次被调用时会返回 true,并等待获取 Airbridge 深度链接,将其转换为 URI Scheme 深度链接后传递给 onSuccess。您可以使用该 URI Scheme 深度链接将用户发送至预设目标页面。

如果没有保存的 Airbridge 深度链接,则会向 onSuccess 传递 nil。如果 SDK 尚未初始化,或 Airbridge.handleDeferredDeeplink 函数并非首次被调用,则会返回 false

传递的 URI Scheme 深度链接通常是 YOUR_SCHEME://... 格式的 URL。如果使用 Meta Deferred App Link 等服务,则可能会传递其他格式的 URL。

应用内事件

Airbridge SDK 会根据设置从您的服务中收集特定用户行为,并将其作为应用内事件发送。

应用内事件发送

Hybrid App 设置

在 Hybrid App 中,无需更改网站代码,即可通过设置使 iOS SDK 处理应用内网站上出现的与 Airbridge 相关的操作。

为了发送事件,需要调用 Airbridge.trackEvent 函数。Airbridge.trackEvent 函数构成要素及其必需性如下。

1234567891011121314
static func trackEvent(
    category: String
)

static func trackEvent(
    category: String,
    semanticAttributes: [String : Any]
)

static func trackEvent(
    category: String,
    semanticAttributes: [String : Any],
    customAttributes: [String : Any]
)

构成要素

是否必需

类型

说明

category

必需

String

事件名称

semanticAttributes

可选

[String: Any]

事件标准属性

customAttributes

可选

[String: Any]

事件自定义属性

各构成要素的定义和可用数据类型请参阅下文:

SDK 提供的标准事件 Category 和 Semantic Attribute 如下:

各数据类型的示例代码如下:

123456789101112131415
import Airbridge
...
Airbridge.trackEvent(
    category: "event",
    semanticAttributes: [
        AirbridgeAttribute.VALUE: 10,
    ],
    customAttributes: [
        "string": "string",
        "number": 1000,
        "boolean": true,
        "object": ["key": "value"],
        "array": ["value"],
    ]
)

应用内事件其他设置

提示

如果未配置其他设置,则将应用默认设置。请查看是否需要其他设置后再继续。

应用内事件示例代码

Airbridge 收集的主要应用内事件是标准事件和自定义事件。标准事件是 Airbridge 预定义的事件,请参阅以下的示例代码: