Developer Guide
SDK 集成
Flutter SDK (v4)

故障排除 - Flutter SDK (v4)

Last updated February 21, 2025

iOS

问题现象

使用 Password AutoFill 功能时，存储的密码域名可能会向 App 用户显示为 airbridge.io 或 abr.ge。

发生原因

在 Airbridge SDK 设置深度链接后，如果使用 Password AutoFill 功能，密码域名将被存储为 Airbridge 深度链接的 App Link 域名，即 airbridge.io 或 abr.ge。

解决方法

可通过设置 Password AutoFill 使用的 Webcredentials 域名来解决该问题：

1. 请准备用于存储密码的域名（YOUR_DOMAIN）。

2. 请将以下 JSON 托管至 https://YOUR_DOMAIN/.well-known/apple-app-site-association，并确保 Content-Type: application/json。

App ID Prefix 和 Bundle ID 可在 Apple Developer 的 [Identifiers]>[YOUR_APP] 获取。

12345
{
    "webcredentials": {
        "apps": ["YOUR_APP_ID_PREFIX.YOUR_BUNDLE_ID"]
    }
}

3. 请在 Xcode 导航至 [YOUR_PROJECT]>[Signing & Capabilities]。

4. 请点击 “+ Capability” 以添加 Associated Domains。请将 webcredentials:YOUR_DOMAIN 输入至 Associated Domains。

Android

问题现象

在构建时，会出现 Dependencies coroutines 错误，并显示以下消息：

Text

1234
java.lang.NoClassDefFoundError: kotlin/coroutines/AbstractCoroutineContextKey
    at java.base/java.lang.ClassLoader.defineClass1(Native Method)
    at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1016)
  ...

发生原因

如果 kotlinx-coroutines-core 库的版本为 v1.3.5 或以上，则 kotlin-stdlib 库的版本必须满足一定的最低要求。

解决方法

请使用 gradlew dependencies 命令检查 kotlin-stdlib 库的版本是否为 v1.3.70 或以上。如果版本低于该要求，请进行更新。

问题现象

使用 Braze SDK 发送的推送通知触发的深度链接打开（Deeplink Open）事件未被收集，而是收集到打开（Open）事件。

发生原因

Airbridge Android SDK 通过 activity 的 action 中的 dataString 和 intent 的 dataString 区分深度链接打开事件和打开事件。

当使用 Braze SDK 发送的推送通知打开 App 时，会使用 NotificationTrampolineActivity。由于无法从 NotificationTrampolineActivity 的 activity 的 action 和 intent 中获取 dataString，因此 Airbridge Android SDK 无法正确区分深度链接打开事件和打开事件。

解决方法

1234567
import co.ab180.airbridge.flutter.AirbridgeFlutter
...
AirbridgeFlutter.setLifecycleIntegration { activity ->
    return@setLifecycleIntegration activity
        .takeIf { it.javaClass.name == "com.braze.push.NotificationTrampolineActivity" }
        ?.run { intent?.extras?.getString("uri") }
}

1234567891011121314151617
import co.ab180.airbridge.flutter.AirbridgeFlutter;
import co.ab180.airbridge.flutter.common.AirbridgeLifecycleIntegration;
...
AirbridgeFlutter.setLifecycleIntegration(new AirbridgeLifecycleIntegration() {
    @Nullable
    @Override
    public String getDataString(@NonNull Activity activity) {
        if (
            activity.getClass().getName().equals("com.braze.push.NotificationTrampolineActivity")
            && activity.getIntent() != null
            && activity.getIntent().getExtras() != null
        ) {
            return activity.getIntent().getExtras().getString("uri");
        }
        return null;
    }
});

问题现象

在构建时，会出现 Manifest merger failed 错误。

发生原因

Airbridge SDK 的 AndroidManifest.xml 中包含用于禁用共享环境设置数据备份的规则。该规则的目的是防止在重新安装 App 时保留相同的 Airbridge 配置值，以便准确检测新安装或重新安装。

在合并 Airbridge SDK 备份规则和 App 自身的备份规则时，可能会发生冲突。

解决方法

Airbridge SDK 定义的禁用备份规则如下：

123456789101112131415161718192021
<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        <exclude domain="sharedpref" path="airbridge-internal" />
        <exclude domain="sharedpref" path="airbridge-install" />
        <exclude domain="sharedpref" path="airbridge-user-info" />
        <exclude domain="sharedpref" path="airbridge-user-alias" />
        <exclude domain="sharedpref" path="airbridge-user-attributes" />
        <exclude domain="sharedpref" path="airbridge-device-alias" />
        <exclude domain="database" path="airbridge.db" />
    </cloud-backup>
    <device-transfer>
        <exclude domain="sharedpref" path="airbridge-internal" />
        <exclude domain="sharedpref" path="airbridge-install" />
        <exclude domain="sharedpref" path="airbridge-user-info" />
        <exclude domain="sharedpref" path="airbridge-user-alias" />
        <exclude domain="sharedpref" path="airbridge-user-attributes" />
        <exclude domain="sharedpref" path="airbridge-device-alias" />
        <exclude domain="database" path="airbridge.db" />
    </device-transfer>
