Android SDK (v4)

Maven metadata URL

提示

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

Android SDK 安装

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

Restricted SDK

提示

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

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

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

SDK 初始化

建议在 Android Application class 中初始化 Airbridge Android SDK。

1. 请创建 Application class。

12345678
import android.app.Application

class AndroidApplication: Application() {

    override fun onCreate() {
        super.onCreate()
    }
}

2. 请在 AndroidManifest.xml 中设置在步骤 1. 创建的 Application。

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

3. 请从 Application class 导入 Airbridge

1
import co.ab180.airbridge.Airbridge

4. 请在 AndroidManifest.xml 中注册的 Application class 文件中添加以下代码。

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

12345678
override fun onCreate() {
    super.onCreate()
    // YOUR_APP_NAME: input your app name
    // YOUR_APP_SDK_TOKEN: input your app token
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .build()
    Airbridge.initializeSDK(this, option)
}

注意

为确保正常工作,请在 Application class 的 onCreate 时调用 initializeSDK 函数。

5. 请设置以下权限:

Opt-in 设置

提示

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

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

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

1. 请在 Application class 进行初始化。请使用 setAutoStartTrackingEnabled 函数防止事件追踪在初始化后自动启用。

12345
// Default Auto Start Tracking Enabled = true
val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
    .setAutoStartTrackingEnabled(false)
    .build()
Airbridge.initializeSDK(this, option)

2. 请收集用户对个人信息收集和使用的响应。如果用户同意收集和使用个人信息,则开始事件追踪。

1234
// Set a variable like below
if (properties.isGDPRAccepted) {
    Airbridge.startTracking()
}

Opt-out 设置

提示

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

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

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

123456
val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
    .setAutoStartTrackingEnabled(true)
    .build()
Airbridge.initializeSDK(this, option)
...
Airbridge.stopTracking()

SDK 签名(SDK Signature)设置

提示

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

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

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

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

1234
val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
    .setSDKSignature("YOUR_SDK_SIGNATURE_SECRET_ID", "YOUR_SDK_SIGNATURE_SECRET")
    .build()
Airbridge.initializeSDK(this, 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 签名] 中查看。

深度链接(Deep Link)

您可以通过设置深度链接,将点击包含追踪链接的广告的用户跳转至 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 面板输入深度链接信息后,请进行设置启用以下功能:

  • 使用 Airbridge 深度链接启用 App

  • 使用 Airbridge 深度链接实现用户跳转

延迟深度链接(Deferred Deep Link)设置

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

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

1234
val isHandled = Airbridge.handleDeferredDeeplink {
    // when app is opened with deferred deeplink
    // show proper content using url
}

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

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

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

应用内事件

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

应用内事件发送

Hybrid App 设置

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

请使用 trackEvent 方法发送事件。为了使用 trackEvent 方法,请导入 Airbridge。

1
import co.ab180.airbridge.Airbridge

为了使用 Airbridge 预定义的 Category 名称和 Attribute,您需要调用 AirbridgeCategoryAirbridgeAttribute

12
import co.ab180.airbridge.common.AirbridgeCategory
import co.ab180.airbridge.common.AirbridgeAttribute

trackEvent 函数构成要素的类型及其必需性如下:

12345
fun trackEvent(
    category: String,
    semanticAttributes: Map<String, Any?>? = null,
    customAttributes: Map<String, Any?>? = null
)

名称

是否必需

类型

说明

category

必需

String

事件名称

semanticAttributes

可选

Map<String, Any?>

事件标准属性

customAttributes

可选

Map<String, Any?>

事件自定义属性

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

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

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

12345678910111213
Airbridge.trackEvent(
    "event",
    mapOf(
        AirbridgeAttribute.VALUE to 10,
    ),
    mapOf(
        "string" to "string",
        "number" to 1000,
        "boolean" to true,
        "object" to mapOf("key" to "value"),
        "array" to listOf("value"),
    )
)

应用内事件其他设置

提示

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

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

应用内事件示例代码

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

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

12345678910111213
Airbridge.trackEvent(
    "event",
    mapOf(
        AirbridgeAttribute.VALUE to 10,
    ),
    mapOf(
        "string" to "string",
        "number" to 1000,
        "boolean" to true,
        "object" to ["key": "value"],
        "array" to ["value"],
    )
)

用户信息

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

用户 ID 设置

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

#{"width":"140px"}

函数

#{"width":"240px"}

说明

Airbridge.setUserID

输入用户 ID

Airbridge.clearUserID

删除用户 ID

Airbridge.setUserAlias

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

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

- 值:最多 1024 个字符

Airbridge.removeUserAlias

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

Airbridge.clearUserAlias

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

请参阅以下示例:

1234567
// ID
Airbridge.setUserID("testID")

// alias
Airbridge.setUserAlias("ADD_YOUR_KEY", "value")
Airbridge.removeUserAlias("DELETE_THIS_KEY")
Airbridge.clearUserAlias()

用户属性设置

注意

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

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

#{"width":"140px"}

函数

#{"width":"240px"}

说明

Airbridge.setUserEmail

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

Airbridge.clearUserEmail

删除用户邮箱

Airbridge.setUserPhone

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

Airbridge.clearUserPhone

删除用户电话号码

Airbridge.setUserAttribute

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

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

- 值:仅支持 String、Number、Boolean 类型,最多 1024 个字符

Airbridge.removeUserAttribute

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

Airbridge.clearUserAttributes

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

请参阅以下示例:

1234567891011121314
// Automatically hashed on client side using SHA256
// Can turn off hashing feature with special flag
Airbridge.setUserEmail("testID@ab180.co")
Airbridge.setUserPhone("821012341234")

// attributes
Airbridge.setUserAttribute("ADD_YOUR_KEY", 1)
Airbridge.setUserAttribute("ADD_YOUR_KEY", 1L)
Airbridge.setUserAttribute("ADD_YOUR_KEY", 1f)
Airbridge.setUserAttribute("ADD_YOUR_KEY", 1.0)
Airbridge.setUserAttribute("ADD_YOUR_KEY", "1")
Airbridge.setUserAttribute("ADD_YOUR_KEY", true)
Airbridge.removeUserAttribute("DELETE_THIS_KEY")
Airbridge.clearUserAttributes()

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

12345
// Default User Info Hash Enabled = true
val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
    .setHashUserInformationEnabled(false)
    .build()
Airbridge.initializeSDK(this, option)

用户信息重置

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

1
Airbridge.clearUser()

高级设置

提示

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

在 App 中使用追踪链接

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

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

注意

如果在 Airbridge Android SDK 2.18.0 及以上版本设置 “在 App 中使用追踪链接” 功能,每次在 App 内使用追踪链接时会记录深度链接页面浏览(Deeplink Pageview)作为 目标事件。如果深度链接页面浏览频繁随深度链接打开(Deeplink Open)发生,可能会影响深度链接打开的绩效。

深度链接页面浏览的默认归因窗口为 3 天。如果希望更改此归因窗口,请联系您的 Airbridge CSM。如果没有指定的 CSM,请通过 [帮助] 提交请求。

归因结果(Attribution Result)使用设置

注意

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

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

12345678
val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
	.setOnAttributionReceived(object : OnAttributionResultReceiveListener {
		override fun onAttributionResultReceived(result: Map<String, String>) {
			// Process attribution data
		}
	})
	.build()
Airbridge.initializeSDK(application, option)

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