User GuideDeveloper GuideAPI
Dashboard

Cordova-Ionic SDK (v4)

NPM Version

提示

本指南介绍如何安装和设置 Cordova-Ionic SDK（v4）。如需了解旧版本，请参阅 Cordova-Ionic SDK（旧版本）。

Cordova-Ionic SDK 安装

您可以通过以下方法安装 Airbridge Cordova-Ionic SDK。安装后，您可以通过 测试 Cordova-Ionic SDK 来检查 SDK 是否正确安装。

请根据各平台安装 airbridge-cordova-sdk plugin。

1
cordova plugin add airbridge-cordova-sdk

SDK 初始化

iOS SDK 与 Android SDK 的初始化方式不同。请参阅以下指南。

YOUR_APP_NAME 和 YOUR_APP_SDK_TOKEN 可在 Airbridge 面板的 [设置]>[Token] 获取。

iOS

请将以下代码添加至 ios/[Project 名称]/AppDelegate.m 文件的 application:didFinishLaunchingWithOptions: 函数中。

1234
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    AirbridgeCordova.initializeSDK(name:"YOUR_APP_NAME", token:"YOUR_APP_TOKEN")
    ...
}

Android

  1. Android SDK 需在 Android Application class 中初始化。请创建 Application class。请在 platforms/android/app/src/main/java/[PACKAGE NAME]/MainApplication.java 添加文件。如果已创建 Application class，请直接进行步骤 3。

  2. 请在 AndroidManifest.xml 中配置创建的 Application。

    AndroidManifest.xml
    123
     <application
        android:name=".AndroidApplication"
        ...>

  3. 请在 platforms/android/app/src/main/java/[PACKAGE NAME]/MainApplication.java 文件中按如下方式添加代码。

    1234567
    import co.ab180.airbridge.cordova.AirbridgeCordova
