更新行为

When you release an update to your Capgo app, you probably want your users to receive that update as soon as possible. But you also don’t want to disrupt their experience by forcing them to wait for a download or restart the app in the middle of a session.

Capgo 的更新行为旨在在快速交付更新和最小化对用户的干扰之间取得平衡。

默认更新流程

默认情况下，Capgo 如下处理应用程序更新：

1. 当应用程序切换到前台时，Capgo 插件会检查是否有新的更新可用。同时，应用程序保持打开状态，它还会在重复的定时器（默认10分钟）下再次检查一次。 periodCheckDelay 如果发现更新，它会在后台下载，而用户可以继续使用当前应用程序版本。

2. 当应用程序切换到前台时，__CAPGO_KEEP_0__ 插件会检查是否有新的更新可用。同时，应用程序保持打开状态，它还会在重复的定时器（默认10分钟）下再次检查一次。如果发现更新，它会在后台下载，而用户可以继续使用当前应用程序版本。

3. 下载完成后，Capgo 等待用户将应用程序置于后台。

4. 当用户下次将应用程序切换到前台时，他们将运行更新后的版本。

这种流程确保用户始终在运行应用程序的最新版本，而不需要被更新提示中断或等待下载。

提示

Capgo 检查更新时应用程序切换到前台以及在应用程序保持打开状态时重复计时器。 periodCheckDelay 控制该间隔（默认10分钟）。

为什么采用这种方法？

在后台或杀死事件中应用更新有几个关键的用户体验优势：

• 用户不会被更新提示中断或在会话中被迫等待下载。

• 在会话之间，更新将在无缝的方式应用，因此应用程序启动的体验始终是新的。

• 您可以频繁地发布更新，而不必担心会干扰正在使用的用户。

主要的缺点是，如果用户在应用更新期间快速切换到后台并重新启动应用，他们可能会丢失任何未保存的状态。

为了减轻这种情况，我们建议：

• 频繁保存状态并在应用重新启动时优雅地恢复它。

• 避免频繁更新，尤其是那些修改应用状态的大部分。

• 考虑自定义更新行为（见下文）。

自定义更新应用的时间

在某些情况下，您可能希望对更新应用的时间有更多的控制。例如，您可能希望确保用户完成正在进行的流程之前更新，或者与服务器端的更改协调应用更新。

Capgo 提供了一个 setDelay 函数，让您指定更新安装之前必须满足的条件：

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    {
      kind: 'date',
      value: '2023-06-01T00:00:00.000Z',
    },
    {
      kind: 'background',
      value: '60000',
    },
  ],
});

本示例将延迟安装更新，直到 2023 年 6 月 1 日之后，并且应用程序至少在后台运行 60 秒。

可用的延迟条件是：

• date: 等待特定日期/时间之后应用更新。
• background: 等待应用程序在后台运行至少一定时间后应用更新。
• nativeVersion: 等待安装具有最低版本的原生二进制文件之前应用更新。
• kill: 等待下一个应用程序杀死事件应用更新。

您可以混合和匹配这些条件来精确控制何时安装更新。

危险

注意， kill 当前条件将在第一次杀死事件后触发更新，而不是像其他条件一样在下一个后台事件后触发。这一不一致将在未来版本中修复。

立即应用更新

对于关键更新或具有非常简单状态的应用程序，您可能希望立即应用更新，而不等待后台或杀死事件。Capgo通过在Capgo配置中启用 autoUpdate policy in your Capacitor config.

推荐：使用Delta（清单）更新进行即时应用

使用即时应用模式时，我们 强烈建议 启用 Delta（清单）更新 以最小化下载时间并改善用户体验。Delta（清单）更新仅下载更改的文件，而不是整个捆绑包，这对于立即应用更新尤其重要，因为用户正在使用您的应用程序。

为什么即时应用模式中的此项很重要：

• 更快的更新：下载更小，更新速度更快，用户看到的加载屏幕时间更短
• 更好的移动体验：在移动网络或较慢的连接下，用户不会等待很长时间
• 更低的带宽使用：只有更改的文件才会下载，既节省了你的数据，又节省了你的用户的数据

当 autoUpdate 设置为 "atInstall", "onLaunch"，或者 "always" 在你的 capacitor.config，CLI会检测到它。在非交互环境中，它会自动发送Delta（清单）更新，在交互环境中，它会在上传之前提示你确认。Legacy directUpdate 配置仍然会被检测到。使用 --no-delta 强制上传完整的捆绑包

To enable Delta (manifest) updates, simply use the --delta 标志

npx @capgo/cli@latest bundle upload --delta

了解更多关于 Delta (manifest) Updates 文档 是设置在您的.

autoUpdate 文件中，而不是在 JavaScript 中的__CAPGO_KEEP_0__。它支持这些值: capacitor.config.ts file, not in JavaScript code. It supports these values:

