通过

App Center Distribut – Android 应用内更新

重要

Visual Studio App Center 于 2025 年 3 月 31 日停用，但分析和诊断功能除外，这些功能将继续受支持，直到 2026 年 6 月 30 日。 了解详细信息。

通过 App Center Distribut 分发应用时，用户可安装新版本的应用。 随着应用的新版本可用，SDK 将向用户显示更新对话框，以便下载或推迟新版本。 选择更新后，SDK 将开始更新应用程序。

警告

即使应用内更新代码在运行时未使用，Google Play 也会将应用内更新代码视为恶意行为。 按照 本部分中 的指示使用分发 SDK 的变体，或在将应用提交到 Google Play 之前完全删除包含应用内更新代码的分发 SDK。 未能这样做可能会导致 Google Play 中的不合规和删除应用。

注释

如果运行的是自动化 UI 测试，启用的应用内更新将阻止自动化 UI 测试，因为它们将尝试针对 App Center 后端进行身份验证。 建议不要为 UI 测试启用 App Center Distribute。

在你的应用中添加应用内更新功能

如果尚未在应用程序中设置并启动 SDK，请按照 “入门 ”部分进行作。

1.添加 App Center Distribute 模块

App Center SDK 采用模块化方法设计，开发人员只需集成他们感兴趣的服务的模块。

  1. 打开项目的应用级别 build.gradle 文件 （app/build.gradle），并在之后 apply plugin添加以下行。

    dependencies {
   def appCenterSdkVersion = '5.0.6'
   implementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
}

    注释

    如果 Android Gradle 插件的版本低于 3.0.0，则需要将 实现 替换为 编译。

  2. 保存 build.gradle 文件，并确保在 Android Studio 中触发 Gradle 同步。

  3. DownloadManager 用于下载更新。 App Center SDK 强制实施 TLS 1.2 以提高安全性。

2. 启动 App Center 分发

若要使用 App Center，请选择加入要使用的模块。 默认情况下，不会启动任何模块，并且必须在启动 SDK 时显式调用每个模块。

将 Distribut 类添加到 AppCenter.start() 方法以启动 App Center Distribute 服务。

AppCenter.start(getApplication(), "{Your App Secret}", Distribute.class);

AppCenter.start(application, "{Your App Secret}", Distribute::class.java)

请确保已经在上面的代码示例中将 {Your App Secret} 替换为您的应用机密。 向方法添加对 Distribute 类的引用后，Android Studio 会自动建议所需的导入语句，但如果您看到无法识别类名称 start() 的错误，请将以下行添加到活动类中的 import 语句中：

import com.microsoft.appcenter.AppCenter;
import com.microsoft.appcenter.distribute.Distribute;

import com.microsoft.appcenter.AppCenter
import com.microsoft.appcenter.distribute.Distribute

注释

Android 10 或更高版本对后台的启动活动有限制。 请参阅有关 从后台启动活动的限制的文章。

注释

在 Android 10（Go 版本）上运行的应用无法接收 SYSTEM_ALERT_WINDOW 权限。 请参阅有关 Go 设备上的SYSTEM_ALERT_WINDOW的文章。

注释

从 Android 11 开始， ACTION_MANAGE_OVERLAY_PERMISSION 意向始终将用户引入顶级设置屏幕，用户可以在其中授予或撤销 SYSTEM_ALERT_WINDOW 应用的权限。 请参阅有关 Android 11 中权限更新的文章。

准备 Google Play 构建

