capgo-live-updates

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capgo Live Updates for Capacitor

为Capacitor应用提供Capgo实时更新

Deploy updates to your Capacitor app instantly without waiting for app store review.

无需等待应用商店审核，即可即时向你的Capacitor应用部署更新。

When to Use This Skill

何时使用本技能

User wants live/OTA updates
User asks about Capgo
User wants to skip app store review
User needs to push hotfixes quickly
User wants A/B testing or staged rollouts

用户需要实时/OTA更新
用户询问Capgo相关内容
用户希望跳过应用商店审核
用户需要快速推送热修复
用户想要进行A/B测试或分阶段发布

What is Capgo?

什么是Capgo？

Capgo is a live update service for Capacitor apps that lets you:

Push JavaScript/HTML/CSS updates instantly
Skip app store review for web layer changes
Roll back bad updates automatically
A/B test features with channels
Monitor update analytics

Note: Native code changes (Swift/Kotlin/Java) still require app store submission.

Capgo是为Capacitor应用提供的实时更新服务，你可以：

即时推送JavaScript/HTML/CSS更新
针对Web层变更跳过应用商店审核
自动回滚有问题的更新
通过渠道进行功能A/B测试
监控更新分析数据

注意：原生代码变更（Swift/Kotlin/Java）仍需提交至应用商店审核。

Getting Started

入门指南

Step 1: Create a Capgo Account

步骤1：创建Capgo账户

Go to https://capgo.app
Click "Sign Up" or "Get Started"
Sign up with GitHub, Google, or email
Choose a plan:
- Free: 1 app, 500 updates/month
- Solo: $14/mo, unlimited updates
- Team: $49/mo, team features
- Enterprise: Custom pricing

访问 https://capgo.app
点击 "注册" 或 "开始使用"
使用GitHub、Google或邮箱注册
选择套餐：
- 免费版：1个应用，每月500次更新
- 个人版：14美元/月，无限次更新
- 团队版：49美元/月，包含团队协作功能
- 企业版：定制定价

Step 2: Install the CLI

步骤2：安装CLI

bash

bun add -g @capgo/cli

bash

bun add -g @capgo/cli

Step 3: Login to Capgo

步骤3：登录Capgo

bash

capgo login

bash

capgo login

Opens browser to authenticate

打开浏览器进行身份验证


Or use API key:
```bash
capgo login --apikey YOUR_API_KEY


或使用API密钥登录：
```bash
capgo login --apikey YOUR_API_KEY

Step 4: Initialize Your App

步骤4：初始化你的应用

bash

cd your-capacitor-app
capgo init

This will:

Create app in Capgo dashboard
Add
```
@capgo/capacitor-updater
```
to your project
Configure capacitor.config.ts
Set up your first channel

bash

cd your-capacitor-app
capgo init

此命令将：

在Capgo控制台中创建应用
向你的项目添加
```
@capgo/capacitor-updater
```
配置capacitor.config.ts
设置你的第一个渠道

Step 5: Install the Plugin

步骤5：安装插件

If not installed automatically:

bash

bun add @capgo/capacitor-updater
bunx cap sync

如果未自动安装：

bash

bun add @capgo/capacitor-updater
bunx cap sync

Configuration

配置

Basic Configuration

基础配置

typescript

// capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.yourapp.id',
  appName: 'Your App',
  webDir: 'dist',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,  // Enable automatic updates
    },
  },
};

export default config;

typescript

// capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.yourapp.id',
  appName: 'Your App',
  webDir: 'dist',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,  // 启用自动更新
    },
  },
};

export default config;

Advanced Configuration

高级配置

typescript

// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
    // Update behavior
    resetWhenUpdate: true,           // Reset to built-in on native update
    updateUrl: 'https://api.capgo.app/updates', // Default
    statsUrl: 'https://api.capgo.app/stats',    // Analytics

    // Channels
    defaultChannel: 'production',

    // Update timing
    periodCheckDelay: 600,           // Check every 10 minutes (seconds)
    delayConditionsFail: false,      // Don't delay on condition fail

    // Private updates (enterprise)
    privateKey: 'YOUR_PRIVATE_KEY',  // For encrypted updates
  },
},

typescript

// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
    // 更新行为
    resetWhenUpdate: true,           // 原生更新时重置为内置版本
    updateUrl: 'https://api.capgo.app/updates', // 默认地址
    statsUrl: 'https://api.capgo.app/stats',    // 分析数据地址

    // 渠道设置
    defaultChannel: 'production',

    // 更新检查时机
    periodCheckDelay: 600,           // 每10分钟检查一次（单位：秒）
    delayConditionsFail: false,      // 条件不满足时不延迟检查

    // 私有更新（企业版）
    privateKey: 'YOUR_PRIVATE_KEY',  // 用于加密更新
  },
},

