更新行为

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

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

默认更新流程

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

1. 当应用程序移动到前台时，Capgo插件会检查是否有新的更新可用。同时，应用程序保持打开状态，它也会在重复的定时器控制下再次检查 periodCheckDelay (default 10 minutes).

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

3. Capgo等待用户将应用程序置于后台.

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

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

提示

Capgo在应用程序切换到前台时以及应用程序保持打开时，定期检查更新. periodCheckDelay 控制该间隔（默认10分钟）。

为什么采用这种方法？

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

• targetLanguage":"Simplified Chinese",

• protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"]

• ,

texts":["用户不会被更新提示或被迫在会话中等待下载中打断。",

更新在会话之间被应用，启动应用的体验始终是新的。",

• 您可以频繁地发布更新而不必担心中断活跃用户。",

• 主要的缺点是，如果用户在应用更新期间背景化并快速恢复应用，他们可能会丢失任何未保存的状态。",

• 为了减轻这一点，我们建议：

."保存状态频繁并在应用恢复时优雅地恢复。",

考虑定制更新行为以适应敏感流（见下文）。",

Capgo provides a setDelay function that lets you specify conditions that must be met before an update is installed:

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（清单）更新，在交互环境中，它会在上传之前提示你确认。 directUpdate 配置仍然被检测到。使用 --no-delta 来强制进行一次完整的打包上传。

要启用Delta (清单)更新，仅需在上传打包时使用以下标志： --delta 终端窗口

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

Delta (清单)更新文档 在你的.

autoUpdate 文件中设置，而不是在JavaScript中 __CAPGO_KEEP_0__. 它支持以下值： capacitor.config.ts file, not in JavaScript code. It supports these values:

• false : 禁用自动更新检查 'off'config is still detected. Use __CAPGO_KEEP_0__ to force a full bundle upload.
• true 或 'atBackground' (default): 每次前台检查时自动检查并下载，下次应用切换到后台时应用更新
• 'atInstall': 只在新安装或原生应用商店更新后立即应用；否则使用 "atBackground" 行为
• 'onLaunch': 只在应用从杀死状态（冷启动）切换到前台时立即应用。第一次检查后，回退到 "atBackground" 行为
• '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 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();

The event fires once the app has finished initializing and applying any pending updates. This is the point at which it’s safe to show your app’s UI, as it ensures the user will see the latest version. appReady In addition to handling the event, we recommend setting the configuration option to when using an instant apply mode. This preserves the current URL path when the app is reloaded due to an update, helping maintain the user’s location in the app and reducing disorientation.

If you don’t handle the event and set when using an instant apply mode, the user may briefly see a stale version of the app, be taken back to the initial route, or see a flicker as the update is applied. appReady Using an instant apply mode can be useful for delivering critical bug fixes or security patches, but it comes with some tradeoffs: keepUrlPathAfterReload The user may see a brief flicker or loading state as the update is applied if you don’t properly handle the splashscreen (either with or manual) true 在应用程序完成初始化和应用任何待处理更新后，会触发此事件。 这是显示应用程序 UI 的安全点，因为它确保用户将看到最新版本。

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

如果您不正确处理启动屏幕（即使是使用 或手动），用户可能会在应用程序更新时看到短暂的闪烁或加载状态。

• 在应用程序完成初始化和应用任何待处理更新后，会触发此事件。 这是显示应用程序 UI 的安全点，因为它确保用户将看到最新版本。 autoSplashscreen 除了处理事件外，我们建议在使用即时应用模式时设置配置选项为 。这在应用程序由于更新而重新加载时保留当前 URL 路径，帮助维护用户在应用程序中的位置并减少混乱。 appReady 事件处理).
• 如果更新修改了应用程序状态或 UI，用户可能会在会话中看到一个中断性的变化。
• 如果用户的位置在应用程序中丢失，可能会让他们感到混乱。 keepUrlPathAfterReload 您需要小心地处理保存和恢复状态，以确保平滑的过渡。
• 如果您启用了即时应用，我们建议：

使用

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

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

继续从更新行为

如果您正在使用 更新行为 来规划实时更新交付，请将其与 Capgo Live Updates for the product workflow in Capgo Live Updates, __CAPGO_KEEP_0__ Live Updates 中，查看 功能 在功能中实现详细信息 更新类型 在更新类型中实现详细信息 开始 在开始中实现详细信息