Developer Guide
DeepLink Plan
Android SDK (v4)

DeepLink Plan - Android SDK (v4)

Last updated 2 days ago

本指南介绍如何安装 Airbridge Android SDK 并进行必要的配置。

Android SDK 安装

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

1. 在 Project build.gradle 文件的 repositories 块中声明 Airbridge maven 仓库。

12345
allprojects {
    repositories {
        maven { url "https://sdk-download.airbridge.io/maven" }
    }
}

2. 在 Application 的 gradle 文件中，添加 Airbridge Android SDK 包。

123456
dependencies {
    // Get the latest version from https://sdk-download.airbridge.io/maven
    implementation "io.airbridge:sdk-android:HERE_LATEST_VERSION"
    // For example
    // implementation "io.airbridge:sdk-android:0.0.0"
}

123456
dependencies {
    // Get the latest version from https://sdk-download.airbridge.io/maven
    implementation("io.airbridge:sdk-android:HERE_LATEST_VERSION")
    // For example
    // implementation("io.airbridge:sdk-android:0.0.0")
}

提示
Airbridge Android SDK 需要 1.4 及以上版本的 Kotlin stdlib 和 Kotlinx coroutines 库。

Airbridge Android SDK 同时使用 JetBrains 的 Kotlin 和 Coroutines 库。

如果使用 .aar 手动安装 SDK，需要将以下 Dependency 库添加到 Project 中：

库	链接
Airbridge SDK	下载
JetBrains Java Annotations	下载
Kotlin Standard Library	下载
Kotlinx Coroutines Core	下载
Kotlinx Coroutines Android	下载
Play Services Appset	下载

Restricted SDK

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

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

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

1. 在 Project build.gradle 文件的 repositories 块中声明 Airbridge maven 仓库。

12345
allprojects {
    repositories {
        maven { url "https://sdk-download.airbridge.io/maven" }
    }
}

2. 在 Application 的 gradle 文件中，添加 Airbridge Android SDK 包。

123456
dependencies {
    // Get the latest version from https://sdk-download.airbridge.io/maven
    implementation "io.airbridge:sdk-android-restricted:HERE_LATEST_VERSION"
    // For example
    // implementation "io.airbridge:sdk-android-restricted:0.0.0"
}

123456
dependencies {
    // Get the latest version from https://sdk-download.airbridge.io/maven
    implementation("io.airbridge:sdk-android-restricted:HERE_LATEST_VERSION")
    // For example
    // implementation("io.airbridge:sdk-android-restricted:0.0.0")
}

提示
Airbridge Android SDK 需要 1.4 及以上版本的 Kotlin stdlib 和 Kotlinx coroutines 库。

Airbridge Android SDK 同时使用 JetBrains 的 Kotlin 和 Coroutines 库。

如果使用 .aar 手动安装 SDK，需要将以下 Dependency 库添加到 Project 中：

库	链接
Airbridge SDK Restricted	下载
JetBrains Java Annotations	下载
Kotlin Standard Library	下载
Kotlinx Coroutines Core	下载
Kotlinx Coroutines Android	下载
Play Services Appset	下载

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)
}

123456789
@Override
public void onCreate() {
    super.onCreate();
    // YOUR_APP_NAME: input your app name
    // YOUR_APP_SDK_TOKEN: input your app token
    AirbridgeOption option = new AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .build();
    Airbridge.initializeSDK(this, option);
}

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

5. 设置以下权限：

Airbridge Android SDK 需要通过网络传输事件的权限。

请在 Application 的 AndroidManifest.xml 添加以下权限：

123456
<manifest ...>
  ...
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  ...
</manifest>

根据 Google 政策，针对 Android 13（API 33）及以上版本的 App 必须在 AndroidManifest.xml 文件中声明 Google Play 服务的一般权限才能获取设备的广告 ID（Advertising ID，简称 ADID）。

从 2.13.0 版本起，Airbridge Android SDK 会自动添加 AD_ID 权限，以获取 ADID。

如果未设置 LAT（Limit Ad Tracking，限制广告跟踪)，但 GAID（Google Advertising ID，Google 广告 ID）显示为 00000000-0000-0000-0000-000000000000，则是由于 AD_ID 权限被第三方库等排除所致，请使用以下代码添加 AD_ID 权限以解决问题。

