更新行为

复制一个包含安装步骤和本插件的完整Markdown指南的设置提示。

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

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

默认更新流程

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

当应用程序切换到前台时，Capgo 插件会检查是否有新的更新可用。同时，应用程序保持打开状态，它还会在重复的定时器（默认10分钟）下再次检查一次。 periodCheckDelay 如果发现更新，它将在后台下载，而用户可以继续使用当前应用程序版本。
如果发现更新，它将在后台下载，而用户可以继续使用当前应用程序版本。
下载完成后，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: 等待下一次应用程序杀死事件再应用更新。

您可以混合和匹配这些条件来精确控制何时安装更新。

立即应用更新

对于关键更新或具有非常简单状态的应用程序，您可能希望立即应用更新，而不等待背景或杀死事件。Capgo通过在您的Capgo配置中启用 autoUpdate policy in your Capacitor config.

"atInstall", "onLaunch"立即应用所需：--delta，autoSplashscreen和SplashScreen "always" 立即应用所需：--delta，autoSplashscreen和SplashScreen 立即应用所需：--delta，autoSplashscreen和SplashScreen 立即应用所需：--delta，autoSplashscreen和SplashScreen

立即应用所需：--delta，autoSplashscreen和SplashScreen @capacitor/splash-screen 立即应用所需：--delta，autoSplashscreen和SplashScreen autoSplashscreen: true 立即应用所需：--delta，autoSplashscreen和SplashScreen SplashScreen.launchAutoHide: false. 在没有 Splash 插件的情况下，用户会看到应用更新时的闪烁或陈旧的 UI。

当 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' : 在每次前台检查时检查并下载自动，随后在下一次后台切换时应用更新
'atInstall': 在首次安装或原生应用商店更新后立即应用；否则使用 "atBackground" : 行为
'onLaunch': 在从杀死状态（冷启动）将应用带到前台时立即应用。第一次检查后，回退到 "atBackground" : 在每次前台转换时检查，并在有更新时立即应用
'always': 自动检查并下载，发出
'onlyDownload', 并且永远不会设置下一个捆绑包或自动应用更新 updateAvailable: 测试一个原生构建而不使用实时更新

: 在每次前台转换时检查，并在有更新时立即应用

查看测试原生构建而不使用实时更新用于原生版本、渠道策略和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 for instant apply with autoSplashscreen
    },
  },
};

export default config;

与 autoUpdate: 'always'，Capgo在每次前台转换时进行检查，并在下载完成时立即应用更新，即使用户正在使用应用。由 periodCheckDelay 可以在应用程序保持打开状态时触发相同的即刻应用行为。

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

。设置

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() 或显示自己的更新提示。

自动启动屏幕处理

即时应用模式（"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();

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

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

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

如果 @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.

继续更新行为

If you are using 更新行为 与 __CAPGO_KEEP_0__ Live Updates Capgo Live Updates Capgo Live Updates 为 __CAPGO_KEEP_0__ Live Updates 概览概览功能更新类型查看更新类型的实现细节开始使用查看开始使用的实现细节