User GuideDeveloper GuideAPI
Dashboard

Unreal SDK (v4)

提示

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

Unreal SDK 安装

Airbridge Unreal SDK 需要 Unreal Engine 4.23 或以上版本。

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

1. 请下载最新版本的 Airbridge Unreal SDK。

2. 请在 Unreal Engine 项目的根目录下创建 Plugins 文件夹。

3. 请将 Airbridge Unreal SDK 移动至 Plugins 文件夹内，结构如下：

123456
<YOUR_UE_PROJECT>
  ├── Plugins
          └── AirbridgeUnrealSDK
              ├── Resources
              ├── Source
              └── AirbridgeUnrealSDK.uplugin

4. 请在 Unreal Engine 工具栏中点击 [Settings]>[Plugins]，启用 Airbridge Unreal SDK。

5. 请在 App 的 Build.cs 文件（<YOUR_UE_PROJECT>.Build.cs）内的 PublicDependencyModuleNames 数组中，添加 AirbridgeUnreal，如下所示：

123456789
public class <YOUR_UE_PROJECT> : ModuleRules
{
    public <YOUR_UE_PROJECT>(ReadOnlyTargetRules Target) : base(Target)
    {
        ...
        PublicDependencyModuleNames.AddRange(new string[] { ... , "AirbridgeUnreal" });   // ADD DEPENDENCY 
        ...
    }
}

Restricted SDK

提示

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

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

请按照以下步骤安装 Restricted SDK：

1. 请下载最新版本的 Airbridge Unreal SDK。

2. 请在 Unreal Engine 项目的根目录下创建 Plugins 文件夹。

3. 请将 Airbridge Unreal SDK 移动至 Plugins 文件夹内，结构如下：

123456
<YOUR_UE_PROJECT>
  ├── Plugins
          └── AirbridgeUnrealSDK
              ├── Resources
              ├── Source
              └── AirbridgeUnrealSDK.uplugin

4. 请在 Unreal Engine 工具栏中点击 [Settings]>[Plugins]，启用 Airbridge Unreal SDK。

5. 请在 App 的 Build.cs 文件（<YOUR_UE_PROJECT>.Build.cs）内的 PublicDependencyModuleNames 数组中，添加 AirbridgeUnreal，如下所示：

123456789
public class <YOUR_UE_PROJECT> : ModuleRules
{
    public <YOUR_UE_PROJECT>(ReadOnlyTargetRules Target) : base(Target)
    {
        ...
        PublicDependencyModuleNames.AddRange(new string[] { ... , "AirbridgeUnreal" });   // ADD DEPENDENCY 
        ...
    }
}

SDK 初始化

请在 SDK 设置 的 App Name 和 App Token 输入正确的值。

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

SDK 设置

1. 请打开 Unreal Engine 的 Project Settings 窗口。

2. 在 Plugins 选项下点击 Airbridge Unreal SDK，即可查看以下界面。对于不需要配置的值，请省略对应的键。

3. 填写所需输入值后，请点击 Set as Default 按钮。

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

ATT 弹窗提供

提示

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

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

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

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

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

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

您可以使用 SDK 设置 的 iOS Tracking Authorization Timeout Seconds 修改延迟时间。默认值为 30 秒，最大可设置为 3600 秒（1 小时）。

注意

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

Opt-in

提示

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

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

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

1
FAirbridge::StartTracking();

Opt-out

提示

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

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

请将 SDK 设置 的 Auto Start Tracking Enabled 设置为 true 后，在无法再收集事件时调用 StopTracking 函数。从调用 StopTracking 函数的时刻起，将不再收集事件。

1
FAirbridge::StopTracking();

SDK 签名 (SDK Signature) 设置

提示

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

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

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

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

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

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

请在 SDK 设置 输入 SDK Signature Secret ID 和 SDK Signature Secret。

您可以通过设置深度链接，将点击包含追踪链接的广告的用户跳转至 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 中，无需更改网站代码，即可通过设置使 Unreal SDK 处理应用内网站上出现的与 Airbridge 相关的操作。

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

12345
static void TrackEvent(
	const FString& Category,
	const UAirbridgeMap* SemanticAttributes = nullptr,
	const UAirbridgeMap* CustomAttributes = nullptr
);

