自动更新

本文档将说明如何运行您的自动更新服务器。

提供您的 bundle

确保您的 bundle 通过 HTTPS 提供,并且服务器具有正确的 CORS 标头以允许应用下载更新。例如 https://myserver.com/app/updates/updates.json

如果您不熟悉提供 bundle,我们建议您尝试 Capgo Cloud 或在此处查看示例:

配置

将 updateUrl 添加到您的 capacitor.config.json。

{
  "plugins": {
    "CapacitorUpdater": {
      "updateUrl": "https://myserver.com/app/updates/updates.json",
    }
  }
}

更新 API

每次打开应用时,插件都会向您的 API 发出 POST 调用,主体如下:

interface AppInfos {
    "platform": "ios" | "android",
    "device_id": "UUID_of_device_unique_by_install",
    "app_id": "APPID_FROM_CAPACITOR_CONFIG",
    "custom_id": "your_custom_id_set_on_runtime",
    "plugin_version": "PLUGIN_VERSION",
    "version_build": "VERSION_NUMBER_FROM_NATIVE_CODE",
    "version_code": "VERSION_CODE_FROM_NATIVE_CODE",
    "version_name": "LAST_DOWNLOADER_VERSION" | "builtin"
    "version_os": "VERSION_OF_SYSTEM_OS",
    "is_emulator": boolean,
    "is_prod": boolean,
}

服务器 API 应以 JSON 格式响应 capacitor-updater 插件。如果需要更新,则使用此数据:

{
"version": "1.2.3",
"url": "https://myserver.com/app/updates/my-new-app-2.0.0.zip",
"checksum": "sha256_checksum_of_bundle"
}

在自动更新模式下,服务器应比较版本并返回正确的版本,如果存在 URL 键,插件将启动下载过程。

如果您添加 “message” 和 “error” 键,则不会设置版本,消息将显示在日志中。

version 键应采用 semver 格式。

zip 文件应在根目录有 index.html 文件,或者根目录只有一个文件夹,其中包含 index.html。

您可以使用 CLI 命令压缩您的 bundle:

npx @capgo/cli bundle zip --path [/path/to/my/bundle]

生成 Bundle 校验和

重要: 您必须使用 Capgo CLI 创建 bundle zip 文件。Capgo 插件需要特定的 zip 格式和结构,只有使用官方 CLI 工具才能保证。标准 zip 实用程序可能会创建不兼容的存档。

要为您的 bundle 生成校验和,请使用带有 --json 标志的 Capgo CLI zip 命令:

npx @capgo/cli bundle zip [appId] --json

此命令将:

创建与 Capgo 插件兼容的格式正确的 zip 文件
生成用于完整性验证的 SHA256 校验和
以 JSON 格式输出 bundle 信息

示例输出:

{
  "version": "1.2.3",
  "checksum": "a1b2c3d4e5f6789...",
  "size": 1234567
}

在您的 API 响应中使用此输出的 checksum 值,以确保插件可以在安装前验证 bundle 完整性。