• false 禁用自动更新检查 'off'或
• true (默认): 检查并下载每次前台检查时自动，然后在下一次应用程序移动到后台时应用更新 'atBackground' alternatives_cta_questions
• 'atInstall': 在首次安装或原生应用商店更新后立即应用; 否则使用 "atBackground" behavior
• 'onLaunch': 在从杀死状态（冷启动）将应用带到前台时立即应用; 之后第一次检查后，切换回 "atBackground" behavior
• 'always': 在每次前台转换时检查，并在有更新时立即应用
• 'onlyDownload': 自动检查和下载，发出 updateAvailable, 并且永远不会设置下一个捆绑包或自动应用更新

测试一个原生构建而不使用实时更新

查看 测试原生构建而不使用实时更新 以了解原生版本、频道策略和CI配置的安全措施

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true,
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Required when using instant apply with autoSplashscreen
    },
  },
};

export default config;

注意

重要: 只有即时应用模式才会在插件实际检查更新时应用更新。默认情况下，检查在应用切换到前台时运行，并在应用保持打开时以重复的时间间隔运行。 periodCheckDelay 控制该间隔（默认10分钟）。

与 autoUpdate: 'always'，Capgo在每次前台转换时进行检查，并在下载完成时立即应用更新，即使用户正在使用应用。周期性检查由 periodCheckDelay 可以在应用保持打开时触发相同的立即应用行为。

注意，因为 autoUpdate 是原生配置，立即应用模式需要在JavaScript中进行一些额外的处理，code。

注意事项

使用即时应用模式时， autoSplashscreen，必须设置 launchAutoHide: false 在SplashScreen配置中（如上所示）

下载自动更新而不应用

如果您想让Capgo自动下载更新但不自动应用，请使用 autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

在此模式下，插件会在下载包后发出 updateAvailable 您的应用程序可以决定何时调用 CapacitorUpdater.set() 或显示自己的更新提示

自动处理启动屏幕

为了使即时应用模式更易于使用，Capgo 提供了一个选项，自动处理隐藏启动屏幕（自版本 7.6.0 开始可用）： autoSplashscreen 复制到剪贴板

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

启用时： autoSplashscreen 插件在应用更新时自动隐藏启动屏幕

• 插件在不需要更新时自动隐藏启动屏幕
• 您不需要手动监听
• 事件或调用 appReady 手动启动屏幕处理 SplashScreen.hide()

Section titled “手动启动屏幕处理”

如果您希望手动控制或需要自定义逻辑，可以禁用 autoSplashscreen 并自己处理:

import { CapacitorUpdater } from '@capgo/capacitor-updater';
import { SplashScreen } from '@capacitor/splash-screen';

CapacitorUpdater.addListener('appReady', () => {
  // Hide splash screen
  SplashScreen.hide();
});

CapacitorUpdater.notifyAppReady();

The appReady 事件在应用程序完成初始化和应用任何待处理更新后触发一次。这是显示应用程序 UI 的安全点，因为它确保用户将看到最新版本。

除了处理事件外，我们建议在使用即时应用模式时将 appReady 配置选项设置为 keepUrlPathAfterReload 以便在应用程序由于更新而重新加载时保留当前 URL 路径，帮助维持用户在应用程序中的位置并减少混乱。 true 如果您不处理事件并在使用即时应用模式时设置

，用户可能会在应用程序更新期间看到过时版本、被带回初始路由或看到闪烁。 appReady event keepUrlPathAfterReload configuration option

使用即时应用模式可以有助于快速修复关键错误或安全漏洞，但它会带来一些权衡：

• 如果您没有正确处理启动屏幕（使用或手动事件处理），用户可能会在更新应用时看到一个短暂的闪烁或加载状态： autoSplashscreen 如果更新修改了应用状态或UI，用户可能会在会话中间看到一个打断的变化： appReady 如果不设置，用户的位置可能会丢失，导致他们感到混乱：
• 您需要小心地处理保存和恢复状态，以确保平滑过渡：
• 如果您启用即时应用，我们建议： keepUrlPathAfterReload 使用最简单的设置，或者手动处理事件，如果您需要自定义逻辑：
• 使用最简单的设置，或者手动处理事件，如果您需要自定义逻辑：

事件

• 事件 autoSplashscreen: true 事件 appReady 事件
• 设置 keepUrlPathAfterReload 到 true 为了保持用户在应用中的位置
• 保存和恢复应用状态以避免丢失用户进度
• 彻底测试应用更新行为以确保没有突然的过渡、丢失的状态或位置变化

大多数情况下，默认更新行为提供了最好的平衡，快速交付更新并最小化干扰。但是，对于具有特定需求的应用，Capgo提供了自定义更新应用时机和方式的灵活性

继续从更新行为

如果您正在使用 更新行为 来规划实时更新交付，连接它到 Capgo实时更新 为Capgo Live Updates 的产品工作流程 概述 为概述中的实现细节 功能 为功能中的实现细节 更新类型 为更新类型中的实现细节,并且 开始使用 为开始使用中的实现细节