更新行为

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

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

默认更新流程

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

1. 应用程序启动时，Capgo 插件检查是否有新的更新可用。

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

3. 下载完成后，Capgo 等待用户将应用程序置于后台或完全杀死它。

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

此流程确保用户始终在运行最新版本的应用程序，而无需被更新提示或被迫等待下载。

提示

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

为什么采用这种方法?

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

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

• 在会话之间，更新会被应用得非常顺滑，因此应用程序启动的体验总是新鲜的。

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

主要的缺点是，如果用户在应用程序更新之间快速切换到后台并恢复应用程序，他们可能会丢失任何未保存的状态。

为了减轻这种情况，我们建议：

• 频繁保存状态并在应用程序恢复时优雅地恢复它。

• 避免频繁更新应用程序状态的很大部分。

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

定制更新应用的时间

在某些情况下，您可能希望更控制地确定更新何时应用。例如，您可能希望确保用户完成正在进行的流程后再更新，或者与服务器端更改协调应用更新。

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 policy in your Capacitor config.

Recommended: Use Delta (Manifest) Updates with Instant Apply

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

Delta (manifest) updates

• 仅下载更改的文件而不是整个捆绑包，这在更新立即应用于用户正在使用的应用时尤其重要。为什么即时应用模式中的此项重要
• 更快的更新:较小的下载意味着更新速度快，减少用户看到的加载屏幕时间
• 更好的移动体验：: 只下载了修改过的文件，既节省了你的数据，也节省了你的用户的数据

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

要启用 Delta (清单) 更新，仅需在上传捆绑包时使用 --delta 标志：

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

了解更多在 Delta (manifest) 更新文档.

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

• false 或 'off': 禁用自动更新
• true 或 'atBackground' (默认): 在应用切换到后台时自动下载并应用
• 'atInstall': 在新安装或原生应用更新后立即应用，否则使用后台流程
• 'onLaunch': 在应用启动后立即应用，否则在启动检查后使用后台流程
• 'always': 在 Auto Update 运行时立即应用
• '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 不兼容立即应用模式。

与 autoUpdate: 'always', Capgo 将在更新检查期间下载完成时立即应用更新，即使用户正在使用应用程序。 没有启用周期性检查的更新将只在应用程序启动或从后台恢复时应用。

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

注意

在使用即时应用模式时， autoSplashscreen，您必须设置 launchAutoHide: false 在SplashScreen配置中（如上所示）

以防止SplashScreen在更新过程完成后自动隐藏。这确保您有完全控制权，决定何时隐藏SplashScreen。

If you want Capgo to check and download updates automatically but never apply them automatically, use 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 appReady 事件在应用程序完成初始化和应用任何待处理更新后只会触发一次。这是显示应用程序 UI 的安全点，因为它确保用户将看到最新版本。

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

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

使用即时应用模式可以有助于快速修复关键错误或安全漏洞，但它会带来一些权衡：

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

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

• 使用 autoSplashscreen: true 进行最简单的设置，或者手动处理 appReady 事件以实现自定义逻辑。
• 设置 keepUrlPathAfterReload 为了保持用户在应用中的位置。 true 在需要时保存和恢复应用状态，以避免丢失用户进度。
• 彻底测试应用程序更新行为，以确保没有突然的过渡、丢失的状态或混乱的位置变化。
• 在大多数情况下，默认更新行为提供了最好的平衡，即快速交付更新并最小化干扰。但是，对于具有特定需求的应用程序，__CAPGO_KEEP_0__ 提供了自定义更新何时和如何应用的灵活性。

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.