通过

App Center Distribute - Unity 应用内更新

重要

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

通过 App Center 分发版，用户/测试人员可以在通过 App Center 分发应用后安装新版本的应用。 启用后，SDK 会向用户显示更新对话框，以便下载或推迟安装最新更新。 选择更新后，SDK 将开始更新应用程序。

重要

分发 SDK for Unity 不支持 UWP。 本页中的说明仅涵盖 Android 和 iOS。

警告

即使应用内更新代码在运行时未使用，Google Play 也会将应用内更新代码视为恶意行为。 将应用提交到 Google Play 之前，请根据 本部分中 的指示删除此代码。 未能移除应用内更新代码，可能会导致应用不符合规定并被 Google Play 删除。

注释

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

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

添加 App Center Distribute 模块

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

如果尚未在应用程序中设置并启动 SDK，请遵循 Unity 入门 文档。 请确保导入 App Center Distribut 包。 其名称应采用格式 AppCenterDistribute-v{version}.unitypackage。

注释

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 也会将应用内更新代码视为恶意行为。 将应用提交到 Google Play 之前，请删除此代码。 未能移除应用内更新代码，可能会导致应用不符合规定并被 Google Play 删除。 若要删除应用内更新的原生代码，请在附加了AppCenterBehavior的游戏对象上的“分发”部分下取消选中“使用分发”复选框。

使用私人分发组

默认情况下，分发使用公共分发组。 如果要使用专用通讯组，则需要更改为 UpdateTrack “专用”。 为此，请在附加了AppCenterBehavior的游戏对象上，进入分发部分，然后在更新跟踪下拉列表中选择专用。

使用专用轨道时，浏览器窗口将打开以对用户进行身份验证。 所有后续更新检查都将在私有更新通道获取最新版本。

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

禁用自动更新检查

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

  • 应用程序启动时。
  • 当应用程序进入后台后，再次切换到前台。
  • 当启用之前已禁用的分发模块时。

如果你希望手动检查新版本，可以禁用自动检查更新。

为此，请在附有AppCenterBehavior的游戏对象的“分发”部分下，取消选中“自动检查更新”复选框。

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

手动检查更新

Distribute.CheckForUpdate();

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

注释

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

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

1.自定义或本地化文本

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

2.自定义更新对话框

可以通过实现 ReleaseAvailable 回调来自定义默认更新对话框的外观。

警告

在应用程序加载的首个场景中，需要在MonoBehaviour的Awake方法中注册回调，以避免错过任何发布回调调用。

// In this example, OnReleaseAvailable is a method name in same class
Distribute.ReleaseAvailable = OnReleaseAvailable;

下面是将 SDK 对话框替换为自定义逻辑的回调实现：

bool OnReleaseAvailable(ReleaseDetails releaseDetails)
{
    // Look at releaseDetails public properties to get version information, release notes text or release notes URL
    string versionName = releaseDetails.ShortVersion;
    string versionCodeOrBuildNumber = releaseDetails.Version;
    string releaseNotes = releaseDetails.ReleaseNotes;
    Uri releaseNotesUrl = releaseDetails.ReleaseNotesUrl;

    // (Do something with the values if you want)

    // On mandatory update, user can't postpone
    if (releaseDetails.MandatoryUpdate)
    {
        // Force user to update (you should probably show some custom UI here)
        Distribute.NotifyUpdateAction(UpdateAction.Update);
    }
    else
    {
        // Allow user to update or postpone (you should probably show some custom UI here)
        // "GetUserUpdateAction()" isn't part of the SDK; it just represents a way of getting user response.
        // This blocks the thread while awaiting the user's response! This example shouldn't be used literally
        UpdateAction updateAction = GetUserUpdateAction();
        Distribute.NotifyUpdateAction(updateAction);
    }
    // Return true if you're using your own UI to get user response, false otherwise
    return true;
}

Android 的实现说明：