Implementing Updates

实现更新

Automatic Updates (Recommended)

自动更新（推荐）

With

autoUpdate: true

, updates are automatic:

typescript

// app.ts - Just notify when ready
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Tell Capgo the app loaded successfully
// This MUST be called within 10 seconds of app start
CapacitorUpdater.notifyAppReady();

Important: Always call

notifyAppReady()

. If not called within 10 seconds, Capgo assumes the update failed and rolls back.

当

autoUpdate: true

时，更新将自动进行：

typescript

// app.ts - 仅在就绪时发送通知
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 告知Capgo应用已成功加载
// 必须在应用启动后10秒内调用此方法
CapacitorUpdater.notifyAppReady();

重要提示：务必调用

notifyAppReady()

。如果10秒内未调用，Capgo将认为更新失败并自动回滚。

Manual Updates

手动更新

For more control:

typescript

// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: false,  // Disable auto updates
  },
},

typescript

// update-service.ts
import { CapacitorUpdater } from '@capgo/capacitor-updater';

class UpdateService {
  async checkForUpdate() {
    // Check for available update
    const update = await CapacitorUpdater.getLatest();

    if (!update.url) {
      console.log('No update available');
      return null;
    }

    console.log('Update available:', update.version);
    return update;
  }

  async downloadUpdate(update: any) {
    // Download the update bundle
    const bundle = await CapacitorUpdater.download({
      url: update.url,
      version: update.version,
    });

    console.log('Downloaded:', bundle.id);
    return bundle;
  }

  async installUpdate(bundle: any) {
    // Set as next version (applies on next app start)
    await CapacitorUpdater.set(bundle);
    console.log('Update will apply on next restart');
  }

  async installAndReload(bundle: any) {
    // Set and reload immediately
    await CapacitorUpdater.set(bundle);
    await CapacitorUpdater.reload();
  }
}

如需更多控制权：

typescript

// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: false,  // 禁用自动更新
  },
},

typescript

// update-service.ts
import { CapacitorUpdater } from '@capgo/capacitor-updater';

class UpdateService {
  async checkForUpdate() {
    // 检查是否有可用更新
    const update = await CapacitorUpdater.getLatest();

    if (!update.url) {
      console.log('暂无可用更新');
      return null;
    }

    console.log('发现可用更新:', update.version);
    return update;
  }

  async downloadUpdate(update: any) {
    // 下载更新包
    const bundle = await CapacitorUpdater.download({
      url: update.url,
      version: update.version,
    });

    console.log('下载完成:', bundle.id);
    return bundle;
  }

  async installUpdate(bundle: any) {
    // 设置为下次启动版本（应用重启后生效）
    await CapacitorUpdater.set(bundle);
    console.log('更新将在下次应用启动时生效');
  }

  async installAndReload(bundle: any) {
    // 设置并立即重启应用
    await CapacitorUpdater.set(bundle);
    await CapacitorUpdater.reload();
  }
}

Update with User Prompt

带用户提示的更新

typescript

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

async function checkUpdate() {
  const update = await CapacitorUpdater.getLatest();

  if (!update.url) return;

  const { value } = await Dialog.confirm({
    title: 'Update Available',
    message: `Version ${update.version} is available. Update now?`,
  });

  if (value) {
    // Show loading indicator
    showLoading('Downloading update...');

    const bundle = await CapacitorUpdater.download({
      url: update.url,
      version: update.version,
    });

    hideLoading();

    // Apply and reload
    await CapacitorUpdater.set(bundle);
    await CapacitorUpdater.reload();
  }
}

typescript

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

async function checkUpdate() {
  const update = await CapacitorUpdater.getLatest();

  if (!update.url) return;

  const { value } = await Dialog.confirm({
    title: '发现可用更新',
    message: `版本 ${update.version} 已可用。立即更新？`,
  });

  if (value) {
    // 显示加载指示器
    showLoading('正在下载更新...');

    const bundle = await CapacitorUpdater.download({
      url: update.url,
      version: update.version,
    });

    hideLoading();

    // 应用更新并重启
    await CapacitorUpdater.set(bundle);
    await CapacitorUpdater.reload();
  }
}

Listen for Update Events

监听更新事件

typescript

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

// Update downloaded
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Update available:', info.bundle.version);
});

// Download progress
CapacitorUpdater.addListener('downloadProgress', (progress) => {
  console.log('Download:', progress.percent, '%');
});

// Update failed
CapacitorUpdater.addListener('updateFailed', (info) => {
  console.error('Update failed:', info.bundle.version);
});

