更新行为

当您向您的Capgo应用程序发布更新时，您可能希望您的用户尽快接收到该更新。但是，您也不希望通过强制用户等待下载或在会话中重新启动应用程序来干扰他们的体验。

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

默认更新流程

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

1. 当应用程序切换到前台时，Capgo插件会检查是否有新的更新可用。同时，应用程序保持打开状态，它还会在控制器由 periodCheckDelay (默认10分钟)控制的重复定时器上检查一次。

2. 如果发现更新，它会在后台下载，而用户继续使用应用程序的当前版本。

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 立即应用更新

标题为“立即应用更新”的部分

For critical updates or apps with very simple state, you may want to apply an update as soon as it’s downloaded, without waiting for a background or kill event. Capgo supports this via the autoUpdate Capacitor

建议：使用Delta（清单）更新进行即时应用

在使用即时应用模式时，我们 强烈建议 启用 Delta（清单）更新 以最小化下载时间并改善用户体验

Delta（清单）更新仅下载更改的文件，而不是整个捆绑包，这在更新立即应用时尤其重要，因为用户正在使用应用程序时。

• 为什么即时应用模式中的此项很重要：更快的更新：更小的下载意味着更新速度快，减少了用户看到加载屏幕的时间
• 更好的移动体验：在移动网络或较慢的连接下，用户不会遇到长时间的等待
• 降低带宽使用量：只下载更改的文件，既节省了你的数据，也节省了你的用户的数据

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

强制上传完整的捆绑包。 --delta 当上传捆绑包时显示标志：

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

在 Delta (manifest) 更新文档.

autoUpdate 设置在你的 capacitor.config.ts 文件中，而不是在 JavaScript 中 code. 它支持这些值：

• false 或 'off'：禁用自动更新检查
• true 或 'atBackground' (默认): 每次前台检查时检查并下载更新，然后在下次应用切换到后台时应用更新
• '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 is a native configuration, instant apply modes require some additional handling in your JavaScript code.

注意

当使用即刻应用模式时， autoSplashscreen，您必须设置 launchAutoHide: false 在SplashScreen配置中（如上所示）以防止启动屏幕自动隐藏。这确保您在更新过程完成后有完全控制启动屏幕隐藏的时间。

自动下载但不应用

如果您想Capgo自动检查并下载更新，但永远不自动应用它们，请使用 autoUpdate: 'onlyDownload':

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

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

自动启动屏幕处理

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

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

当 autoSplashscreen 启用时：

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

手动启动屏幕处理

如果您更喜欢手动控制或需要自定义逻辑，可以禁用 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 的安全点，因为它确保用户将看到最新版本。

除了处理"事件"外，我们建议在使用即时应用模式时将"配置选项"设置为""。这在应用程序重新加载时由于更新而保留当前 URL 路径，帮助维持用户在应用程序中的位置并减少混乱。 appReady 如果您不处理"事件"并在使用即时应用模式时设置"配置选项"，用户可能会在应用程序更新期间看到过时版本、被带回初始路由或看到闪烁的更新过程。 keepUrlPathAfterReload 使用即时应用模式可以用于交付关键 bug 修复或安全补丁，但它会带来一些权衡： true __CAPGO_KEEP_0__

__CAPGO_KEEP_0__ appReady __CAPGO_KEEP_0__ keepUrlPathAfterReload __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

• 如果您没有正确处理启动屏幕（使用 autoSplashscreen 或手动 appReady 事件处理），用户可能会看到一个短暂的闪烁或加载状态。
• 如果更新修改了应用程序状态或用户界面，用户可能会在会话中看到一个打断性的变化。
• 如果 keepUrlPathAfterReload 未设置，用户的应用程序位置可能会丢失，从而使他们感到混乱。
• 您需要小心地处理保存和恢复状态，以确保平滑的过渡。

如果您启用了即刻应用，我们建议：

• 使用 autoSplashscreen: true 进行最简单的设置，或者手动处理 appReady 事件，如果您需要自定义逻辑。
• 设置 keepUrlPathAfterReload to true 为了在应用中保留用户的位置。
• 根据需要保存和恢复应用状态，以避免丢失用户进度。
• 彻底测试应用程序更新行为，以确保没有突然的过渡、丢失的状态或混乱的位置变化。

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

继续从更新行为

如果您正在使用 更新行为 来规划实时更新交付，连接它与 Capgo Live Updates 用于Capgo Live Updates中的产品工作流程 概述 __CAPGO_KEEP_0__ 功能 __CAPGO_KEEP_1__ 更新类型 __CAPGO_KEEP_2__ 开始使用 __CAPGO_KEEP_3__