更新行为

当您向您的Capgo应用程序发布更新时，您可能希望您的用户尽快接收该更新。但您也不希望迫使他们等待下载或在会话中重新启动应用程序中断他们的体验。

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

默认更新流程

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

1. On app launch, the Capgo plugin checks to see if a new update is available.

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

3. 一旦下载完成，Capgo 等待用户在后台或完全关闭应用时再次启动应用。

4. 当用户下次启动应用时，他们将运行更新后的版本。

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

提示

Capgo 也会在应用从后台恢复时检查更新，因此即使用户没有完全退出应用，用户也会收到更新。

为什么采用这种方法？

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

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

• Updates will be applied seamlessly between sessions, so the experience of launching the app is always fresh.

• You can deliver updates frequently without worrying about disrupting active users.

The main drawback is that if a user backgrounds and quickly resumes your app, they may lose any unsaved state since the update was applied in between those actions.

To mitigate this, we recommend:

• Saving state frequently and restoring it gracefully when the app resumes.

• Avoiding very frequent updates that modify large parts of the app state.

• Considering customizing the update behavior for sensitive flows (see below).

Customizing When Updates Are Applied

__CAPGO_KEEP_0__ 提供了一个

Capgo provides a setDelay __CAPGO_KEEP_0__ provides a 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通过 directUpdate 配置选项

推荐：使用Delta（清单）更新与直接更新

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

Why this matters for Direct Updates:

• 更快的更新: 更小的下载意味着更新会快速完成，减少用户看到的加载屏幕时间
• 更好的移动体验: 在移动网络或较慢连接的用户不会面临长时间等待
• 更低的带宽使用: 只下载更改的文件，既节省了你的数据，也节省了你的用户的数据

当 directUpdate 在你的 capacitor.config,CLI检测到它。 在非交互环境中，它会自动发送Delta（清单）更新，在交互环境中，它会在上传之前提示你确认。 使用 --no-delta 强制上传完整的捆绑包

要启用Delta（清单）更新，请简单地使用 --delta 上传包时的标志:

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

在 Delta (manifest) 更新文档.

directUpdate 在你的 capacitor.config.ts 文件中设置，而不是在 JavaScript 中 code. 它支持三个值:

• false (默认): 不进行直接更新（使用默认行为：下载时启动，设置时后台）
• 'atInstall': 只在应用安装、更新时从商店更新时进行直接更新，否则像 directUpdate = false 一样
• 'onLaunch': 只在应用安装、更新时从商店更新或应用被杀死后进行直接更新，否则像 directUpdate = false 一样
• 'always': 在所有上述情况下（应用安装、更新时从商店、应用被杀死或应用恢复）进行直接更新，永远不像 directUpdate = false 一样
• true (已弃用): 与 'always' 为了向后兼容

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

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true, // NEW: Automatically handle splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Still required when using directUpdate
    },
  },
};

export default config;

注意

重要: directUpdate 仅在应用程序实际检查更新时才会应用更新。默认情况下，这只会在应用程序启动或从后台恢复时发生。注意 periodCheckDelay 与 directUpdate.

启用后，__CAPGO_KEEP_0__ 将在更新检查期间下载完成后立即应用更新，即使用户正在使用应用程序。禁用周期性检查后，这意味着更新将仅在应用程序启动或从后台恢复时才会应用。 directUpdate enabled, Capgo will immediately apply an update as soon as the download completes during an update check, even if the user is actively using the app. Without periodic checking enabled, this means updates will only be applied when the app starts or resumes from background.

是一个原生配置，因此它需要在您的JavaScript中进行一些额外的处理。 directUpdate is a native configuration, it requires some additional handling in your JavaScript code.

注意

在使用 directUpdate,您必须设置 launchAutoHide: false 在SplashScreen配置（如上所示）中

以防止启动屏幕自动隐藏。这确保您在更新过程完成后有完全控制启动屏幕隐藏的时间。

标题：自动启动屏幕处理 directUpdate easier to use, Capgo provides an autoSplashscreen 更容易使用，__CAPGO_KEEP_0__提供了一个

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: '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 配置选项设置为 true 使用 directUpdate。这样可以在应用程序更新时保持当前 URL 路径，帮助维持用户在应用程序中的位置并减少混乱。

如果您不处理 appReady 事件并设置 keepUrlPathAfterReload 使用 directUpdate，用户可能会在应用程序更新时看到过时的版本，或者被带回初始路由，或者在应用程序更新时看到闪烁的屏幕。

使用 directUpdate 可以用来交付关键的bug修复或安全补丁，但它会带来一些权衡：

• 如果您不正确地处理 autoSplashscreen （或手动处理），用户可能会在应用程序更新时看到闪烁的屏幕或加载状态 appReady 事件处理).
• 如果更新修改了应用程序状态或 UI，用户可能会在会话中间看到一个打断的变化。
• 如果"位置"属性未设置，用户可能会在应用程序中迷路。 keepUrlPathAfterReload 您需要小心地处理保存和恢复状态，以确保平滑过渡。
• 如果您启用"位置"，我们建议：

使用"位置"的最简单设置，或者手动处理"位置"事件，如果您需要自定义逻辑。 directUpdate设置"位置"为

• translations autoSplashscreen: true __CAPGO_KEEP_0__ appReady __CAPGO_KEEP_1__
• __CAPGO_KEEP_2__ keepUrlPathAfterReload __CAPGO_KEEP_3__ true 保持用户在应用中的位置。
• 在需要时保存和恢复应用状态，以避免丢失用户进度。
• 彻底测试应用程序更新行为，以确保没有突然的过渡、丢失的状态或混乱的位置变化。

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