创建支持免安装体验的 app bundle

如需打造 Google Play 免安装体验，您需要将其添加到 Android App Bundle 中。这类软件包称为免安装的 app bundle。本文档介绍如何针对免安装的 app bundle 设置开发环境，以及如何配置、构建、测试和发布免安装的 app bundle。

如果您已经有免安装应用项目，但它使用的是已弃用的功能插件 (com.android.feature)，您可以了解如何迁移您的免安装应用以支持 Android App Bundle。

注意：为了发布 app bundle，您必须选择启用 Play 应用签名功能。

设置开发环境

如需在 app bundle 中提供免安装体验，您需要使用 Google Play 免安装体验开发 SDK。您可以通过以下某种方式安装该 SDK：

• 安装 Android Studio 3.6 或更高版本。打开 Android Studio，然后从 SDK 管理器的 SDK Tools 标签页下载 Google Play 免安装体验开发 SDK。

• 从命令行安装：

  cd path/to/android/sdk/tools/bin && \
    ./sdkmanager 'extras;google;instantapps'
  

此外，如果您想在本地测试免安装体验，可以使用物理或虚拟设备。

了解所需的执行条件

为了提高安全性，Google Play 免安装体验在一种特殊的 SELinux 沙盒中运行免安装的 app bundle。此沙盒只允许部分权限，与其他应用的交互类型也存在限制。以下部分详细介绍了此沙盒的特征。

支持的权限和操作

免安装的 app bundle 只能使用以下列表中的权限：

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION
• ACCESS_NETWORK_STATE
• BILLING - 自 Play 结算库 1.0 起已弃用。
• CAMERA
• INSTANT_APP_FOREGROUND_SERVICE - 仅在 Android 8.0（API 级别 26）及更高版本中提供。
• INTERNET
• READ_PHONE_NUMBERS - 仅在 Android 8.0（API 级别 26）及更高版本中提供。
• RECORD_AUDIO
• VIBRATE
• WAKE_LOCK

处理常见不受支持的权限

下面列出了您必须从应用中移除的常见不受支持的权限，并给出了每项权限的建议迁移路径：

• ACCESS_WIFI_STATE：使用 ACCESS_NETWORK_STATE，它应该能提供类似于 ACCESS_WIFI_STATE 的信息。
• BILLING：这是已弃用的权限。使用不再需要 com.android.vending.BILLING 权限的 Google Play 结算库。
• READ/WRITE_EXTERNAL_STORAGE：免安装应用无权访问外部存储空间；请改用内部存储空间。
• com.google.android.c2dm.permission.RECEIVE 和 permission.C2D_MESSAGE：C2DM 已弃用。迁移到 Firebase 云消息传递 (FCM)。FCM 无需任何其他权限即可运行。

此外，免安装的 app bundle 无法执行以下操作：

• 使用后台服务。
• 在后台运行时发送通知。

访问安装式应用

开发免安装体验时请注意，除非满足以下某种条件，否则该体验将无法与设备上的安装式应用互动：

• 安装式应用中的一个或多个 Activity 将其 android:visibleToInstantApps 元素设为 true - 此元素适用于在 Android 8.0（API 级别 26）或更高版本上运行的应用。
• 安装式应用包含具有 CATEGORY_BROWSABLE 的 intent 过滤器。
• 免安装体验使用 ACTION_SEND、ACTION_SENDTO 或 ACTION_SEND_MULTIPLE 操作发送 intent。

针对免安装体验配置您的项目

为了与 Google Play 免安装体验兼容，您必须在多个方面对免安装 app bundle 进行适当的配置。下面几节将介绍这些注意事项。

声明项目依赖项

如需在您的应用中使用 Google Play 免安装体验 API，请在应用模块的 build.gradle 配置文件中添加以下声明：

Groovy

implementation "com.google.android.gms:play-services-instantapps:17.0.0"

Kotlin

implementation("com.google.android.gms:play-services-instantapps:17.0.0")

定义正确的版本号

应用的免安装体验版本号必须低于安装式应用的版本号。我们希望用户在用过 Google Play 免安装体验后在自己的设备上下载并安装应用。Android 框架将这一过渡视为应用更新。

注意：如果用户在其设备上安装了您的应用版本，将会始终运行所安装的版本，而不会运行免安装体验版本。即使安装的版本是您应用的旧版本，也不会运行免安装体验版本。

为确保遵循此版本控制方案，请遵循以下策略之一：

• 从头开始重新设置 Google Play 免安装体验的版本号。
• 将安装式 APK 的版本号提高一个较大的数值（如 1000），以确保有足够的空间来提高免安装体验的版本号。

您可以在两个单独的 Android Studio 项目中开发您的免安装应用和安装式应用。但是，如果您这样做，必须执行以下操作才能在 Google Play 上发布您的应用：

1. 在两个 Android Studio 项目中使用相同的软件包名称。
2. 在 Google Play 管理中心将两个变体上传到同一应用。

注意：版本号不是面向用户的值，主要由系统使用。面向用户的版本名称没有限制。