...
override fun onCreate() {
    super.onCreate()
    AirbridgeCordova.initializeSDK(this, "YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
    ...
}

SDK 设置

请输入用于 Airbridge Cordova-Ionic SDK 的配置值。

12345678910111213141516171819
{
    "sdkEnabled": boolean,
    "logLevel": "debug" | "info" | "warning" | "error" | "fault",
    "autoStartTrackingEnabled": boolean,
    "autoDetermineTrackingAuthorizationTimeoutInSecond": number,
    "trackMetaDeferredAppLinkEnabled": boolean,
    "sessionTimeoutInSecond": number,
    "metaInstallReferrerAppID": string,
    "trackAirbridgeDeeplinkOnlyEnabled": boolean,
    "trackInSessionLifecycleEventEnabled": boolean,
    "hashUserInformationEnabled": boolean,
    "sdkSignatureID": string,
    "sdkSignatureSecret": string,
    "clearEventBufferOnInitializeEnabled": boolean,
    "eventBufferCountLimit": number,
    "eventBufferSizeLimitInGibibyte": number,
    "eventTransmitIntervalInSecond": number,
    "isHandleAirbridgeDeeplinkOnly": boolean
}

1. 请在 Cordova-Ionic Project 文件夹的顶部创建 airbridge.json 文件，并按照上方示例输入 JSON。

2. 对于不需要配置的值，请省略对应的键。

有关配置值的更多信息，请参阅以下指南：

ATT 弹窗提供

提示

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

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

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

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

2. 请按照 Apple 文档 设置 ATT 弹窗。

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

您可以使用 SDK 设置 的 autoDetermineTrackingAuthorizationTimeoutInSecond 函数修改延迟时间。该函数的默认值为 30 秒，最大可设置为 3600 秒（1 小时）。

注意

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

Opt-in

提示

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

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

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

1
Airbridge.startTracking()

Opt-out

提示

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

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

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

1
Airbridge.stopTracking()

SDK 签名（SDK Signature）设置

提示

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

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

SDK 签名设置需要以下 SDK 签名凭证：

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

  • sdkSignatureSecret：Secret，可以在 Airbridge 面板的 [规则管理]>[作弊验证规则]>[SDK 签名]>[SDK 签名凭证] 中获取。

SDK 签名凭证的更多信息，请参阅 本指南。

请输入 SDK 设置 的 sdkSignatureID 和 sdkSignatureSecret。

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

Airbridge 深度链接的工作原理

Airbridge 在追踪链接打开时，会根据用户环境，将追踪链接中配置的 URI Scheme 深度链接转换为最适合的 Airbridge 深度链接（HTTP 深度链接或 URI Scheme 深度链接）以引导用户进入 App。随后，Airbridge SDK 会将 Airbridge 深度链接重新转换为追踪链接中配置的 URI Scheme 深度链接，并传递至 App。

  • 追踪链接中配置的 URI Scheme 深度链接示例：YOUR_SCHEME://product/12345

  • Airbridge 深度链接示例：

    • HTTP 深度链接格式 1：https://YOUR_APP_NAME.airbridge.io/~~~

    • HTTP 深度链接格式 2：https://YOUR_APP_NAME.abr.ge/~~~

    • URI Scheme 深度链接格式：YOUR_SCHEME://product/12345?airbridge_referrer=~~~

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

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

深度链接设置

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

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

在 Airbridge 面板注册深度链接信息后，请进行设置启用以下功能：

延迟深度链接（Deferred Deep Link）设置

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

延迟深度链接会自动传递给 OnDeeplinkReceived，无需额外设置。

应用内事件

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

应用内事件发送

Hybrid App 设置

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

请调用 Airbridge.trackEvent 函数以发送事件。Airbridge.trackEvent 函数构成要素的类型及其必需性如下：

1234567891011
/**
 * Tracks user behavior through event tracking with attributes.
 * @param category Name of event.
 * @param semanticAttributes Additional attributes of the event that defined by Airbridge.
 * @param customAttributes Additional attributes of the event.
 */
static trackEvent(
    category: string,
    semanticAttributes?: Record<string, any>,
    customAttributes?: Record<string, any>,
): void

名称

是否必需

类型

说明

category

必需

string

事件名称

semanticAttributes

可选

Record<string, any>

事件标准属性

customAttributes

可选

Record<string, any>

事件自定义属性

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

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

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

12345678910111213
Airbridge.trackEvent(
    'event',
    {
        [AirbridgeAttribute.VALUE]: 10,
    },
    {
        'string': 'string',
        'number': 1000,
        'boolean': true,
        'object': {'key': 'value'},
        'array': ['value'],
    },
)

应用内事件其他设置

提示

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

您可以为发送的应用内事件添加所需的设置。

应用内事件示例代码

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

自定义事件是 Airbridge 客户自定义的事件，用于追踪无法通过标准事件满足的、针对 Airbridge 客户服务定制的用户行为。请参阅以下的示例代码。

12345678910111213
Airbridge.trackEvent(
    'event',
    {
        [AirbridgeAttribute.VALUE]: 10,
    },
    {
        'string': 'string',
        'number': 1000,
        'boolean': true,
        'object': {'key': 'value'},
        'array': ['value'],
    },
)

用户信息

您可以将用户信息随事件一同发送至 Airbridge，以基于这些信息更精确地监测跨 Web 和 App 的广告绩效。

用户 ID 设置

用户 ID 是您服务中使用的用户标识符。用户 ID 必须唯一，能够在 Web 和 App 中将同一用户识别为一个用户。

#{"width":"140px"}

函数

#{"width":"240px"}

说明

Airbridge.setUserID

输入用户 ID

Airbridge.clearUserID

删除用户 ID

Airbridge.setUserAlias

输入其他用户标识符，最多可输入 10 个

- key：最多 128 个字符，必须符合正则表达式 ^[a-zA-Z_][a-zA-Z0-9_]*$

- value：最多 1024 个字符

Airbridge.removeUserAlias

从输入的其他用户标识符中删除指定的标识符

Airbridge.clearUserAlias

删除所有输入的其他用户标识符

请参阅以下的示例。

1234567
// identifier
Airbridge.setUserID('string')
Airbridge.clearUserID()
// addtional identifier
Airbridge.setUserAlias('string', 'string')
Airbridge.removeUserAlias('string')
Airbridge.clearUserAlias()

用户属性设置

注意

可能包含敏感的用户信息。发送前请咨询法律顾问。

您可以通过设置用户属性发送其他用户信息。

#{"width":"140px"}

函数

#{"width":"240px"}

说明

Airbridge.setUserEmail

输入用户邮箱，自动进行 SHA256 哈希处理

Airbridge.clearUserEmail

删除用户邮箱

Airbridge.setUserPhone

输入用户电话号码，自动进行 SHA256 哈希处理

Airbridge.clearUserPhone

删除用户电话号码

Airbridge.setUserAttribute

输入其他用户属性，最多可输入 100 个

- key：最多 128 个字符，必须符合正则表达式 ^[a-zA-Z_][a-zA-Z0-9_]*$

- value：仅支持 String、Number、Boolean 类型，最多 1024 个字符

Airbridge.removeUserAttribute

从输入的其他用户属性中删除指定属性

Airbridge.clearUserAttributes

删除所有输入的其他用户属性

请参阅以下的示例。

12345678910
// email, phone
Airbridge.setUserEmail('string')
Airbridge.clearUserEmail()
Airbridge.setUserPhone('string')
Airbridge.clearUserPhone()
// addtional attribute
Airbridge.setUserAttribute('string', 'string')
Airbridge.setUserAttribute('number', 1000)
Airbridge.removeUserAttribute('string')
Airbridge.clearUserAttributes()

用户属性哈希处理

如果将 SDK 设置 的 hashUserInformationEnabled 函数设置为 false，则发送用户邮箱和电话号码时不会进行 SHA256 哈希处理。默认设置为 true。

用户信息重置

您可以使用 Airbridge.clearUser 函数重置用户信息。

1
Airbridge.clearUser()

高级设置

提示

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

仅收集 Airbridge 深度链接

提示

Cordova-Ionic SDK 需为 v4.2.0 或以上版本。

通过 Airbridge Cordova-Ionic SDK 的 setOnDeeplinkReceived 方法接收的深度链接，不仅包括 Airbridge 深度链接，还可能包括其他解决方案的深度链接或自定义深度链接。

123
Airbridge.setOnDeeplinkReceived(function (url) {
    // show proper content using url
})

您可以通过将 SDK 设置 的 isHandleAirbridgeDeeplinkOnly 设置为 true，仅收集 Airbridge 深度链接。

在 App 中使用追踪链接

根据链接的打开方式，在 App 内正确使用追踪链接可能会有一定困难。

通过使用 Airbridge.click 函数或 Airbridge.impression 函数，您可以使用户在 App 中跳转到同一 App 的另一个页面，无需通过外部浏览器。

注意

在 Airbridge SDK 设置 “在 App 中使用追踪链接” 功能后，每次在 App 中使用追踪链接时，将记录 “深度链接页面浏览（Deeplink Pageview）” 作为 目标事件（Target Event）。如果深度链接页面浏览频繁随深度链接打开（Deeplink Open）发生，可能会影响深度链接打开的绩效。

深度链接页面浏览的的默认归因窗口为 3 天。如果希望更改此归因窗口，请联系您的 CSM。

归因结果（Attribution Result）使用

注意

Airbridge SDK 收集归因结果需要时间，因此不建议将归因结果用于需要实时处理的功能。

您可以使用 Airbridge.setOnAttributionReceived 函数收取归因结果数据。

123
Airbridge.setOnAttributionReceived((attribution) => {
    // when attribution is received
})

根据归因结果的存在与否，数据传递如下：

推送通知深度链接收集

点击推送通知后，需要将 Payload 中的深度链接信息传递给 Airbridge SDK，才能收集深度链接事件。请使用 Airbridge.trackDeeplink 函数进行设置。

iOS

请将以下代码添加至 ios/YOUR_PROJECT_NAME/AppDelegate.m 文件中。

12345678910111213141516171819202122232425262728
import Airbridge

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable : Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    if UIApplication.shared.applicationState == .inactive {
        let url = // 푸시 알림 페이로드의 딥링크

        Airbridge.trackDeeplink(url)
    }
}

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandlercompletionHandler: @escaping () -> Void
) {
    if 
        UIApplication.shared.applicationState == .inactive || UIApplication.shared.applicationState == .background,
        response.actionIdentifier == UNNotificationDefaultActionIdentifier
    {
        let url = // 푸시 알림 페이로드의 딥링크

        Airbridge.trackDeeplink(url)
    }
}

