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

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

核心要点：

• 什么是 Capgo？ An open-source platform for live updates in Capacitor 应用提供可靠的安全保障。
• 为什么需要 OTA 更新？ 节省时间，提升用户体验，并快速修复 Bug。
• 如何开始使用？
  • 安装 Capgo 插件: npm install @capgo/capacitor-updater
  • 使用 API 密钥配置您的应用。
  • 使用 “production” 或 “beta” 等频道进行定向发布。
• 高级功能： 端到端加密、错误处理以及 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].
• 更新策略：这些策略定义了更新的交付和应用方式，选项包括自动下载、安装时机和用户提示 [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 Updates

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

基础配置步骤

首先在您的 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);
}

对于关键更新，你可以在继续操作前向用户发送 prompt：

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 规则

仅靠技术修复还不够——您的更新还需要符合应用商店的指南。

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 的实现细节， 合规性 了解合规部分的实现细节， Capgo 安全扫描器 了解 Capgo Security Scanner 的产品工作流， Capgo 安全 用于 Capgo 安全的产品工作流，以及 Capgo 信任中心 用于 Capgo 信任中心的产品工作流。