名称

是否必需

类型

说明

category

必需

String

事件名称

semanticAttributes

可选

UAirbridgeMap

事件标准属性

customAttributes

可选

UAirbridgeMap

事件自定义属性

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

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

아래 데이터 유형별 예시 코드를 참고해 주세요.

1234567891011
FAirbridge::TrackEvent(
    "event",
    UAirbridgeMap::CreateObject()
        ->Set(AirbridgeAttribute::VALUE, 10),
    UAirbridgeMap::CreateObject()
        ->Set("string", "string")
        ->Set("number", 1000)
        ->Set("boolean", true)
        ->Set("object", UAirbridgeMap::CreateObject()->Set("key", "value"))
        ->Set("array", UAirbridgeList::CreateObject()->Add("value"))
);

应用内事件其他设置

提示

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

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

应用内事件示例代码

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

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

1234567891011
FAirbridge::TrackEvent(
    "event",
    UAirbridgeMap::CreateObject()
        ->Set(AirbridgeAttribute::VALUE, 10),
    UAirbridgeMap::CreateObject()
        ->Set("string", "string")
        ->Set("number", 1000)
        ->Set("boolean", true)
        ->Set("object", UAirbridgeMap::CreateObject()->Set("key", "value"))
        ->Set("array", UAirbridgeList::CreateObject()->Add("value"))
);

用户信息

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

用户 ID 设置

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

#{"width":"140px"}

函数

#{"width":"240px"}

说明

FAirbridge::SetUserID

输入用户 ID

FAirbridge::ClearUserID

删除用户 ID

FAirbridge::SetUserAlias

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

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

- value：最多 1024 个字符

FAirbridge::RemoveUserAlias

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

FAirbridge::ClearUserAlias

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

请参阅以下的示例。

1234567
// ID
FAirbridge::SetUserID("testID");

// Alias
FAirbridge::SetUserAlias("ADD_YOUR_KEY", "ADD_YOUR_VALUE");
FAirbridge::RemoveUserAlias("DELETE_THIS_KEY");
FAirbridge::ClearUserAlias();

用户属性设置

注意

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

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

#{"width":"140px"}

函数

#{"width":"240px"}

说明

FAirbridge::SetUserEmail

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

FAirbridge::ClearUserEmail

删除用户邮箱

FAirbridge::SetUserPhone

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

FAirbridge::ClearUserPhone

删除用户电话号码

FAirbridge::SetUserAttribute

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

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

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

FAirbridge::RemoveUserAttribute

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

FAirbridge::ClearUserAttributes

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

请参阅以下的示例。

1234567891011121314
// Automatically hashed on client side using SHA256
// Can turn off hashing feature with special flag
FAirbridge::SetUserEmail("testID@ab180.co");
FAirbridge::SetUserPhone("821012341234");

// Attributes
FAirbridge::SetUserAttribute("ADD_YOUR_KEY", 1);
FAirbridge::SetUserAttribute("ADD_YOUR_KEY", 1L);
FAirbridge::SetUserAttribute("ADD_YOUR_KEY", 1f);
FAirbridge::SetUserAttribute("ADD_YOUR_KEY", 1.0);
FAirbridge::SetUserAttribute("ADD_YOUR_KEY", "1");
FAirbridge::SetUserAttribute("ADD_YOUR_KEY", true);
FAirbridge::RemoveUserAttribute("DELETE_THIS_KEY");
FAirbridge::ClearUserAttributes();

用户属性哈希处理

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

用户信息重置

您可以使用 FAirbridge::ClearUser 函数重置用户信息。

提示

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

高级设置

提示

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

仅收集 Airbridge 深度链接

通过 Airbridge Unreal SDK 的 FAirbridge::SetOnDeeplinkReceived 方法接收的深度链接，不仅包括 Airbridge 深度链接，还可能包括其他解决方案的深度链接或自定义深度链接。

ExampleGameModeBase.cpp
1234567891011121314
...
#include "AirbridgeUnreal.h"