Android

Android 会自动收集，无需额外设置。

无论深度链接由何种服务生成，只要通过深度链接启用 App，Airbridge SDK 即会收集深度链接事件。您可以将 SDK 设置 的 trackAirbridgeDeeplinkOnlyEnabled 函数设置为 true，仅收集由 Airbridge 深度链接触发的事件。

会话中发生的生命周期事件收集

Airbridge SDK 会收集开启新会话的 Open 事件和 Foreground 事件，但在会话持续期间，这些事件不会被收集。

您可以通过将 SDK 设置 的 trackInSessionLifecycleEventEnabled 函数设置为 true，以在会话持续期间也收集 Open 事件和 Foreground 事件。

所有收集到的 Foreground 事件都将被记录为 Open 事件。

Google 《数字市场法案》（DMA）遵守设置

为遵守 DMA，用户的同意信息（User Consent）必须共享给 Airbridge。请注意，如果用户位于欧洲经济区（European Economic Area，简称 EEA），则必须始终向 Airbridge 共享用户是否位于 EEA 以及用户的同意信息。DMA 的更多信息，请参阅 本指南。

1. 请检查启用 App 的用户所在地。如果用户在 EEA（eea=1）启用了 App，则检查是否已取得该用户的同意信息。如果已取得，请继续步骤 3。