</data-extraction-rules>

12345678910
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <exclude domain="sharedpref" path="airbridge-internal" />
    <exclude domain="sharedpref" path="airbridge-install" />
    <exclude domain="sharedpref" path="airbridge-user-info" />
    <exclude domain="sharedpref" path="airbridge-user-alias" />
    <exclude domain="sharedpref" path="airbridge-user-attributes" />
    <exclude domain="sharedpref" path="airbridge-device-alias" />
    <exclude domain="database" path="airbridge.db" />
</full-backup-content>

解决与 fullBackupContent="string" 的冲突

如果在 AndroidManifest.xml 中添加了 android:fullBackupContent="string"，可能会出现以下错误：

Build Output

1
Manifest merger failed : Attribute application@fullBackupContent value=(string) from AndroidManifest.xml

为了解决该错误，请在 AndroidManifest.xml 文件中：

在 <manifest> 标签中添加 xmlns:tools="http://schemas.android.com/tools"
在 <application> 标签中添加 tools:replace="android:fullBackupContent"

解决与 dataExtractionRules="string resource" 的冲突

如果在 AndroidManifest.xml 中添加了 android:dataExtractionRules="string resource"，可能会出现以下错误：

Build Output

12
Manifest merger failed : Attribute application@dataExtractionRules value=(string resource) from AndroidManifest.xml

为了解决该错误，请在 AndroidManifest.xml 文件中：

在 <manifest> 标签中添加 xmlns:tools="http://schemas.android.com/tools"
在 <application> 标签中添加 tools:replace="android:dataExtractionRules"

解决与 allowBackup="false" 的冲突

如果在 AndroidManifest.xml 中添加了 android:allowBackup="false"，可能会出现以下错误：

Build Output

123
Manifest merger failed : Attribute application@allowBackup value=(false) from AndroidManifest.xml:32:9-36
	is also present at [:airbridge] AndroidManifest.xml:27:9-35 value=(true).
	Suggestion: add 'tools:replace="android:allowBackup"' to <application> element at AndroidManifest.xml:30:5-250:19 to override.

为了解决该错误，请在 AndroidManifest.xml 文件中：

在 <manifest> 标签中添加 xmlns:tools="http://schemas.android.com/tools"
在 <application> 标签中添加 tools:replace="android:allowBackup"

compileSdkVersion 低于 31 时的错误

android:dataExtractionRules 功能从 API Level 31 开始支持，因此如果 compileSdkVersion 低于 31，可能会出现以下错误：

Build Output

1
AndroidManifest.xml: AAPT: error: attribute android:dataExtractionRules not found.

为了解决该错误，请在 AndroidManifest.xml 文件中：

在 <manifest> 标签中添加 xmlns:tools="http://schemas.android.com/tools"
在 <application> 标签中添加 tools:remove="android:dataExtractionRules"

请参阅以下指南获取更多信息：

问题现象

当 Airbridge SDK 备份规则与其他第三方 SDK（例如 AppsFlyer SDK）的备份规则发生重复应用时，可能会出现以下构建错误：

123
Attribute application@fullBackupContent value=(@xml/appsflyer_backup_rules) from [com.appsflyer:af-android-sdk:6.6.1] AndroidManifest.xml:14:18-73
is also present at [io.airbridge:sdk-android:2.14.0] AndroidManifest.xml:27:18-78 value=(@xml/airbridge_auto_backup_rules).
Suggestion: add 'tools:replace="android:fullBackupContent"' to <application> element at AndroidManifest.xml:7:5-13:19 to override.

发生原因

由于 Airbridge SDK 备份规则与第三方 SDK 备份规则同时应用，可能会导致构建错误。

解决方法

配置 `backup_rules.xml`

请创建 android/app/src/main/res/xml 文件夹。
请在该 xml 文件夹内创建文件，例如 custom_backup_rules.xml。
请在该文件中，添加 Airbridge SDK 定义的数据备份规则，如下所示：

12345678910111213141516
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- Airbridge Backup Rules -->
    <exclude domain="sharedpref" path="airbridge-internal" />
    <exclude domain="sharedpref" path="airbridge-install" />
    <exclude domain="sharedpref" path="airbridge-user-info" />
    <exclude domain="sharedpref" path="airbridge-user-alias" />
    <exclude domain="sharedpref" path="airbridge-user-attributes" />
    <exclude domain="sharedpref" path="airbridge-device-alias" />
    <exclude domain="database" path="airbridge.db" />
  
    <!-- Appsflyer Backup Rules -->
    <exclude domain="sharedpref" path="appsflyer-data"/>
	
	<!-- Your Custom Backup Rules -->
</full-backup-content>

配置 `data_extraction_rules.xml`

提示
data_extraction_rules.xml 配置仅适用于 Airbridge Flutter SDK v4.1.5 及以上。

请在 xml 文件夹内创建文件，例如 custom_data_extraction_rule.xml。
请在该文件中，添加 Airbridge SDK 定义的数据备份规则，如下所示：