即使应用内更新代码在运行时未使用，Google Play 也会将应用内更新代码视为恶意行为。 按照本部分中的指示使用分发 SDK 的变体，或在将应用提交到 Google Play 之前完全删除包含应用内更新代码的分发 SDK。 未能这样做可能会导致 Google Play 中的不合规和删除应用。 为了方便起见，我们提供了 App Center Distribut SDK 版本和 stubbed API，因此唯一的更改是依赖项交换。

  1. 打开项目的应用级别 build.gradle 文件（app/build.gradle）。

  2. 通过添加产品风味来配置构建变体：

    android {
    flavorDimensions "distribute"
    productFlavors {
        appCenter {
            dimension "distribute"
        }
        googlePlay {
            dimension "distribute"
        }
    }
}

  3. 根据产品风格修改依赖项块以使用不同的依赖项：

    dependencies {
    def appCenterSdkVersion = "5.0.6"
    appCenterImplementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
    googlePlayImplementation "com.microsoft.appcenter:appcenter-distribute-play:${appCenterSdkVersion}"
}

  4. 保存 build.gradle 文件，并确保在 Android Studio 中触发 Gradle 同步。

  5. 您可以在 构建 > 选择构建变体 的下拉菜单或工具窗口栏中的 构建变体 中更改构建变体。

可以在 Android 文档中阅读有关配置生成变体的详细信息。

使用私人分发组

默认情况下，分发使用公共分发组。 如果要使用专用通讯组，则需要通过 setUpdateTrack API 显式设置它。

Distribute.setUpdateTrack(UpdateTrack.PRIVATE);

Distribute.setUpdateTrack(UpdateTrack.PRIVATE)

注释

默认值是 UpdateTrack.PUBLIC。 此方法只能在调用 AppCenter.start 方法之前调用。 当应用程序进程重启时，更新跟踪的更改不会持久化，因此，如果该方法并非在每次调用 AppCenter.start 之前都被执行，那么它将默认是公共的。

当应用位于前台（Distribute.setUpdateTrack(UpdateTrack.PRIVATE);和AppCenter.start之后）时，将打开浏览器窗口以对用户进行身份验证。 所有后续更新检查都将在私有更新通道获取最新版本。

如果用户处于 专用轨道上，这意味着在成功进行身份验证后，他们将从他们所属的任何专用通讯组获取最新版本。 如果用户处于 公共轨道上，则意味着他们将从任何公共通讯组获取最新版本。

禁用自动更新检查

默认情况下，SDK 会自动检查新版本：

  • 应用程序启动时。
  • 应用程序从后台转换到前台时。
  • 当启用之前已禁用的分发模块时。

如果你希望手动检查新版本，可以禁用自动检查更新。 为此，在 SDK 启动之前调用以下方法：

Distribute.disableAutomaticCheckForUpdate();

Distribute.disableAutomaticCheckForUpdate()

注释

在调用 AppCenter.start 方法之前，必须调用此方法。

然后，可以使用以下部分中介绍的 checkForUpdate API。

手动检查更新

Distribute.checkForUpdate();

Distribute.checkForUpdate()

这会向 App Center 发送请求，并在有新版本可用时显示更新对话框。

注释

即使启用了自动更新，更新调用的手动检查也有效。 如果另一个检查已完成，则忽略更新的手动检查。 如果用户已推迟更新（除非最新版本是强制更新），则不会处理更新的手动检查。

自定义或本地化应用内更新对话框

1.自定义或本地化文本

如果要更改或本地化更新对话框中显示的文本，可以轻松提供自己的资源字符串。 查看 此资源文件中的字符串文件。 使用相同的字符串名称/键，并在你的应用资源文件中指定要在对话框中体现的本地化值。

2.自定义更新对话框

可以通过实现 DistributeListener 接口来自定义默认更新对话框的外观。 在调用 AppCenter.start 之前，需要注册侦听器，如以下示例所示：

Distribute.setListener(new MyDistributeListener());
AppCenter.start(...);

Distribute.setListener(MyDistributeListener())
AppCenter.start(...)

下面是将 SDK 对话框替换为自定义对话的侦听器实现示例：

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.net.Uri;

import com.microsoft.appcenter.distribute.Distribute;
import com.microsoft.appcenter.distribute.DistributeListener;
import com.microsoft.appcenter.distribute.ReleaseDetails;
import com.microsoft.appcenter.distribute.UpdateAction;

public class MyDistributeListener implements DistributeListener {

