更新行为

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

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

默认更新流程

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

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

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

3. Once the download completes, Capgo waits for the user to background the app.

4. 此流程确保用户始终在运行最新版本的应用，而不会被更新提示或被迫等待下载中断。

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

提示

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 Capacitor

Recommended: Use Delta (Manifest) Updates with Instant Apply

当使用即时应用模式时，我们 强烈建议 启用 Delta (manifest) Updates 以最小化下载时间并改善用户体验

Delta (manifest) updates 只下载更改的文件，而不是整个捆绑包，这在更新立即应用于用户正在使用的应用程序时尤其重要。

• 为什么即时应用模式中的此项重要：更快的更新
• :较小的下载意味着更新速度快，减少了用户看到加载屏幕的时间更好的移动体验：
• 降低带宽使用: 只下载更改的文件，节省双方的数据

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

要启用Delta（清单）更新，只需在上传捆绑包时使用 --delta 标志：

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

在 Delta (manifest) 更新文档.

autoUpdate 由您的 capacitor.config.ts 文件设定，而不是 JavaScript code. 它支持这些值：

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

测试原生构建无实时更新

查看 测试原生构建无实时更新 原生构建无实时更新的native-version、channel-policy和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提供了一个 autoSplashscreen 选项，自动处理隐藏启动屏幕（自版本7.6.0起可用）：

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();

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

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

事件并在使用即时应用模式时设置 appReady ，用户可能会在应用程序更新期间看到过时版本、被带回初始路由或看到应用程序更新时的闪烁效果。 keepUrlPathAfterReload 使用即时应用模式可以用于交付关键错误修复或安全补丁，但它会带来一些权衡：

如果您不正确处理启动屏幕（使用

• 或手动处理），用户可能会在应用程序更新期间看到闪烁或加载状态。 autoSplashscreen 使用即时应用模式可以用于交付关键错误修复或安全补丁，但它会带来一些权衡： appReady event handling).
• 如果更新修改了应用程序状态或 UI，用户可能会在会话中间看到一个中断性的变化.
• 如果 keepUrlPathAfterReload 未设置，用户可能会在应用程序中迷路.
• 您需要小心地处理保存和恢复状态，以确保平滑的过渡.

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

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

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

继续从更新行为

如果您正在使用 更新行为 来规划实时更新交付，连接它与 Capgo Live Updates for the product workflow in Capgo Live Updates, __CAPGO_KEEP_0__ Live Updates 概述 功能 对于功能的实现细节 更新类型 对于更新类型的实现细节 入门 对于入门的实现细节