如何使用 Capgo 文档进行 OTA 更新

想要更快的速度 应用更新 且无需等待应用商店审核？ Capgo 让您能够立即向用户推送安全的 Over-the-Air (OTA) 更新。跳过应用商店审核，轻松保持应用处于最新状态。

核心要点：

• 什么是 Capgo？ 专为应用提供 Live Update 的 Capacitor 开源平台。
• 为什么选择 OTA 更新？ 节省时间，提升用户体验，并快速修复 Bug。
• 如何开始使用？
  • 安装 Capgo 插件: npm install @capgo/capacitor-updater
  • 使用 API 密钥配置您的应用。
  • 使用 “production” 或 “beta” 等 Channel 进行定向发布。
• 高级功能： 端到端加密、错误处理以及 CI/CD 集成。

Capgo 的文档 (capgo.app/docs) 提供了从安装、安全到故障排除的分步指南。从基础安装到高级配置，它是你实现无缝更新的首选指南。

Capgo用于 Live update 的 CapacitorJs 插件

使用 Capgo 文档

在进行 OTA 更新时，高效查阅文档至关重要 Capgo 的文档为在 Capacitor 应用中集成 Live Update 提供了详细指导。

文档获取途径

你可以在以下地址访问 Capgo 的文档： capgo.app/docs [1]. 文档按具体用途划分为以下章节：

核心术语与概念

以下是你将遇到的关键术语：

• 渠道：这些是用于控制版本分发的更新流。例如，你可以设置 “production”、“beta” 和 “staging” 等渠道，以满足不同用户群体的需求 [4].
• 更新策略：这些策略定义了更新的交付和应用方式。选项包括自动下载、安装时机以及用户提示 (prompt) [1].
• App 状态监听器：这些组件用于追踪 App 当前处于前台还是后台状态 [4].
• Bundle：包含 App 新版本的打包更新文件，其中涵盖了资源文件、code 变更以及配置更新 [4].

Code 示例与教程

文档提供了示例 code 以简化集成过程。以下是一个使用 TypeScript/JavaScript 的基础示例：

import { CapacitorUpdater } from '@capgo/capacitor-updater'

// Initialize the updater
await CapacitorUpdater.notifyAppReady()

对于更高级的使用场景，文档中还包含了实际应用案例 [2][3]，例如：

• 通过切换渠道进行 A/B 测试
• 通过用户提示实现自定义更新流程
• 错误处理与回滚机制实现
• 将更新集成至 CI/CD pipeline

每个教程都会重点介绍性能考量与安全维度，助您做出明智决策。文档会定期更新，以包含最新的功能与最佳实践。 [1].

如需了解实现细节，请查看接下来的配置指南。

配置 OTA 更新

在 Capgo 中配置 OTA 更新以简化您的部署流程。遵循以下步骤和技巧，即可实现无忧配置。

基础配置步骤

首先在您的 Capacitor 项目中安装 Capgo plugin：

npm install @capgo/capacitor-updater
npx cap sync

接下来，更新您的 capacitor.config.json 文件，并填入您的 Capgo API 密钥:

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": true,
      "apiKey": "YOUR_API_KEY_HERE"
    }
  }
}

接着，在应用的主文件中初始化 updater 以检测更新：

import { CapacitorUpdater } from '@capgo/capacitor-updater';
await CapacitorUpdater.notifyAppReady();

完成后，你可以设置 channels 来管理不同的更新流。

更新 Channel 设置

根据你的 更新通道 部署需求来组织：

若要向特定 Channel 上传更新，请使用 Capgo CLI:

npx @capgo/cli upload -c production

更新方式

Capgo 提供两种主要的更新处理方式：

自动更新 通过设置来启用自动更新 autoUpdate: true 在你的配置中。这能确保更新在后台自动应用，无需开发者进行额外操作。

手动更新 如果需要更强的控制权，你可以手动管理更新。使用以下模式来检查并应用更新：

// Check for updates
const update = await CapacitorUpdater.download();

// Install when ready
if (update) {
  await CapacitorUpdater.set(update);
}

对于关键更新，你可以在继续之前提示用户：

if (update.version > currentVersion) {
  const userConsent = await showUpdatePrompt();
  if (userConsent) {
    await CapacitorUpdater.set(update);
  }
}

你还可以通过自定义 ID 和 channel 来针对特定的用户群进行更新：

await CapacitorUpdater.setCustomId('beta-tester-123');
await CapacitorUpdater.setChannel('beta');

最后，请务必包含错误处理和回滚选项：

try {
  await CapacitorUpdater.set(update);
} catch (error) {
  await CapacitorUpdater.reset(); // Revert to the last working version
  console.error('Update failed:', error);
}

完成这些步骤后，你的 OTA 更新系统就准备就绪了。你可以进一步探索高级设置来定制更新流程。

sbb-itb-f9944d2

高级设置

提升你的 Capgo OTA 更新 配置体验，通过增加安全措施和灵活的更新配置。这些选项能在符合 App Store 指南的同时，确保安全顺畅的更新体验。

