包

复制一个包含安装步骤和此插件的完整 Markdown 指南的设置提示。

捆绑包是 Capgo 的核心更新包。每个捆绑包包含构成应用内容的 Web 资产 (HTML、CSS、JS)。捆绑包管理器 API 允许您管理这些更新包，包括列出和删除它们。

理解捆绑包

捆绑包代表您的应用程序的特定捆绑包（版本）中的Web内容，并包括：

捆绑包（版本）: 语义版本号捆绑包的
校验和: 验证捆绑包完整性的唯一哈希
存储信息: 关于捆绑包存储位置和方式的详细信息
原生要求: 捆绑包所需的最低原生应用程序版本
元数据:

手动创建包（不含CLI）

Here’s how to create and upload bundles manually without using the Capgo CLI:

以下是手动创建和上传包的步骤，使用__CAPGO_KEEP_0 CAPGO_KEEP_1__不需要：

步骤 1：构建应用

npm run build

Step 2: Create Bundle Zip Using Same Packages as Capgo CLI

步骤 2：使用__CAPGO_KEEP_0__ __CAPGO_KEEP_1__相同的包创建包压缩文件（重要）: 使用相同的 JavaScript 包来确保兼容性，Capgo CLI 内部使用的包完全相同。

安装必需包

npm install adm-zip @tomasklaen/checksum

使用 JavaScript 创建 ZIP 包（与 Capgo CLI 相同）

注意：以下示例中， version 指的是 API 使用的包（版本）名称。

const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
const AdmZip = require('adm-zip');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

// Exact same implementation as Capgo CLI
function zipFileUnix(filePath) {
  const zip = new AdmZip();
  zip.addLocalFolder(filePath);
  return zip.toBuffer();
}

async function zipFileWindows(filePath) {
  console.log('Zipping file windows mode');
  const zip = new AdmZip();

  const addToZip = (folderPath, zipPath) => {
    const items = fs.readdirSync(folderPath);

    for (const item of items) {
      const itemPath = path.join(folderPath, item);
      const stats = fs.statSync(itemPath);

      if (stats.isFile()) {
        const fileContent = fs.readFileSync(itemPath);
        zip.addFile(path.join(zipPath, item).split(path.sep).join('/'), fileContent);
      } else if (stats.isDirectory()) {
        addToZip(itemPath, path.join(zipPath, item));
      }
    }
  };

  addToZip(filePath, '');
  return zip.toBuffer();
}

// Main zipFile function (exact same logic as CLI)
async function zipFile(filePath) {
  if (os.platform() === 'win32') {
    return zipFileWindows(filePath);
  } else {
    return zipFileUnix(filePath);
  }
}

async function createBundle(inputPath, outputPath, version) {
  // Create zip using exact same method as Capgo CLI
  const zipped = await zipFile(inputPath);

  // Write to file
  fs.writeFileSync(outputPath, zipped);

  // Calculate checksum using exact same package as CLI
  const checksum = await getChecksum(zipped, 'sha256');

  return {
    filename: path.basename(outputPath),
    version: version,
    size: zipped.length,
    checksum: checksum
  };
}

// Usage
async function main() {
  try {
    const result = await createBundle('./dist', './my-app-1.2.3.zip', '1.2.3');
    console.log('Bundle info:', JSON.stringify(result, null, 2));
  } catch (error) {
    console.error('Error creating bundle:', error);
  }
}

main();

步骤 3：使用相同的包计算 SHA256 校验和（与 CLI 相同）

const fs = require('node:fs');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

async function calculateChecksum(filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  // Use exact same package and method as Capgo CLI
  const checksum = await getChecksum(fileBuffer, 'sha256');
  return checksum;
}

// Usage
async function main() {
  const checksum = await calculateChecksum('./my-app-1.2.3.zip');
  console.log('Checksum:', checksum);
}

main();

步骤 4: 将包上传到您的存储

将您的 zip 文件上传到任何可通过网络访问的存储:

# Example: Upload to your server via scp
scp my-app-1.2.3.zip user@your-server.com:/var/www/bundles/

# Example: Upload to S3 using AWS CLI
aws s3 cp my-app-1.2.3.zip s3://your-bucket/bundles/

# Example: Upload via curl to a custom endpoint
curl -X POST https://your-storage-api.com/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@my-app-1.2.3.zip"

重要上述包必须是 通过 HTTPS URL 公开可访问（无需身份验证）。__CAPGO_KEEP_0__的服务器需要从此 URL 下载包。 via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

步骤 5: 将包注册到__CAPGO_KEEP_0__ __CAPGO_KEEP_1__

https://your-storage.com/bundles/my-app-1.2.3.zip
https://github.com/username/repo/releases/download/v1.2.3/bundle.zip
https://cdn.jsdelivr.net/gh/username/repo@v1.2.3/dist.zip

Step 5: Register Bundle with Capgo API

使用Capgo通过直接API调用注册外部包:

async function registerWithCapgo(appId, version, bundleUrl, checksum, apiKey) {
  const fetch = require('node-fetch');

  // Create bundle (version)
  const response = await fetch('https://api.capgo.app/bundle/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': apiKey
    },
    body: JSON.stringify({
      app_id: appId,
      version: version,
      external_url: bundleUrl,
      checksum: checksum
    })
  });

  if (!response.ok) {
    throw new Error(`Failed to create bundle: ${response.statusText}`);
  }

  const data = await response.json();
  console.log('Bundle created:', data);

  return data;
}

API 参数

参数	描述	必填
`app_id`	您的应用程序标识符	是
`version`	包（版本）语义版本例如，"1.2.3"	是
`external_url`	公开可访问 HTTPS URL，用于下载包（无需认证）	是
`checksum`	zip文件的SHA256校验和	是

包结构要求

您的包zip必须遵循以下要求：

根索引文件: 必须 index.html 根级别
Capacitor 集成: 必须调用 notifyAppReady() 在您的应用程序中 code
资源路径: 使用所有资源的相对路径

有效的包结构

bundle.zip
├── index.html
├── assets/
│   ├── app.js
│   └── styles.css
└── images/

完整的手动工作流程示例

一个简单的 Node.js 脚本来压缩、校验和上传到 Capgo:

const fs = require('node:fs');
const os = require('node:os');
const AdmZip = require('adm-zip');
const { checksum: getChecksum } = require('@tomasklaen/checksum');
const fetch = require('node-fetch');

async function deployToCapgo() {
  const APP_ID = 'com.example.app';
  const VERSION = '1.2.3';
  const BUNDLE_URL = 'https://your-storage.com/bundles/app-1.2.3.zip';
  const API_KEY = process.env.CAPGO_API_KEY;

  // 1. Create zip (same as Capgo CLI)
  const zip = new AdmZip();
  zip.addLocalFolder('./dist');
  const zipped = zip.toBuffer();

  // 2. Calculate checksum (same as Capgo CLI)
  const checksum = await getChecksum(zipped, 'sha256');
  console.log('Checksum:', checksum);

  // 3. Upload to your storage (replace with your upload logic)
  // fs.writeFileSync('./bundle.zip', zipped);
  // ... upload bundle.zip to your storage ...

  // 4. Register with Capgo API
  const response = await fetch('https://api.capgo.app/bundle/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': API_KEY
    },
    body: JSON.stringify({
      app_id: APP_ID,
      version: VERSION,
      external_url: BUNDLE_URL,
      checksum: checksum
    })
  });

  if (!response.ok) {
    throw new Error(`Failed: ${response.statusText}`);
  }

  console.log('Bundle registered with Capgo!');
}

deployToCapgo().catch(console.error);

安装依赖项：

npm install adm-zip @tomasklaen/checksum node-fetch

校验和验证

JavaScript 校验和计算（与 Capgo CLI 相同）

使用与 Capgo CLI 内部相同的包和方法：

const fs = require('node:fs');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

async function calculateChecksum(filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  // Use exact same package and method as Capgo CLI
  const checksum = await getChecksum(fileBuffer, 'sha256');
  return checksum;
}

// Verify checksum matches
async function verifyChecksum(filePath, expectedChecksum) {
  const actualChecksum = await calculateChecksum(filePath);
  const isValid = actualChecksum === expectedChecksum;

  console.log(`File: ${filePath}`);
  console.log(`Expected: ${expectedChecksum}`);
  console.log(`Actual:   ${actualChecksum}`);
  console.log(`Valid:    ${isValid}`);

  return isValid;
}

// Usage
async function main() {
  const bundleChecksum = await calculateChecksum('./my-app-1.2.3.zip');
  console.log('SHA256 Checksum:', bundleChecksum);
}

main();

校验和重要性

包装完整性: 确保在传输过程中包装没有被损坏
API 验证: Capgo 在接受包装之前验证校验和
插件验证: 移动插件在应用更新之前验证校验和

最佳实践

包装（版本）管理: 使用语义版本一致地
存储优化: 定期清除未使用的捆绑包
捆绑包 (版本) 兼容性: 设置适当的原生最低版本要求
备份策略: 保持关键捆绑包 (版本) 的备份

端点

GET

https://api.capgo.app/bundle/

查询参数

Endpoints

app_id: 必填项。应用程序的 ID
page: 可选项。分页的页码

Response Type

interface Bundle {
  app_id: string
  bucket_id: string | null
  checksum: string | null
  created_at: string | null
  deleted: boolean
  external_url: string | null
  id: number
  minUpdateVersion: string | null
  name: string
  native_packages: Json[] | null
  owner_org: string
  r2_path: string | null
  session_key: string | null
  storage_provider: string
  updated_at: string | null
  user_id: string | null
}

Section titled “Example Request”

# Get all bundles
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123"

# Get next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123&page=1"

Section titled “Example Response”