    @Override
    public boolean onReleaseAvailable(Activity activity, ReleaseDetails releaseDetails) {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        String versionName = releaseDetails.getShortVersion();
        int versionCode = releaseDetails.getVersion();
        String releaseNotes = releaseDetails.getReleaseNotes();
        Uri releaseNotesUrl = releaseDetails.getReleaseNotesUrl();

        // Build our own dialog title and message
        AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(activity);
        dialogBuilder.setTitle("Version " + versionName + " available!"); // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes);

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download, new DialogInterface.OnClickListener() {

            @Override
            public void onClick(DialogInterface dialog, int which) {

                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.UPDATE);
            }
        });

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate()) {
            dialogBuilder.setNegativeButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone, new DialogInterface.OnClickListener() {

                @Override
                public void onClick(DialogInterface dialog, int which) {

                    // This method is used to tell the SDK what button was clicked
                    Distribute.notifyUpdateAction(UpdateAction.POSTPONE);
                }
            });
        }
        dialogBuilder.setCancelable(false); // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show();

        // Return true if you're using your own dialog, false otherwise
        return true;
    }
    
    @Override
    public void onNoReleaseAvailable(Activity activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show();
    }
}

import android.app.Activity
import android.app.AlertDialog
import com.microsoft.appcenter.distribute.Distribute
import com.microsoft.appcenter.distribute.DistributeListener
import com.microsoft.appcenter.distribute.ReleaseDetails
import com.microsoft.appcenter.distribute.UpdateAction

class MyDistributeListener : DistributeListener {

    override fun onReleaseAvailable(activity: Activity, releaseDetails: ReleaseDetails): Boolean {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        val versionName = releaseDetails.shortVersion
        val versionCode = releaseDetails.version
        val releaseNotes = releaseDetails.releaseNotes
        val releaseNotesUrl = releaseDetails.releaseNotesUrl

        // Build our own dialog title and message
        val dialogBuilder = AlertDialog.Builder(activity)
        dialogBuilder.setTitle("Version $versionName available!") // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes)

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(
            com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download
        ) { dialog, which ->
            // This method is used to tell the SDK what button was clicked
            Distribute.notifyUpdateAction(UpdateAction.UPDATE)
        }

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate) {
            dialogBuilder.setNegativeButton(
                com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone
            ) { dialog, which ->
                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.POSTPONE)
            }
        }
        dialogBuilder.setCancelable(false) // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show()

        // Return true if you're using your own dialog, false otherwise
        return true
    }

    override fun onNoReleaseAvailable(activity: Activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show()
    }
}

如示例中所示，如果侦听器返回true，则必须调用Distribute.notifyUpdateAction(UpdateAction.UPDATE);或Distribute.notifyUpdateAction(UpdateAction.POSTPONE);。

如果不调用 notifyUpdateAction，回调将在每次活动更改时重复。

如果在用户操作通知到 SDK 之前活动发生更改，则可以使用相同的版本再次调用侦听器。

需要此行为才能涵盖以下情境：

  • 应用程序会像按下 HOME 键一样被发送到后台，然后在一个不同的界面中恢复。
  • 你的活动被另一个活动遮挡，不必离开应用程序（例如点击一些通知）。
  • 其他类似的方案。

在这种情况下，托管对话框的活动可能会被替换，而无需用户交互。 因此，SDK 再次调用侦听器，以便可以还原自定义对话。

如果 SDK 检查更新时没有找到比当前使用版本更新的可用更新，则会调用 onNoReleaseAvailable 接口的 DistributeListener 回调。 这样，就可以在此类方案中执行自定义代码。 上面的示例演示如何在找不到更新时显示 Toast 消息。

在运行时启用或禁用 App Center Distribut

可以在运行时启用和禁用 App Center Distribute。 如果禁用此功能，SDK 不会提供任何应用内更新功能，但仍可以在 App Center 门户中使用分发服务。

Distribute.setEnabled(false);

Distribute.setEnabled(false)

若要再次启用 App Center Distribute，请使用相同的 API，但作为参数传递 true 。

Distribute.setEnabled(true);

Distribute.setEnabled(true)

状态在应用程序启动时保留在设备的存储中。

此 API 是异步的，可以在 App Center 异步 API 指南中详细了解该 API。

注释

此方法只能在启动 Distribute 后使用。

检查是否启用了 App Center Distribute