如示例中所示，如果回调返回true，您必须调用Distribute.NotifyUpdateAction(UpdateAction.UPDATE);或Distribute.NotifyUpdateAction(UpdateAction.POSTPONE);。

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

如果在通知用户操作到 SDK 之前，活动发生变化，则可以用相同的版本再次调用回调函数。

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

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

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

3.如果未找到更新，则执行代码

如果 SDK 检查更新时，找不到任何比当前使用版本新的更新，则会调用 NoReleaseAvailable 回调。 这样，就可以在此类方案中执行自定义代码。 在调用 AppCenter.Start 之前，需要注册回调，如以下示例所示：

// In this example OnNoReleaseAvailable is a method name in same class
Distribute.NoReleaseAvailable = OnNoReleaseAvailable;
AppCenter.Start(...);

void OnNoReleaseAvailable()
{
    AppCenterLog.Info(LogTag, "No release available callback invoked.");
}

## Enable or disable App Center Distribute at runtime

You can enable and disable App Center Distribute at runtime. If you disable it, the SDK won't provide any in-app update functionality but you can still use the Distribute service in the App Center portal.

To disable the Distribute service, use the following code:

```csharp
Distribute.SetEnabledAsync(false);

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

Distribute.SetEnabledAsync(true);

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

无需等待此调用即可使其他 API 调用（例如 IsEnabledAsync）保持一致。

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

检查是否启用了 App Center Distribute

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

Distribute.IsEnabledAsync();

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

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

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

若要为 Android 和 iOS 上的调试版本启用应用内更新，请在附加 AppCenterBehavior 的游戏对象的“分发”部分下选中“在调试中启用分发”复选框。

App Center 行为

在 Unity 中，选中 “开发生成” 选项的生成即为可调试生成。

在应用关闭更新之前立即执行清理

注释

此回调仅适用于 iOS。

请按照以下示例注册回调函数：

// In this example, OnWillExitApp is a method name in same class
Distribute.WillExitApp = OnWillExitApp;

void OnWillExitApp()
{
    // Perform clean up here
}

这样，当分发即将关闭时，它将调用 OnWillExitApp()。

应用内更新的工作原理

注释

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

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

  1. 此功能仅适用于使用 App Center Distribut 服务分发的 RELEASE 内部版本（默认情况下）。 如果启用 iOS 引导访问功能，则不起作用。
  2. 集成 SDK 后，生成应用的发布版本，并将其上传到 App Center。 通讯组中的用户通过电子邮件收到有关新版本的通知。
  3. 每个用户在其电子邮件中打开链接时，应用程序将安装在其设备上。 请务必使用电子邮件链接进行安装 - 我们不支持旁加载。 从链接下载应用程序时，SDK 会保存 Cookie 中的重要信息，以便以后检查更新，否则 SDK 没有该密钥信息。
  4. 如果应用程序将轨迹设置为专用，浏览器将打开以对用户进行身份验证并启用应用内更新。 只要身份验证信息保持有效，即使切换回公共模式，之后再返回私密模式，也不需要重新打开浏览器。 如果浏览器身份验证成功，用户会自动重定向回应用程序。 如果轨道是公共的（这是默认值），则下一步将直接执行。
  5. 应用的新版本显示应用内更新对话框，要求用户更新应用程序（如果是）：
    • iOS：
      • 一个较高的值 CFBundleShortVersionString 或
      • 具有CFBundleShortVersionString的相等值，但CFBundleVersion的值更高。
      • 版本相同，但构建唯一标识符不同。
    • Android：
      • 一个较高的值 versionCode 或
      • 一个相等值， versionCode 但值 versionName不同。

小窍门

如果第二次上传相同的.apk/.ipa，对话框不会出现，因为二进制文件相同。 在 iOS 上，如果上传一个具有相同版本属性的新构建，则会显示更新对话框。 之所以这样，是因为它是一个不同的二进制文件。 在 Android 上，如果两个版本属性都相同，则二进制文件被视为相同。

如何测试应用内更新？

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

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

小窍门

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