// App ready
CapacitorUpdater.addListener('appReady', () => {
  console.log('App is ready');
});

typescript

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

// 更新已下载
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('发现可用更新:', info.bundle.version);
});

// 下载进度
CapacitorUpdater.addListener('downloadProgress', (progress) => {
  console.log('下载进度:', progress.percent, '%');
});

// 更新失败
CapacitorUpdater.addListener('updateFailed', (info) => {
  console.error('更新失败:', info.bundle.version);
});

// 应用就绪
CapacitorUpdater.addListener('appReady', () => {
  console.log('应用已就绪');
});

Deploying Updates

部署更新

Deploy via CLI

通过CLI部署

bash

undefined

bash

undefined

Build your web app

构建你的Web应用

bun run build

Upload to Capgo

上传至Capgo

capgo upload

Upload to specific channel

上传至指定渠道

capgo upload --channel beta

Upload with version

指定版本上传

capgo upload --bundle 1.2.3

undefined

capgo upload --bundle 1.2.3

undefined

Deploy via CI/CD

通过CI/CD部署

GitHub Actions

yaml

undefined

yaml

undefined

.github/workflows/deploy.yml

name: Deploy to Capgo

on: push: branches: [main]

jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - uses: oven-sh/setup-bun@v1

  - name: Install dependencies
    run: bun install

  - name: Build
    run: bun run build

  - name: Deploy to Capgo
    run: bunx @capgo/cli upload
    env:
      CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

undefined

name: 部署至Capgo

on: push: branches: [main]

jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - uses: oven-sh/setup-bun@v1

  - name: 安装依赖
    run: bun install

  - name: 构建应用
    run: bun run build

  - name: 部署至Capgo
    run: bunx @capgo/cli upload
    env:
      CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

undefined

GitLab CI

yaml

undefined

yaml

undefined

.gitlab-ci.yml

deploy: stage: deploy image: oven/bun script: - bun install - bun run build - bunx @capgo/cli upload only: - main variables: CAPGO_TOKEN: $CAPGO_TOKEN

undefined

deploy: stage: deploy image: oven/bun script: - bun install - bun run build - bunx @capgo/cli upload only: - main variables: CAPGO_TOKEN: $CAPGO_TOKEN

undefined

Channels and Staged Rollouts

渠道与分阶段发布

Create Channels

创建渠道

bash

undefined

bash

undefined

Create beta channel

创建beta渠道

capgo channel create beta

Create staging channel

创建staging渠道

capgo channel create staging

undefined

capgo channel create staging

undefined

Deploy to Channels

部署至指定渠道

bash

undefined

bash

undefined

Deploy to beta (internal testing)

部署至beta渠道（内部测试）

capgo upload --channel beta

Promote to production

推广至生产渠道

capgo upload --channel production

undefined

capgo upload --channel production

undefined

Staged Rollout

分阶段发布

In Capgo dashboard:

Go to Channels > production
Set rollout percentage (e.g., 10%)
Monitor analytics
Increase to 50%, then 100%

在Capgo控制台中：

进入渠道 > production
设置发布百分比（例如：10%）
监控分析数据
逐步提升至50%，再到100%

Device-Specific Channels

设备专属渠道

typescript

// Assign device to channel
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// For beta testers
await CapacitorUpdater.setChannel({ channel: 'beta' });

// For production users
await CapacitorUpdater.setChannel({ channel: 'production' });

typescript

// 为设备分配渠道
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 为Beta测试者分配
await CapacitorUpdater.setChannel({ channel: 'beta' });

// 为生产用户分配
await CapacitorUpdater.setChannel({ channel: 'production' });

Rollback and Version Management

回滚与版本管理

Automatic Rollback

自动回滚

notifyAppReady()

isn't called within 10 seconds, Capgo automatically rolls back to the previous working version.

如果10秒内未调用

notifyAppReady()

，Capgo将自动回滚至上一个可用版本。

Manual Rollback

手动回滚

bash

undefined

bash

undefined

List available versions

列出可用版本

capgo bundle list

Rollback to specific version

回滚至指定版本

capgo bundle revert --bundle 1.2.2 --channel production

undefined

capgo bundle revert --bundle 1.2.2 --channel production

undefined

In-App Rollback

应用内回滚

typescript

// Get list of downloaded bundles
const bundles = await CapacitorUpdater.list();

// Rollback to built-in version
await CapacitorUpdater.reset();

// Delete a specific bundle
await CapacitorUpdater.delete({ id: 'bundle-id' });

typescript

// 获取已下载的更新包列表
const bundles = await CapacitorUpdater.list();