123456789101112131415161718192021222324252627282930313233
<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        <!-- Airbridge Backup Rules -->
        <exclude domain="sharedpref" path="airbridge-internal" />
        <exclude domain="sharedpref" path="airbridge-install" />
        <exclude domain="sharedpref" path="airbridge-user-info" />
        <exclude domain="sharedpref" path="airbridge-user-alias" />
        <exclude domain="sharedpref" path="airbridge-user-attributes" />
        <exclude domain="sharedpref" path="airbridge-device-alias" />
        <exclude domain="database" path="airbridge.db" />

        <!-- Appsflyer Backup Rules -->
        <exclude domain="sharedpref" path="appsflyer-data"/>

	    <!-- Your Custom Backup Rules -->
    </cloud-backup>
    <device-transfer>
        <!-- Airbridge Backup Rules -->
        <exclude domain="sharedpref" path="airbridge-internal" />
        <exclude domain="sharedpref" path="airbridge-install" />
        <exclude domain="sharedpref" path="airbridge-user-info" />
        <exclude domain="sharedpref" path="airbridge-user-alias" />
        <exclude domain="sharedpref" path="airbridge-user-attributes" />
        <exclude domain="sharedpref" path="airbridge-device-alias" />
        <exclude domain="database" path="airbridge.db" />

        <!-- Appsflyer Backup Rules -->
        <exclude domain="sharedpref" path="appsflyer-data"/>

	    <!-- Your Custom Backup Rules -->
    </device-transfer>
</data-extraction-rules>

配置 `AndroidManifest.xml`

Airbridge Flutter SDK v4.1.5 及以上

12345678910
<manifest
    ...
    xmlns:tools="http://schemas.android.com/tools">

    <application
        ...
		android:allowBackup="true"
		android:fullBackupContent="@xml/custom_backup_rules"
        android:dataExtractionRules="@xml/custom_data_extraction_rules"
		tools:replace="android:fullBackupContent, android:dataExtractionRules">

Airbridge Flutter SDK v4.1.5 以下

123456789
<manifest
    ...
    xmlns:tools="http://schemas.android.com/tools">

    <application
        ...
		android:allowBackup="true"
		android:fullBackupContent="@xml/custom_backup_rules"
		tools:replace="android:fullBackupContent">

问题现象

在 LAT（Limit Ad Tracking，限制广告跟踪）已关闭的的情况下，GAID（Google Advertising ID，Google 广告 ID）应该被正常收集，但实际被收集为 00000000-0000-0000-0000-000000000000。

发生原因

由于第三方库等的影响，AD_ID 权限被移除，导致 GAID 收集异常。

解决方法

请添加 AD_ID 权限：

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

Was this helpful?

Any questions or suggestions?

故障排除 - Flutter SDK (v4)

iOS

存储的密码域名显示为 airbridge.io 或 abr.ge 的问题

问题现象

发生原因

解决方法

Android

构建时出现 Dependencies coroutines 错误

问题现象

发生原因

解决方法

使用 Braze SDK 发送的推送通知触发的深度链接打开事件未被收集

问题现象

发生原因

解决方法

构建时出现 Manifest merger failed 错误

问题现象

发生原因

解决方法

解决与 fullBackupContent="string" 的冲突

解决与 dataExtractionRules="string resource" 的冲突

解决与 allowBackup="false" 的冲突

compileSdkVersion 低于 31 时的错误

Airbridge SDK 备份规则合并冲突问题

问题现象

发生原因

解决方法

配置 `backup_rules.xml`

配置 `data_extraction_rules.xml`

提示

配置 `AndroidManifest.xml`

Airbridge Flutter SDK v4.1.5 及以上

Airbridge Flutter SDK v4.1.5 以下

GAID 被收集为 00000000-0000-0000-0000-000000000000

问题现象

发生原因

解决方法

故障排除 - Flutter SDK (v4)self.__wrap_n!=1&&self.__wrap_b(":Ricvf9tpkvecq:",0.5)

iOS

存储的密码域名显示为 airbridge.io 或 abr.ge 的问题

问题现象

发生原因

解决方法

Android

构建时出现 Dependencies coroutines 错误

问题现象

发生原因

解决方法

使用 Braze SDK 发送的推送通知触发的深度链接打开事件未被收集

问题现象

发生原因

解决方法

构建时出现 Manifest merger failed 错误

问题现象

发生原因

解决方法

解决与 fullBackupContent="string" 的冲突

解决与 dataExtractionRules="string resource" 的冲突

解决与 allowBackup="false" 的冲突

compileSdkVersion 低于 31 时的错误

Airbridge SDK 备份规则合并冲突问题

问题现象

发生原因

解决方法

配置 backup_rules.xml

配置 data_extraction_rules.xml

提示

配置 AndroidManifest.xml

Airbridge Flutter SDK v4.1.5 及以上

Airbridge Flutter SDK v4.1.5 以下

GAID 被收集为 00000000-0000-0000-0000-000000000000

问题现象

发生原因

解决方法

故障排除 - Flutter SDK (v4)

配置 `backup_rules.xml`

配置 `data_extraction_rules.xml`

配置 `AndroidManifest.xml`