void AExampleGameModeBase::BeginPlay()
{
    ...
    
    FAirbridge::SetOnDeeplinkReceived([](const FString& Url)
    {
        // show proper content using url
    });

    ...
}

您可以通过将 SDK 设置 的 Is Handle Airbridge Deeplink Only 设置为 true，使 OnDeeplinkReceived 回调仅传递 Airbridge 深度链接。

在 App 中使用追踪链接

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

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

注意

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

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

归因结果（Attribution Result）使用

注意

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

您可以使用 FAirbridge::SetOnAttributionReceived 函数收取安装事件的归因结果数据。

123456
static void OnReceived(TMap<FString, FString> Attribution) {  }

void SomeFunction() 
{ 
    FAirbridge::SetOnAttributionReceived(OnReceived);
}

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

推送通知深度链接收集

注意

请使用自定义 iOS AppDelegate 来应用下方代码。

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

iOS

请将以下代码添加至自定义 AppDelegate。

123456789101112131415161718192021222324252627282930
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <Airbridge/Airbridge.h>
#import <UserNotifications/UserNotifications.h>

@interface SomeAppDelegate : NSObject <UIApplicationDelegate, UNUserNotificationCenterDelegate>

@end

@implementation SomeAppDelegate

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    UIApplicationState state = UIApplication.sharedApplication.applicationState;
    if (state == UIApplicationStateInactive) {
        NSURL *url = // 푸시 알림 페이로드의 딥링크
        
        Airbridge.trackDeeplink(url)
    }
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    UIApplicationState state = UIApplication.sharedApplication.applicationState;
    if ((state == UIApplicationStateInactive || state == UIApplicationStateBackground)
        && [response.actionIdentifier isEqualToString:UNNotificationDefaultActionIdentifier]) {
        NSURL *url = // 푸시 알림 페이로드의 딥링크
        
        Airbridge.trackDeeplink(url)
    }
}

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

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

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

您可以通过将 SDK 设置 的 Track In Session Life Cycle Event Enabled 设置为 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 设置 的 Auto Start Tracking Enabled 设置为 false。

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

注意

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

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

Unreal - Set Device Alias
1234567891011
// Set device alias into Airbridge SDK

// Based on actual region
FAirbridge::SetDeviceAlias("eea", "0" /* or "1" */);

// Based on actual user consent
FAirbridge::SetDeviceAlias("adPersonalization", "0" /* or "1" */);
FAirbridge::SetDeviceAlias("adUserData", "0" /* or "1" */);

// Explicitly start tracking
FAirbridge::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）。

2. 请将 SDK 设置 的 Facebook Deferred App Link Enabled 设置为 true。

在禁用状态下初始化 Airbridge SDK

注意

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

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

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

123
FAirbridge::IsSDKEnabled();
FAirbridge::EnableSDK();
FAirbridge::DisableSDK();

Meta Install Referrer (MIR) 收集设置

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

完成设置后，需要将 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 设置 的 Log Level，可以查看从该日志级别到 Fault 级别的所有日志。

位置信息收集

您可以将 SDK 设置 的 Location Collection Enabled 设置为 true，以收集用户的位置信息。

注意

位置信息必须以合法目的和方式收集，使用此功能请谨慎。

此功能仅在 Android 上可用，且 Android App Manifest（Assets/Plugins/Android/AndroidManifest.xml）中必须包含以下权限：

1234
// Choose one
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
...

注意

Airbridge SDK 收集 LastKnownLocation 信息。如果未获取 GPS 信息，即使有适当的权限和设置也可能不存在任何值。

应用商店流量监测

如果希望监测各应用商店（例：Google Play Store、One Store、Huawei Store、Galaxy Store）的 App 安装数量，可以通过以下方法为发布在各应用商店的 App 设置标识符，以便在 Airbridge 面板中查看各应用商店的 App 安装数量。此功能仅适用于 Android。

请在 SDK 设置 的 App Market Identifier 字段中，输入应用商店的名称（如 playStore、oneStore、huaweiStore、galaxyStore）。

App 处于后台时停止发送事件

您可以将 SDK 设置 的 Pause Event Transmit On Background Enabled 设置为 true，以在 App 处于后台时停止事件发送。

Was this page helpful?

Have any questions or suggestions?