更新行为

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

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

默认更新流程

Capgo的默认行为是：

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

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

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

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

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

提示

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

Why This Approach?

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

• 用户不会被更新提示打断，也不必在会话中等待下载。

• 更新在会话之间顺利应用，因此启动应用的体验始终新鲜。

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

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

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

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

• 避免修改应用状态的大部分内容的非常频繁的更新。

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

自定义更新何时应用

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

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.

Recommended: Use Delta (Manifest) Updates with Instant Apply

在使用立即应用模式时，我们 强烈推荐使用 简化 Delta (manifest) 更新 以最小化下载时间并改善用户体验。 Delta (manifest) 更新仅下载更改的文件，而不是整个捆绑包，这在更新立即应用于用户正在使用的应用程序时尤其重要。

为什么这对于即时应用模式很重要：

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

当 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': 在应用首次安装或原生应用更新后立即应用，否则使用后台流程
• 'onLaunch': 在应用启动时立即应用，否则在启动检查后使用后台流程
• '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 不兼容

使用 autoUpdate: 'always', Capgo 将在更新检查期间下载完成时立即应用更新，即使用户正在使用应用程序。没有启用定期检查，这意味着更新将仅在应用程序启动或从后台恢复时应用。

注意，由于 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();

在应用程序完成初始化和应用任何待处理更新后，事件将触发一次。这是显示应用程序 UI 的安全点，因为它确保用户将看到最新版本。 appReady 除了处理事件外，我们建议在使用即时应用模式时将配置选项设置为""。这在应用程序重新加载时由于更新而保留当前 URL 路径，帮助维持用户在应用程序中的位置并减少混乱。

如果您不处理事件并在使用即时应用模式时设置""，用户可能会在应用程序更新时看到过时版本、被带回初始路由或看到闪烁的更新过程。 appReady 使用即时应用模式可以用于交付关键 bug 修复或安全补丁，但它带来了某些权衡： keepUrlPathAfterReload 如果您不正确处理启动屏幕（使用""或手动），用户可能会在应用程序更新时看到闪烁或加载状态。 true 事件

配置 appReady event and set keepUrlPathAfterReload 事件

配置

• 事件 autoSplashscreen 事件 appReady [__CAPGO_KEEP_0__]
• 如果更新修改了应用程序状态或 UI，用户可能会在会话中看到一个中断的变化。
• 如果 keepUrlPathAfterReload 未设置，用户可能会在应用程序中迷路。
• 您需要小心地处理保存和恢复状态，以确保平滑的过渡。

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

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

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

继续从更新行为

如果您正在使用 更新行为 来规划实时更新交付，连接它与 Capgo 实时更新 用于产品工作流程在Capgo 实时更新中 概览 用于概览中的实现细节 功能 对于功能的实现细节 更新类型 对于更新类型的实现细节 入门 对于入门的实现细节