// 回滚至内置版本
await CapacitorUpdater.reset();

// 删除指定更新包
await CapacitorUpdater.delete({ id: 'bundle-id' });

Self-Hosted Option

自托管选项

For enterprise or privacy requirements:

bash

undefined

针对企业或隐私需求：

bash

undefined

Install self-hosted Capgo

安装自托管Capgo

docker run -d
-p 8080:8080
-e DATABASE_URL=postgres://...
capgo/capgo-server


Configure app to use self-hosted:

```typescript
// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
    updateUrl: 'https://your-server.com/updates',
    statsUrl: 'https://your-server.com/stats',
  },
},

docker run -d
-p 8080:8080
-e DATABASE_URL=postgres://...
capgo/capgo-server


配置应用使用自托管服务：

```typescript
// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
    updateUrl: 'https://your-server.com/updates',
    statsUrl: 'https://your-server.com/stats',
  },
},

Security

安全

Encrypted Updates

加密更新

For sensitive apps, enable encryption:

bash

undefined

针对敏感应用，启用加密：

bash

undefined

Generate key pair

生成密钥对

capgo key create

Upload with encryption

加密后上传

capgo upload --key-v2


Configure in app:

```typescript
// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
    privateKey: 'YOUR_PRIVATE_KEY',
  },
},

capgo upload --key-v2


在应用中配置：

```typescript
// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
    privateKey: 'YOUR_PRIVATE_KEY',
  },
},

Code Signing

代码签名

Verify updates are from trusted source:

bash

undefined

验证更新来自可信来源：

bash

undefined

Sign bundle

签名更新包

capgo upload --sign

Verify signature in app

在应用中验证签名

capgo key verify

undefined

capgo key verify

undefined

Monitoring and Analytics

监控与分析

Dashboard Metrics

控制台指标

In Capgo dashboard, view:

Active devices
Update success rate
Rollback rate
Version distribution
Error logs

在Capgo控制台中，你可以查看：

活跃设备数
更新成功率
回滚率
版本分布
错误日志

Custom Analytics

自定义分析

typescript

// Track custom events
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Get current bundle info
const current = await CapacitorUpdater.current();
console.log('Current version:', current.bundle.version);

// Get download stats
const stats = await CapacitorUpdater.getBuiltinVersion();

typescript

// 跟踪自定义事件
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 获取当前更新包信息
const current = await CapacitorUpdater.current();
console.log('当前版本:', current.bundle.version);

// 获取内置版本统计数据
const stats = await CapacitorUpdater.getBuiltinVersion();

Troubleshooting

故障排除

Issue: Updates Not Applying

问题：更新未生效

Check
```
notifyAppReady()
```
is called
Verify app ID matches Capgo dashboard
Check channel assignment
Review Capgo dashboard logs

检查是否调用了
```
notifyAppReady()
```
验证应用ID与Capgo控制台中的一致
检查渠道分配是否正确
查看Capgo控制台日志

Issue: Rollback Loop

问题：回滚循环

App crashes before
```
notifyAppReady()
```
Fix: Ensure
```
notifyAppReady()
```
is called early
Temporarily disable updates to debug

应用在调用
```
notifyAppReady()
```
前崩溃
修复方法：确保尽早调用
```
notifyAppReady()
```
临时禁用更新以进行调试

Issue: Slow Downloads

问题：下载缓慢

Enable delta updates (automatic)
Optimize bundle size
Use CDN (enterprise)

启用增量更新（自动开启）
优化更新包大小
使用CDN（企业版）

Best Practices

最佳实践

Always call
notifyAppReady()
- First thing after app initializes
Test updates on beta channel first - Never push untested to production
Use semantic versioning - Makes rollback easier
Monitor rollback rate - High rate indicates quality issues
Implement error boundary - Catch crashes before rollback
Keep native code stable - Native changes need app store

务必调用
notifyAppReady()
- 应用初始化后首先调用此方法
先在beta渠道测试更新 - 切勿直接推送未测试的更新至生产渠道
使用语义化版本控制 - 便于回滚操作
监控回滚率 - 高回滚率表明存在质量问题
实现错误边界 - 在回滚前捕获崩溃问题
保持原生代码稳定 - 原生代码变更仍需提交至应用商店

Resources

资源

Capgo Documentation: https://capgo.app/docs
Capgo Dashboard: https://web.capgo.app
Plugin GitHub: https://github.com/Cap-go/capacitor-updater
Discord Community: https://discord.gg/capgo

Capgo文档：https://capgo.app/docs
Capgo控制台：https://web.capgo.app
插件GitHub仓库：https://github.com/Cap-go/capacitor-updater
Discord社区：https://discord.gg/capgo