如需详细了解如何设置应用版本，请参阅控制应用版本。

更新目标沙盒版本

您需要先更新免安装应用的 AndroidManifest.xml 文件，然后才能将 Google Play 免安装体验支持的沙盒环境作为目标平台。您可以通过将 android:targetSandboxVersion 属性添加到应用的 <manifest> 元素来完成此更新，如以下代码段所示：

<manifest
   xmlns:android="http://schemas.android.com/apk/res/android"
  ...
   android:targetSandboxVersion="2" ...>

如需了解详情，请参阅 targetSandboxVersion 属性文档。

声明免安装的应用模块

您可以通过以下某种方式声明 app bundle 支持免安装体验：

• 如果您现有的 app bundle 只包含基础模块，可以按照以下步骤为 app bundle 启用免安装体验：

  1. 从菜单栏中依次选择 View > Tool Windows > Project，打开 Project 面板。
  2. 右键点击基础模块（通常名为 'app'），然后依次选择 Refactor > Enable Instant Apps Support。
  3. 在出现的对话框中，从下拉菜单中选择基础模块。
  4. 点击 OK。

  Android Studio 会在模块的清单中添加以下声明：

  <manifest ... xmlns:dist="http://schemas.android.com/apk/distribution">
      <dist:module dist:instant="true" />
      ...
  </manifest>
  

  注意 ：默认情况下，app bundle 的基础模块称为 app。

• 如果您的现有 app bundle 包含多个模块，您可以创建免安装的功能模块。此过程还会使应用的基础模块支持免安装体验，让您可以选择在应用内支持多个免安装入口点。

注意：给定模块可以包含多个 Activity。如需使 app bundle 能够支持免安装体验，所有免安装的模块内的代码和资源的总下载大小不得超过 15 MB。

添加对登录的支持

如果您的免安装体验允许用户登录，免安装的 app bundle 必须支持 Android 的 Smart Lock（密码专用）功能。如果您要开发“免安装 Play”游戏，应改用 Google Play 游戏服务登录。

支持执行环境

为了与运行免安装体验的 SELinux 沙盒兼容，请在创建免安装的 app bundle 时注意以下事项：

• 请勿共享 myUid() 的值，该值是应用进程的内核分配 UID。
• 如果您的应用以 Android 8.1（API 级别 27）或更低版本为目标平台，请创建网络安全配置文件，并将 cleartextTrafficPermitted 设为 false。免安装体验不支持 HTTP 流量。对于以 Android 9 或更高版本为目标平台的应用，明文流量默认处于停用状态。

• 已下载的免安装体验仍会保留在用户的设备上，直到免安装体验缓存被清除。系统会在出现以下情况时执行清除操作：

  • 由于设备的可用内存不足，系统会对免安装体验缓存进行垃圾回收。
  • 用户重启设备。

  如果出现上述任一情况，用户必须重新下载免安装体验才能与之互动。

• 如果系统运行所用的存储空间很少，可能会将免安装体验的用户数据从内部存储空间中移除。因此，建议您定期将用户数据与应用服务器进行同步，以保留用户的进度。

添加免安装体验工作流的逻辑

将 app bundle 配置为支持免安装体验后，您可以添加以下各部分中所示的逻辑。

检查应用是否运行免安装体验

如果应用的某些逻辑取决于用户是否参与了免安装体验，请调用 isInstantApp() 方法。如果当前正在运行的进程是免安装体验，此方法会返回 true。

显示安装提示

如果您要构建试用版应用或游戏，Google Play 免安装体验会在您的免安装体验中显示提示，邀请用户在其设备上安装完整的体验版本。如需显示此提示，请使用 InstantApps.showInstallPrompt() 方法，如以下代码段所示：

Kotlin

class MyInstantExperienceActivity : AppCompatActivity {
    // ...
    private fun showInstallPrompt() {
        val postInstall = Intent(Intent.ACTION_MAIN)
                .addCategory(Intent.CATEGORY_DEFAULT)
                .setPackage(your-installed-experience-package-name)

        // The request code is passed to startActivityForResult().
        InstantApps.showInstallPrompt(this@MyInstantExperienceActivity,
                postInstall, request-code, /* referrer= */ null)
    }
}

Java

public class MyInstantExperienceActivity extends AppCompatActivity {
    // ...
    private void showInstallPrompt() {
        Intent postInstall = new Intent(Intent.ACTION_MAIN)
                .addCategory(Intent.CATEGORY_DEFAULT)
                .setPackage(your-installed-experience-package-name);

        // The request code is passed to startActivityForResult().
        InstantApps.showInstallPrompt(MyInstantExperienceActivity.this,
                postInstall, request-code, /* referrer= */ null);
    }
}

将数据转移到安装式体验

如果用户喜欢您的免安装体验，他们可能会决定安装您的应用。为了提供良好的用户体验，请务必将用户的数据从您的免安装体验转移到完整版应用中。

