更新行为

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

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

默认更新流程

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

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

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

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

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

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

提示

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通过在Capgo配置中设置 autoUpdate policy in your Capacitor config.

推荐：使用Delta（清单）更新进行即时应用

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

为什么即时应用模式中的此项很重要：

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

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

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

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

在 中了解更多关于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 when using instant apply with autoSplashscreen
    },
  },
};

export default config;

注意

重要: 只有实时应用模式才会在插件实际检查更新时应用更新。默认情况下，检查在应用切换到前台时运行，并在应用保持打开时以重复的时间间隔运行。 periodCheckDelay 控制该间隔（默认10分钟）。

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

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

注意事项

使用即时应用模式时， autoSplashscreen，必须在SplashScreen配置中（如上所示）设置 launchAutoHide: false 以防止更新过程完成后自动隐藏启动屏幕。这确保您有完全控制启动屏幕何时被隐藏的权利。

自动下载但不应用

如果您想让Capgo自动下载更新但不自动应用它们，请使用 autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

在此模式下，插件会在下载包后发出 updateAvailable 信号。您的应用程序可以决定何时调用 CapacitorUpdater.set() 或显示自己的更新提示。

自动启动屏幕处理

为了使即时应用模式更容易使用，Capgo 提供了一个选项，自动处理隐藏启动屏幕（自版本 7.6.0 开始可用）： autoSplashscreen 复制到剪贴板

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

启用时： autoSplashscreen 插件在应用更新时自动隐藏启动屏幕

• 插件在不需要更新时自动隐藏启动屏幕
• 您不需要手动监听
• 事件或调用 appReady 手动启动屏幕处理 SplashScreen.hide()

Section titled “手动启动屏幕处理”

如果您需要手动控制或自定义逻辑，可以禁用 autoSplashscreen 并自己处理:

import { CapacitorUpdater } from '@capgo/capacitor-updater';
import { SplashScreen } from '@capacitor/splash-screen';

CapacitorUpdater.addListener('appReady', () => {
  // Hide splash screen
  SplashScreen.hide();
});

CapacitorUpdater.notifyAppReady();

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

除了处理事件外，我们建议在使用即时应用模式时将配置选项设置为 appReady 以便在应用程序由于更新而重新加载时保留当前 URL 路径，帮助维持用户在应用程序中的位置并减少混乱。 keepUrlPathAfterReload 如果您不处理事件并在使用即时应用模式时设置 true ，用户可能会在应用程序更新期间看到过时版本、被带回初始路由或看到闪烁的更新过程。

事件 appReady 事件 keepUrlPathAfterReload 事件

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

• 如果您没有正确处理启动屏幕（使用或手动事件处理），用户可能会在更新应用时看到短暂的闪烁或加载状态： autoSplashscreen 如果更新修改了应用状态或UI，用户可能会在会话中间看到一个打断的变化： appReady 如果不设置，用户的位置可能会丢失，导致他们感到混乱：
• 您需要小心地处理保存和恢复状态，以确保平滑的过渡：
• 如果您启用即时应用，我们建议： keepUrlPathAfterReload 使用最简单的设置，或者手动处理事件，如果您需要自定义逻辑：
• handleSplashScreen

handleSplashScreen

• handleSplashScreenEvent autoSplashscreen: true handleSplashScreenEvent appReady handleSplashScreenEvent
• 设置 keepUrlPathAfterReload 到 true 为了保持用户在应用中的位置
• 保存和恢复应用状态以避免丢失用户进度
• 彻底测试应用更新行为以确保没有突然的过渡、丢失的状态或混乱的位置变化

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

继续从更新行为

如果您正在使用 更新行为 来规划实时更新交付，连接它到 Capgo实时更新 为 Capgo Live Updates 的产品工作流程而言 概述 概述的实现细节 功能 功能的实现细节 更新类型 更新类型的实现细节 开始使用 开始使用的实现细节