安全特性

Capgo 提供强大的安全协议，以保护您的 update bundles 并安全地交付给用户。平台对所有更新均采用基于公钥密码学的端到端加密 [1]。以下是启用关键安全特性的方法：

// Enable bundle verification
await CapacitorUpdater.setVerifyBundles(true);

// Configure encryption settings
await CapacitorUpdater.configure({
  encryption: {
    enabled: true,
    failOnError: true
  }
});

Bundle 保护系统的核心组件包括：

更新行为设置

你可以通过事件监听器和配置选项来自定义更新的推送与安装方式。使用以下设置来调整更新的时机和用户交互：

// Listen for when an update is available
CapacitorUpdater.addListener('updateAvailable', async (info) => {
  if (info.version > currentVersion) {
    // Custom update logic based on app state
    const isAppInactive = await checkAppState();
    if (isAppInactive) {
      await CapacitorUpdater.download();
    }
  }
});

// Monitor download completion
CapacitorUpdater.addListener('downloadComplete', (info) => {
  console.log(`Update ${info.version} ready to install`);
  // Implement custom installation timing if desired
});

对于分阶段发布，你可以直接通过 dashboard 或使用 code 来配置更新分发：

// Set custom update conditions for a gradual rollout
await CapacitorUpdater.configure({
  rollout: {
    percentage: 25, // Start with 25% of users
    timeInterval: 24 // Increase rollout percentage every 24 hours
  }
});

处理特定版本相关的行为：

// Handle version-specific update failures
CapacitorUpdater.addListener('updateFailed', async (info) => {
  if (info.error.code === 'VERSION_MISMATCH') {
    await CapacitorUpdater.reset(); // Revert to the last stable version
    // Optionally, handle error notification here
  }
});

这些设置可确保更新的可靠性，同时允许你根据应用需求定制流程。在将更新推送到生产环境之前，请务必在 Capgo 的 staging 环境中进行充分测试 [2].

问题排查指南

Capgo 的 error logs 和内置工具可帮助解决 OTA 更新难题，同时确保你的应用符合应用商店的相关要求。

常见问题与解决方案

以下是一些常见问题及其解决方案：

• 下载失败 症状: 下载卡住或无法完成。 解决方案: 请检查网络连接，确认更新 URL 是否有效，并添加重试机制以应对中断。

• 版本冲突 症状: 更新无法安装或导致 App 不稳定。 解决方案: 使用清晰的版本号以避免冲突，并实现回滚机制以确保安全。

• 安装错误 症状：更新失败或触发自动回滚。 解决方案：确保在成功更新后调用 notifyAppReady() 以防止回滚。

对于大于 50MB 的更新，将其拆分为较小的文件可以提升 Android 设备上的性能 [5].

使用详细的错误日志来尽早发现问题。例如，实现以下监听器：

CapacitorUpdater.addListener('updateFailed', (error) => {
  console.log(`Update failed: ${error.code}`);
  logUpdateError({
    errorCode: error.code,
    deviceInfo: error.device,
    timestamp: new Date().toISOString()
  });
});

通过将错误日志与预检相结合，您可以在专注于合规性之前有效地处理这些问题。

App Store 规则

仅靠技术修复是不够的——您的更新还需要符合 App Store 的指南。

Apple App Store 要求:

• 用户透明度: 清晰告知用户更新内容并征得其同意。
• 核心功能: 确保应用的核心功能在审核后保持完好。
• 安全措施: 使用安全的方式传输更新。

Android 端实现:

await CapacitorUpdater.configure({
  updateNotification: {
    title: "Update Available",
    message: "A new version is available. Please update to access the latest features.",
    requireUserConsent: true
  }
});

最佳实践:

• 版本控制逐步发布更新以减少冲突。
• 更新通知提供清晰且用户友好的更新提示。
• 安全性: 验证 bundle 的完整性并使用加密技术保护数据。

总结

本节总结了指南中的核心要点。

Capgo 的文档提供了清晰的指南，帮助开发者在符合应用商店规范的前提下，将 Live Update 集成到 Capacitor 应用中。

利用 Capgo 的资源，开发者可以实现以下核心功能： 端到端加密 和 CI/CD 集成，涵盖了从初始设置到高级配置的所有内容 [1].

核心实现领域

这些核心部分构成了 Capgo 更新管理系统的支柱。

Capgo 的 CLI 与分析工具简化了 更新管理 贯穿应用的整个生命周期 [1].

如需更多支持，您可以查看以下资源： API 文档, 示例项目，以及 社区论坛 [2].

继续阅读：如何使用 Capgo 文档进行 OTA 更新

如果你正在使用 如何使用 Capgo 文档进行 OTA 更新 以规划安全与合规，并将其与 加密 以了解 Encryption 中的实现细节， 合规性 有关 Compliance 中的实现细节， Capgo 安全扫描器 关于 Capgo Security Scanner 的产品工作流， Capgo 安全性 关于 Capgo Security 的产品工作流，以及 Capgo 信托中心 关于 Capgo Trust Center 的产品工作流。