如果用户使用的是搭载 Android 8.0（API 级别 26）或更高版本的设备，并且您的应用将 targetSandboxVersion 指定为 2，用户的数据会自动转移到完整版应用中。否则，您必须手动转移数据。如需实现此操作，请使用以下某个 API：

• 对于使用搭载 Android 8.0（API 级别 26）或更高版本的设备的用户，请使用 Cookie API - 应用示例
• 如果用户可以在搭载 Android 7.1（API 级别 25）及更低版本的设备上与您的体验互动，请添加对 Storage API 的支持 - 应用示例

构建 app bundle

您可以使用 Android Studio 或命令行界面来构建免安装的 app bundle。

Android Studio

使用 Android Studio，您可以依次选择 Build > Build Bundle(s) / APK(s) > Build Bundle(s) 来构建 app bundle。如需详细了解如何构建项目，请参阅构建您的项目。

命令行界面

您还可以从命令行构建 app bundle 完整代码。

支持 64 位架构

在 Google Play 上发布的应用必须支持 64 位架构。添加 64 位的应用版本不仅可以提升性能，还能针对仅支持 64 位架构的设备做好准备。详细了解 64 位支持。

测试免安装体验

在发布免安装 app bundle 之前，您可以从以下任一位置测试免安装体验，以验证其能否正常运行：

• 通过 Android Studio 将其安装到本地设备上。
• 通过命令行界面将其安装到本地设备上。
• 将其发布到 Google Play 管理中心的内部测试轨道上。

。

注意： 免安装体验仅适用于搭载 Android 8.0 (API) 的设备 级别 26）或更高版本。

Android Studio

如需使用 Android Studio 在本地设备上测试应用的免安装体验，请执行以下步骤：

1. 如果您的测试设备上有安装式应用，请将其卸载。
2. 在 Android Studio 中，从“Run/Debug Configurations”对话框的 General 标签页中显示的安装选项中，选中 Deploy as instant app 复选框。
3. 在菜单栏中依次选择 Run > Run，或点击工具栏中的 Run ，然后选择要用来测试应用的免安装体验的设备。应用的免安装体验会加载到您选择的测试设备上。

命令行界面

如需使用命令行在本地设备上测试应用的免安装体验，请执行以下步骤：

1. 如果您的测试设备上有安装式应用，请将其卸载。
2. 输入以下命令，在测试设备上旁加载并运行您的免安装应用：

ia run output-from-build-command

注意 ：您可以提供 ia run 的替代信息来启动免安装体验 在测试设备上的体验。如需了解详情，请执行以下命令： ia help run。

内部测试轨道

如需通过 Play 商店或网站上的横幅测试应用的免安装体验，请将应用发布到 Play 管理中心的内部测试轨道上。

如需将应用发布到内部测试轨道，请完成以下步骤：

1. 请按照将您的 app bundle 上传到 Play 管理中心指南中的步骤上传 app bundle。
2. 为上传的软件包制作发布到内部测试轨道的版本。如需了解详情，请参阅有关如何准备和发布版本的支持文章。

3. 使用内部测试人员账号登录设备，然后通过以下界面之一启动免安装体验：

   • 应用的 Play 商品详情中的立即体验按钮。
   • 应用网站上的横幅中的链接。

注意：当您使用 Google Play 的内部测试轨道时，Play 管理中心不会应用 Google Play 免安装体验概览中所述的大小限制。 因此，即使免安装体验的大小超过 15 MB，您仍然可以测试和在内部展示该体验。

将 app bundle 发布到正式版轨道

注意：亲子同乐计划目前不兼容 Google Play 免安装体验。如果您的应用或游戏 您需要退出亲子同乐计划 来发布免安装应用或游戏。

注意 ：自 2023 年 6 月起，只有使用 app bundle 发布的免安装应用才适用 提供给用户使用请确保所有基于 APK 的免安装应用均已安装 已更新为支持免安装体验的软件包。

如需发布免安装的 app bundle，请执行以下步骤：

1. 使用发布密钥为您的 app bundle 签名（如果尚未执行签名），然后将 app bundle 上传到 Play 管理中心。
2. 在 Play 管理中心，依次打开版本管理 > Android 免安装应用，然后转到免安装应用正式版轨道。
3. 选择 Update from Library，然后选择已上传的免安装 app bundle。

选择发布免安装体验的位置

您可以在用户可以安装您的应用的部分国家和地区发布应用的免安装体验。如果您希望向位于一组特定国家和地区的用户推广应用的免安装体验，此功能非常有用。

其他资源

如需详细了解如何打造免安装体验和 Android App Bundle，请参阅以下资源：

视频：利用 App Bundle 打造免安装应用

观看 2018 年 Android 开发者峰会中本次会议的视频，了解如何为 Android App Bundle 添加免安装体验。

视频：使用 Android App Bundle 发布体量更小的应用

了解如何通过 app bundle 加快应用开发速度，并为用户创建更小的 APK。

Codelab：您的首个 Android App Bundle

关于创建 Android App Bundle 并向其中添加功能的分步指南。

Android App Bundle 格式

详细了解 bundletool 命令行程序如何使用应用的代码和资源构建 app bundle。