提示

Airbridge 无法提供有关存储用户同意信息或实现同意弹窗的指导。请咨询法律顾问。

2. 如果尚未取得用户的同意信息，请通过同意弹窗等方法取得用户的同意信息。必须收集 adPersonalization 和 adUserData。

3. 请将 SDK 设置 的 autoStartTrackingEnabled 设置为 false。

4. 请初始化 Airbridge SDK，并在收集用户信息之前将用户同意信息共享给 Airbridge。

注意

  • 必须为 eea、adPersonalization 和 adUserData 使用相同的名称。

  • 请根据收集的信息正确输入 0 或 1。

12345678
// deliver informations to sdk using device alias
// based on actual region
Airbridge.setDeviceAlias('eea', '0' or '1')
// based on actual user consent
Airbridge.setDeviceAlias('adPersonalization', '0' or '1')
Airbridge.setDeviceAlias('adUserData', '0' or '1')
// start tracking explicitly
Airbridge.startTracking()

请按以下步骤在 Meta ads 中设置 延迟深度链接。Airbridge SDK 优先收集 Meta Deferred App Link，若无 Meta Deferred App Link 则收集 Airbridge 延迟深度链接。

Meta ads 中的 SKAN 广告系列不支持 Meta Deferred App Link。

1. 请安装 Facebook SDK。请参阅 Meta ads 文档（iOS）和 Meta ads 文档（Android）。

2. 请将 SDK 设置 的 trackMetaDeferredAppLinkEnabled 函数设置为 true。

在禁用状态下初始化 Airbridge SDK

注意

如果 Airbridge SDK 在初始化后未立即启用，则可能无法收集安装（Install）、打开（Open）、深度链接（Deeplink）事件。

初始化 SDK 时，所有功能将默认启用。您可以通过将 SDK 设置 的 sdkEnabled 函数设置为 false，在禁用所有功能的状态下初始化 Airbridge SDK。

或者，可以通过以下方法检查 Airbridge SDK 的启用状态，并启用或禁用所有功能。

123
Airbridge.isSDKEnabled()
Airbridge.enableSDK()
Airbridge.disableSDK()

Meta Install Referrer (MIR) 收集设置

以下是收集 MIR 所需的设置。请在 SDK 初始化阶段，将 Meta App ID 传递给 SDK 设置 的 metaInstallReferrerAppID。

完成设置后，需要将 Install Referrer Decryption Key（安装引荐来源解密密钥）注册到 Airbridge 面板，才能查看解密后的 MIR。如何注册 Install Referrer Decryption Key，请参阅 本指南。

App 卸载追踪

Airbridge 会向过去 6 个月内执行过至少 1 次 App 事件的用户发送静默推送通知，以检查用户是否已卸载 App。此静默推送通知在每天 UTC 15:00 至 16:00 之间发送。App 卸载事件可在 Airbridge 报告和通过导出原始数据查看。

详细设置方法和说明，请参阅以下指南：

第三方解决方案集成

部分第三方解决方案的集成需要进行 SDK 设置。建议在通过 Airbridge SDK 收集数据之前，完成所需设置。

各第三方解决方案的集成设置，请参阅以下指南：

SDK 日志查看

Airbridge SDK 提供的日志分为以下 5 个级别：Debug、Info、Warning、Error 和 Fault。 Debug 为严重性最低的日志级别，Fault 为最严重的日志级别。

Airbridge SDK 默认提供 Warning、Error 和 Fault 级别日志。通过将日志级别输入 SDK 设置 的 logLevel 函数，可以查看从该日志级别到 Fault 级别的所有日志。

Was this page helpful?

Have any questions or suggestions?