12345
<manifest ...>
  ...
  <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
  ...
</manifest>

深度链接 (Deep Link)

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 面板注册深度链接信息:

请前往 [追踪链接]>[深度链接] 并输入以下信息：

Android URI Scheme：根据 Android URI Scheme，将 Airbridge 深度链接转换为 URI Scheme 深度链接。App Link 和 URI Scheme 需要此信息。
Android 包名：用于识别 Android 包。App Link 和 URI Scheme 需要此信息。
Android sha256_cert_fingerprints：用于设置 App Link 域名。App Link 需要此信息。

注意
为确保正确的用户跳转，请为正式版 App 和开发用 App 注册不同的 Android URI Scheme 和 sha256_cert_fingerprints。

请按照以下步骤将上述信息注册至 Airbridge 面板。

1. 请前往 [追踪链接]>[深度链接]。

2. 请在 [Android URI Scheme] 中输入 Android URI Scheme，该 URI Scheme 必须与 :// 一起输入。例如，如果 Android URI Scheme 是 demo，则输入 demo://。

3. 请在 [Android 包名] 中输入 Android 包名。

4. 为了获取 sha256_cert_fingerprints，请在部署的 keystore 文件中运行以下命令：

1
keytool -list -v -keystore YOUR_KEYSTORE.keystore

请查看结果中的 SHA256 值。SHA256 值即是 sha256_cert_fingerprints。

1234
Certificate fingerprints:
    MD5:  4C:65:04:52:F0:3F:F8:65:08:D3:71:86:FC:EF:C3:49
    SHA1: C8:BF:B7:B8:94:EA:5D:9D:38:59:FE:99:63:ED:47:B2:D9:5A:4E:CC
    SHA256: B5:EF:4D:F9:DC:95:E6:9B:F3:9A:5E:E9:D6:E0:D8:F6:7B:AB:79:C8:78:67:34:D9:A7:01:AB:6A:86:01:0E:99

5. 请在 [sha256_cert_fingerprints] 中输入在步骤 4. 获取的 SHA256 值。

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

请按照以下步骤进行设置，以确保用户点击追踪链接后，App 能通过 Airbridge 深度链接启用。

1. 请添加处理深度链接的 Activity。将 Activity class 文件添加到 src 中。

123456789
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity

class DeeplinkActivity: AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

123456789101112
import android.os.Bundle;

import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;

public class DeeplinkActivity extends AppCompatActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    }
}

请在 AndroidManifest.xml 文件添加该 Activity。

AndroidManifest.xml

123456
<application
    ...>

    <activity android:name=".DeeplinkActivity" />

</application>

2. 为了在 App 设置 Airbridge 深度链接的 URI Scheme 深度链接，请在 AndroidManifest.xml 的处理深度链接的 Activity 中添加 Intent Filter。

添加的 Intent Filter 必须使用在 Airbridge 面板中注册的 Android URI Scheme。请输入 Android URI Scheme，不包括 ://。

123456789101112
<activity ...>
    ...
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="YOUR_SCHEME" />
    </intent-filter>
    ...
</activity>

注意
必须输入不包括 :// 的 Android URI Scheme。

3. 为了在 App 设置 Airbridge 深度链接的 App Link，请在 AndroidManifest.xml 的处理深度链接的 Activity 中添加以下 Intent Filter。

YOUR_APP_NAME 是 Airbridge App 名称。

12345678910111213141516171819202122
<activity ...>
    ...
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" android:host="YOUR_APP_NAME.abr.ge" />
        <data android:scheme="https" android:host="YOUR_APP_NAME.abr.ge" />
    </intent-filter>
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" android:host="YOUR_APP_NAME.airbridge.io" />
        <data android:scheme="https" android:host="YOUR_APP_NAME.airbridge.io" />
    </intent-filter>
    ...
</activity>

启用 Airbridge 深度链接时，处理深度链接的 Activity 会使用 Airbridge.handleDeeplink 函数将 Airbridge 深度链接转换为 URI Scheme 深度链接。

转换后的 URI Scheme 深度链接将用户发送至预设的目标页面。

