Cordova Updater 入门指南

复制一条配置 prompt，包含安装步骤和该插件的完整 Markdown 指南。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/cordova-updater`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/cordova-updater/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

本指南将带你完成添加 @capgo/cordova-updater 到 Cordova 应用，这样就能在 iOS 和 Android 上接收 Capgo live updates。

前提条件

Cordova CLI 12+
Cordova Android 13+ 和/或 Cordova iOS 7+
拥有 Capgo 账号 (capgo.app/register)

安装

从 npm 安装插件，并传入您的 Capgo App ID：

cordova plugin add @capgo/cordova-updater --variable APP_ID=YOUR_CAPGO_APP_ID

可选：在安装时覆盖默认配置 (变量与 Capacitor updater 相同)：

cordova plugin add @capgo/cordova-updater \
  --variable APP_ID=YOUR_CAPGO_APP_ID \
  --variable DEFAULT_CHANNEL=production \
  --variable UPDATE_URL=https://plugin.capgo.app/updates \
  --variable AUTO_UPDATE=atBackground

修改插件变量后，请准备 Native Build 项目：
终端窗口
```
cordova prepare android ios
```

快速入门

document.addEventListener('deviceready', async () => {
  await cordova.plugins.Updater.notifyAppReady();
});

常见坑点

请勿将此插件与 cordova-plugin-ionic-webview 配合使用。
调用 notifyAppReady() bundle 一加载完就执行——赶在繁重 UI 工作拖慢回滚窗口之前。
请确保 Cordova scheme 设置正确。

JavaScript 用法

在 deviceready，该插件可通过以下方式使用： cordova.plugins.Updater:

document.addEventListener('deviceready', async () => {
  const { Updater } = cordova.plugins;

  await Updater.notifyAppReady();

  const latest = await Updater.getLatest();
  if (latest.url && !latest.error) {
    const bundle = await Updater.download({
      url: latest.url,
      version: latest.version,
      checksum: latest.checksum,
    });

    await Updater.next({ id: bundle.id });
  }
});

npm 包已内置 TypeScript 类型：

import type { UpdaterPlugin } from '@capgo/cordova-updater';

declare const cordova: { plugins: { Updater: UpdaterPlugin } };

需要 Cordova Android 13+，以便 WebView 通过默认 https://localhost/ scheme 提供服务。
该插件会注册一个 CordovaPluginPathHandler 用于提供下载的 bundle 资源。

需要使用默认 scheme 的 app://localhost/ Cordova iOS 7+。
该插件实现了 CDVPluginSchemeHandler 以拦截 bundle 请求。

上传你的第一个 bundle

构建你的 web 资源，然后使用 Capgo CLI 进行上传（工作流与 Capacitor 相同）：

bun run build
npx @capgo/cli@latest bundle upload --channel=production

下一步

将设置与 Capacitor updater 配置进行对比 — 大多数选项都对应 plugin.xml 变量。
读取 Live update 兼容性在发布 Native Build 插件变更之前。
稍后迁移到 Capacitor？请保持相同的 Capgo App ID 和 channels；仅需更换客户端插件包。