更新行为

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

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

默认更新流程

Capgo的默认行为是如何处理应用程序更新的:

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

2. 下载完成后，__CAPGO_KEEP_0__会等待用户将应用程序切换到后台。

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通过提供 autoUpdate policy in your Capacitor config.

Required for instant apply: --delta, autoSplashscreen, 和 SplashScreen

"atInstall", "onLaunch"实时更新 "always" 在用户等待时，应用更新。使用 Delta更新 只有改变的文件下载。全量压缩上传会降低用户体验。

这些模式也需要 @capacitor/splash-screen 并 autoSplashscreen: true 与 SplashScreen.launchAutoHide: false. 在没有 splash 插件的情况下，用户会看到更新应用期间的闪烁或陈旧的 UI。

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

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

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

• false 或 'off': 关闭自动更新检查
• true 或 'atBackground' Capacitor Live Update 的替代方案
• 'atInstall'(default): 每次前台检查时自动检查并下载更新，然后在下一次后台时应用更新 "atBackground" behavior
• 'onLaunch'行为 "atBackground" behavior
• 'always': 只在从杀死状态（冷启动）将应用带到前台时立即应用。第一次检查后，回退到
• 'onlyDownload': 每次前台转换时检查，并在有可用更新时立即应用 updateAvailable: 自动检查并下载更新，发出

, 并且永远不会设置下一个捆绑包或自动应用更新

查看 测试原生构建 测试原生构建时，需要注意以下几点：

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 for instant apply with autoSplashscreen
    },
  },
};

export default config;

注意

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

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

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

注意

立即应用模式需要 @capacitor/splash-screen 和 autoSplashscreen: true。设置 launchAutoHide: false 在SplashScreen配置中（如上所示），以便在更新完成之前保持启动屏幕可见。

自动下载但不应用

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

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

In此模式下，插件会发出 updateAvailable 下载包后会发出 CapacitorUpdater.set() 您的应用程序可以决定何时调用

或显示自己的更新提示。

标题：自动处理启动屏幕"atInstall", "onLaunch", "always"即时应用模式（ autoSplashscreen ）需要 @capacitor/splash-screen (自版本 7.6.0 开始可用). 安装插件，直到 Capgo 隐藏启动画面：

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

复制到剪贴板 autoSplashscreen 启用时会发出：

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

启动屏幕隐藏后不需要额外的工作

保留 autoSplashscreen: true如果您需要在更新准备就绪后执行额外的逻辑，请监听 appReady 此外，不要跳过启动屏幕插件或 autoSplashscreen 复制到剪贴板

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

CapacitorUpdater.addListener('appReady', () => {
  // Update is applied. autoSplashscreen already hid the splash.
});

CapacitorUpdater.notifyAppReady();

当 appReady 事件在应用程序完成初始化和应用任何待处理更新后只会触发一次。

设置 keepUrlPathAfterReload 到 true 在使用即时应用模式时。 这样可以在应用程序由于更新而重新加载时保留当前 URL 路径。

使用即时应用模式可以用于交付关键错误修复或安全补丁，但它会带来一些权衡：

• 如果更新正在应用，用户可能会看到一个短暂的闪烁或加载状态。 @capacitor/splash-screen 如果缺失或 autoSplashscreen 未启用。
• 如果更新修改了应用程序状态或 UI，用户可能会在会话中看到一个打断性的变化。
• 如果未设置，应用程序的位置可能会丢失，导致用户感到混乱。 keepUrlPathAfterReload 您需要小心地处理保存和恢复状态，以确保平滑过渡。
• 缺失或未启用时，

如果您启用即时应用，我们建议:

• 使用 npx @capgo/cli@latest bundle upload --delta 以避免下载影响用户体验。
• 安装 @capacitor/splash-screen 并设置 autoSplashscreen: true 使用 launchAutoHide: false.
• 设置 keepUrlPathAfterReload 以 true 保持用户在应用中的位置。
• 以保留用户在应用中的位置。
• 保存和恢复应用状态以避免丢失用户进度。

In most cases, the default update behavior provides the best balance of delivering updates quickly and minimizing disruption. But for apps with specific needs, Capgo provides the flexibility to customize when and how updates are applied.

继续从更新行为

如果您正在使用 更新行为 计划live update的交付，连接它与 Capgo实时更新 为产品工作流程在CapgoLive Updates中 Overview 为__CAPGO_KEEP_0__实时更新中的产品工作流 概览 为概览中的实现细节 功能特性 为更新类型的实现细节，和 开始 为开始的实现细节。