12345678910111213141516171819
// when activity is opened with scheme deeplink or app links
override fun onResume() {
	super.onResume()
	
	// handle airbridge deeplink
	val isHandled = Airbridge.handleDeeplink(intent) {
		// when app is opened with airbridge deeplink
        // show proper content using url (YOUR_SCHEME://...)
	}
	if (isHandled) return

	// when app is opened with other deeplink
    // use existing logic as it is
}

override fun onNewIntent(intent: Intent?) {
	super.onNewIntent(intent)
	setIntent(intent)
}

1234567891011121314151617181920212223
// when activity is opened with scheme deeplink or app links
@Override
protected void onResume() {
    super.onResume();

    boolean isHandled = Airbridge.handleDeeplink(
                getIntent(),
                uri -> {
                    // when app is opened with airbridge deeplink
                    // show proper content using url (YOUR_SCHEME://...)
                }
        );
    if (isHandled) return;

    // when app is opened with other deeplink
    // use existing logic as it is
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
}

提示
当输入的是 Airbridge 深度链接时，Airbridge.handleDeeplink 函数会返回 true，并将转换后的 URI Scheme 深度链接传递给 onSuccess。如果输入的不是 Airbridge 深度链接，则返回 false，且不触发回调。
Airbridge.handleDeeplink 函数不会自动提供目标页面的跳转功能。请您通过传递给 Airbridge.handleDeeplink 函数的 onSuccess 的 uri，手动实现页面跳转逻辑。

延迟深度链接（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。

测试

可通过 SDK 运行测试和深度链接测试，验证 Airbridge SDK 和深度链接是否正常运行。

SDK 运行测试

App 安装事件会自动被 Android SDK 收集，无需额外设置。

检查 App 安装事件的收集

1. 准备未安装您 App 的测试设备，或在测试前删除该 App。

2. 将 SDK 日志级别设置为 DEBUG。

12345
// Default log level = Log.INFO
val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
    .setLogLevel(AirbridgeLogLevel.DEBUG)
    .build()
Airbridge.initializeSDK(this, option)

3. 在测试设备上安装 App。安装后需要启用 App，才能收集到 App 安装事件。请启用 App。

Airbridge 将首次收集的打开（Open）事件记录为安装（Install）事件。因此，如果收集到安装（Install）事件，打开（Open）事件可能不会被记录。

4. 在 Android Studio 或 Android Debug Bridge（ADB）使用 Logcat 检查测试设备的 GAID 事件日志。在 Logcat Filter 输入 tag: Airbridge。若 App 安装事件被正常收集，可在日志中查看如下信息：

Send event packets to Airbridge: categories={9161}
Send event packets to Airbridge: categories={9163}

5. 如果经过足够时间后 Logcat 仍无日志，请检查 SDK 是否已初始化、配置是否正确、以及网络状态。

如果反复无法查到 App 安装事件，请通过 [帮助] 提交请求，并附上 SDK 日志。

深度链接测试

提前准备

`#{"width":"120px"}`	`#{"width":"240px"}` 说明	`#{"width":"140px"}` 相关指南
HTTP 深度链接（App link）设置	- 必需设置。	- 面板设置 - 深度链接设置
URI Scheme 深度链接设置	- 必需设置。	- 面板设置 - 深度链接设置
延迟深度链接设置	- 自动设置，无需额外设置。	- 延迟深度链接设置
品牌域名设置	- 可选设置。	- 面板设置
App 安装	- 如果不测试延迟深度链接，请提前在测试设备上安装 App。 - 如果测试延迟深度链接，测试设备上不应安装 App。如果已安装，请提前卸载。

通过深度链接测试网站进行测试

1. 在测试设备上访问深度链接测试网站。您可以扫描下方 QR 码访问。

2. 在 App Name 栏输入在 Airbridge 面板注册的 App 名称。App 名称可在 Airbridge 面板的 [设置]>[Token] 获取。

若要测试特定深度链接地址，在 Deeplink URL 栏中输入 URI Scheme 深度链接，格式应为 {YOUR_SCHEME}://...。

如果要测试品牌域名，在 Custom Domain 栏输入品牌域名。

3. 根据所需测试的深度链接类型，点击相应的按钮。