还可以检查 App Center Distribute 是否已启用：

Distribute.isEnabled();

Distribute.isEnabled()

此 API 是异步的，可以在 App Center 异步 API 指南中详细了解该 API。

注释

此方法应仅在 Distribute 启动后使用，在启动前，它将始终返回 false。

为调试版本启用应用内更新

默认情况下，App Center 仅对发布版本启用应用内更新。

若要在调试版本中启用应用内更新，请先调用以下方法 AppCenter.start：

Distribute.setEnabledForDebuggableBuild(true);

Distribute.setEnabledForDebuggableBuild(true)

注释

此方法仅影响调试生成，对发布版本没有影响。 调试生成意味着 android:debuggable 标志设置为 true （通常由 gradle 预定义的调试生成变体自动设置）。 否则，这是发布版本。

应用内更新的工作原理是什么？

注释

若要使应用内更新正常工作，应从链接下载应用内部版本。 如果从 IDE 安装或手动安装，则它不起作用。

应用内更新功能的工作原理如下：

  1. 此功能仅适用于使用 App Center Distribut 服务分发的 RELEASE 内部版本（默认情况下）。

  2. 集成 SDK 后，生成应用的发布版本并上传到 App Center，发行组中的用户将通过电子邮件收到新版本通知。

  3. 每个用户在其电子邮件中打开链接时，应用程序将安装在其设备上。 请务必使用电子邮件链接进行安装 - 我们不支持旁加载。 从链接下载应用程序时，SDK 会保存 Cookie 中的重要信息，以便以后检查更新，否则 SDK 没有该密钥信息。

  4. 如果应用程序将轨迹设置为专用，浏览器将打开以对用户进行身份验证并启用应用内更新。 只要身份验证信息保持有效，即使切换回公共模式，之后再返回私密模式，也不需要重新打开浏览器。 如果浏览器身份验证成功，用户会自动重定向回应用程序。 如果轨道是公共的（这是默认值），则下一步将直接执行。

  5. 应用的新版本显示应用内更新对话框，要求用户更新应用程序（如果是）：

    • 一个较高的值 versionCode 或
    • 一个相等值， versionCode 但值 versionName不同。

小窍门

如果第二次上传相同的 APK，由于版本相同，对话框将不会出现。

如何测试应用内更新？

需要将发布版本（使用 App Center SDK 的分发模块）上传到 App Center 门户，以测试应用内更新，每次增加版本号。

  1. 如果尚未创建应用，请在 App Center 门户中创建应用。
  2. 创建一个新的分发组并对其进行命名，以便能识别它是用于测试应用内更新功能的。
  3. 添加自己（或您希望包含在应用内更新测试中的所有人员）。 为此使用新的或丢弃的电子邮件地址，该地址不用于 App Center 上的该应用。 这可确保你的体验接近实际测试人员的体验。
  4. 创建包含 App Center Distribute 的应用的新内部版本，并包含如上所述的设置逻辑。 如果组是专用组，请勿忘记在开始使用 setUpdateTrack API 之前设置专用应用内更新跟踪。
  5. 单击门户中的“ 分发新版本 ”按钮并上传应用的生成。
  6. 上传完成后，单击“ 下一步 ”，然后选择创建的 通讯组 作为该应用分发 的目标 。
  7. 审查分发并将构建分发到应用内测试组。
  8. 该组中的人员将收到成为应用测试人员的邀请。 接受邀请后，他们可以从其移动设备从 App Center 门户下载应用。 安装应用内更新后，即可测试应用内更新。
  9. 更新应用程序的versionCode版本。
  10. 生成应用的发布版本，并像在上一步中一样上传应用的新版本，并将其分发到之前创建的 通讯组 。 下次启动应用时，分发组的成员将会收到有关版本更新的提示。

小窍门

查看有关如何 利用 App Center Distribution 的信息，获取有关 通讯组 等的更多详细信息。虽然可以使用 App Center Distribut 分发新版应用而不添加任何代码，但将 App Center Distribute 添加到应用代码将导致测试人员和用户在获得应用内更新体验时获得更无缝的体验。