{
  "data": [
    {
      "id": 1,
      "app_id": "app_123",
      "name": "1.0.0",
      "checksum": "abc123...",
      "minUpdateVersion": "1.0.0",
      "storage_provider": "r2",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "deleted": false,
      "owner_org": "org_123",
      "user_id": "user_123"
    }
  ]
}

DELETE

https://api.capgo.app/bundle/

删除一个或所有应用程序的包。请谨慎操作，因为此操作不可逆。

查询参数

删除特定包时：

interface BundleDelete {
  app_id: string
  version: string
}

删除所有包时：

interface BundleDeleteAll {
  app_id: string
}

示例请求

# Delete specific bundle
curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version": "1.0.0"
  }' \
  https://api.capgo.app/bundle/

# Delete all bundles
curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123"
  }' \
  https://api.capgo.app/bundle/

成功响应

{
  "status": "ok"
}

POST

https://api.capgo.app/bundle/

创建一个带有外部 URL 的新捆绑包。

请求体

interface CreateBundleBody {
  app_id: string
  version: string
  external_url: string // Must be publicly accessible HTTPS URL
  checksum: string
}

示例请求

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "version": "1.2.3",
    "external_url": "https://your-storage.com/bundles/app-1.2.3.zip",
    "checksum": "a1b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcd"
  }' \
  https://api.capgo.app/bundle/

成功响应

{
  "status": "ok"
}

POST (元数据)

https://api.capgo.app/bundle/metadata

更新包元数据，例如链接和注释信息。

请求体

interface UpdateMetadataBody {
  app_id: string
  version_id: number // bundle (version) id
  link?: string
  comment?: string
}

示例请求

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version_id": 456,
    "link": "https://github.com/myorg/myapp/releases/tag/v1.0.0",
    "comment": "Fixed critical bug in authentication"
  }' \
  https://api.capgo.app/bundle/metadata

成功响应

{
  "status": "success"
}

PUT

https://api.capgo.app/bundle/

将一个包设置到一个特定的频道。这个操作将一个包（版本）与一个频道关联起来，用于分发。

请求体

interface SetChannelBody {
  app_id: string
  version_id: number // bundle (version) id
  channel_id: number
}

示例请求

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version_id": 456,
    "channel_id": 789
  }' \
  https://api.capgo.app/bundle/

成功响应

{
  "status": "success",
  "message": "Bundle 1.0.0 set to channel production"
}

错误处理

常见错误场景及其响应：

// Bundle not found
{
  "error": "Bundle not found",
  "status": "KO"
}

// Invalid bundle (version) format
{
  "error": "Invalid version format",
  "status": "KO"
}

// Storage error
{
  "error": "Failed to delete bundle from storage",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage bundles",
  "status": "KO"
}

常见用例

清理旧版包（版本）

// Delete outdated beta bundles (versions)
{
  "app_id": "app_123",
  "version": "1.0.0-beta.1"
}

应用重置

// Remove all bundles to start fresh
{
  "app_id": "app_123"
}

存储考虑

保留策略: 定义保留旧包的时间
大小管理: 监控包大小和存储使用
备份策略: 考虑备份关键的包（版本）
成本优化: 移除不必要的包以优化存储成本

继续从包中

如果您正在使用包来规划存储和文件处理，连接它到 @capgo/capacitor-data-storage-sqlite 了解@capgo/capacitor-data-storage-sqlite的实现细节使用@capgo/capacitor-data-storage-sqlite 为使用 @capgo/capacitor-data-storage-sqlite 的本机功能 @capgo/capacitor-file 为 @capgo/capacitor-file 的实现细节使用 @capgo/capacitor-file 为使用 @capgo/capacitor-file 的本机功能, 和 @capgo/capacitor-uploader for the implementation detail in @capgo/capacitor-uploader.

包

理解捆绑包

手动创建包（不含CLI）

以下是手动创建和上传包的步骤，使用__CAPGO_KEEP_0__ __CAPGO_KEEP_1__不需要：

Step 2: Create Bundle Zip Using Same Packages as Capgo CLI

安装必需包

使用 JavaScript 创建 ZIP 包（与 Capgo CLI 相同）

步骤 3：使用相同的包计算 SHA256 校验和（与 CLI 相同）

步骤 4: 将包上传到您的存储

Step 5: Register Bundle with Capgo API

API 参数

包结构要求

有效的包结构

完整的手动工作流程示例

校验和验证

JavaScript 校验和计算（与 Capgo CLI 相同）

校验和重要性

最佳实践

端点

GET

Endpoints

Response Type

Section titled “Example Request”

Section titled “Example Response”

DELETE

查询参数

示例请求

成功响应

POST

请求体

示例请求

成功响应

POST (元数据)

请求体

示例请求

成功响应

PUT

请求体

示例请求

成功响应

错误处理

常见用例

存储考虑

继续从包中

以下是手动创建和上传包的步骤，使用__CAPGO_KEEP_0 CAPGO_KEEP_1__不需要：