请注意，延迟深度链接只能在测试设备未安装 App 的情况下进行测试。

`#{"width":"120px"}` 按钮	`#{"width":"240px"}` 说明	`#{"width":"140px"}` 示例
Test HTTP Deeplink Type-1	- 可以测试 `https://{your_app-name}.abr.ge` 格式的 HTTP 深度链接。	`https://{your_app-name}.abr.ge/@{your_app-name}/test_sdk?...`
Test HTTP Deeplink Type-2	- 可以测试 `https://abr.ge` 格式的 HTTP 深度链接。与 Test HTTP Deeplink Type-1 的地址格式不同。	`https://abr.ge/@{your_app-name}/test_sdk?...`
Test Scheme Deeplink	- 可以测试 URI Scheme 深度链接。	`https://abr.ge/@{your_app-name}/test_sdk?...`
Test Deferred Deeplink	- 可以测试延迟深度链接。	`https://abr.ge/@{your_app-name}/test_sdk?...`
Test Custom Domain Deeplink	- 仅在输入品牌域名时可用。 - 可以测试品牌域名。	`https://{your_custom_domain}/@{your_app-name}/test_sdk?...`

4. 在 Android Studio 或 Android Debug Bridge（ADB）使用 Logcat 检查测试设备的 GAID 事件日志。在 Logcat Filter 输入 tag: Airbridge。若深度链接事件被正常收集，可在日志中查看如下信息：

Send event packets to Airbridge: categories={9162}
Send event packets to Airbridge: categories={9163}
Send event packets to Airbridge: categories={9168}

如果在 Airbridge SDK 初始化过程中将日志级别设置为 DEBUG，则可查看通过网络传输的数据。

5. 通过 Client request: method={...} 消息发送 header 和 body 值。根据您点击的按钮，进一步检查以下项目。如果深度链接正常运行，所有项目都应符合。

6. 如果经过足够时间后 Logcat 仍无日志，请检查 SDK 是否已初始化、配置是否正确、以及网络状态。

如果反复无法查到深度链接事件，请通过 [帮助] 提交请求，并附上 SDK 日志。

问题排查

问题	解决方法
点击深度链接后，App 未启用，或 SDK 日志显示的内容与设置不符。	请参考深度链接设置，检查深度链接设置是否正确。
点击深度链接后，App 已启用，但未跳转至设定的 App 页面。	您需要手动实现，使用户能够根据传递给 `onSuccess` 函数的深度链接路径进行跳转。请参考深度链接设置。

Was this page helpful?

Have any questions or suggestions?

DeepLink Plan - Android SDK (v4)

Android SDK 安装

Gradle

手动安装

提示

Restricted SDK

提示

Gradle

手动安装

提示

SDK 初始化

注意

必需权限

广告 ID 权限

深度链接 (Deep Link)

深度链接设置

在 Airbridge 面板注册深度链接信息

注意

使用 Airbridge 深度链接启用 App

注意

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

提示

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

Airbridge SDK 获取延迟深度链接的方法

测试

SDK 运行测试

检查 App 安装事件的收集

Logcat 消息的含义

深度链接测试

提前准备

通过深度链接测试网站进行测试

Test HTTP Deeplink

Test Scheme Deeplink

Test Deferred Deeplink

Test Custom Domain Deeplink

问题排查

DeepLink Plan - Android SDK (v4)self.__wrap_n!=1&&self.__wrap_b(":R29jtt7ppjtsba:",0.5)

Android SDK 安装

Gradle

手动安装

提示

Restricted SDK

提示

Gradle

手动安装

提示

SDK 初始化

注意

必需权限

广告 ID 权限

深度链接 (Deep Link)

深度链接设置

在 Airbridge 面板注册深度链接信息

注意

使用 Airbridge 深度链接启用 App

注意

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

提示

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

Airbridge SDK 获取延迟深度链接的方法

测试

SDK 运行测试

检查 App 安装事件的收集

Logcat 消息的含义

深度链接测试

提前准备

通过深度链接测试网站进行测试

Test HTTP Deeplink

Test Scheme Deeplink

Test Deferred Deeplink

Test Custom Domain Deeplink

问题排查

DeepLink Plan - Android SDK (v4)