バンドル

このプラグインのインストール手順と全マークダウンガイドを含むセットアップコマンドをコピーできます。

Bundles are the core update packages in Capgo. Each bundle contains the web assets (HTML, CSS, JS) that make up your app’s content. The Bundles API allows you to manage these update packages, including listing and deleting them.

Understanding Bundles

バンドルは、特定のバージョンのアプリのウェブコンテンツを表し、次の情報を含みます:

バンドル (バージョン): バンドル (バージョン) のセマンティックバージョン番号
バンドルのチェックサム
: バンドルの整合性を検証するためのユニークなハッシュストレージ情報
: バンドルがどのように保存され、どこに保存されているかについての詳細ネイティブ要件
: ネイティブアプリの最低バージョン要件: 作成日時、所有者情報、トラッキング情報

手動でバンドルを作成する ( CLI を使用しない)

ここでは、 Capgo CLI を使用せずにバンドルを作成しアップロードする方法を説明します。

ステップ 1: アプリをビルドする

まず、アプリのウェブアセットをビルドしてください。

npm run build

ステップ 2: Capgo CLI と同じパッケージを使用してバンドル ZIP を作成する

重要な注意事項: Capgo CLI の内部で使用している同じ JavaScript パッケージを使用して、互換性を確保します。

必要なパッケージをインストールする

npm install adm-zip @tomasklaen/checksum

JavaScript で Capgo CLI と同じように Zip アーカイブを作成する

注: 以下の例では、 version refers to the bundle (version) name used by the 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();

Step 3: Calculate SHA256 Checksum Using Same Package as 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"

重要バンドルは パブリックにアクセス可能 via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

バンドルをダウンロードできるようにするための有効なパブリック URL の例:

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`	アプリケーションID	はい
`version`	バンドル(バージョン) セマンティックバージョン（例：「1.2.3」）	はい
`external_url`	パブリックにアクセス可能 HTTPS URL からバンドルをダウンロードできる場所 (認証なし)	はい
`checksum`	zip ファイルの SHA256 チェックサム	はい

バンドル構造要件

あなたのバンドル zip は、次の要件を満たす必要があります：

ルートインデックスファイル: 必ず index.html rootレベルで
Capacitor統合: 必ず呼び出す notifyAppReady() codeアプリ内で
アセットパス: アセットのすべてのパスを相対パスで使用する

有効なバンドル構造

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

完全な手動ワークフロー例

Node.jsスクリプトを簡単にzip、チェックサム、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

チェックサム検証

Capgo CLI と同等の JavaScript チェックサム計算

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/

バンドル情報を取得する。1ページあたり50バンドルを返します。

クエリパラメータ

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
}

Terminal window

# 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"

Copy to clipboard

{
  "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/

アプリのバンドルを1つまたはすべて削除します。削除は元に戻せないため、ご注意ください。

クエリパラメータ

特定のバンドルを削除する場合:

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
  target?: "auto" | "stable" | "rollout" // default: auto
}

target チャンネルが進化ロールアウトを設定している場合のバンドルへのリンクの場所:

auto — 進化ロールアウトが設定されている場合のロールアウトのターゲット; それ以外の場合は安定したもの (デフォルト).
rollout — 進化ロールアウトのターゲットを常に設定; 安定したフォールバックは変更なし.
stable — 安定したフォールバックを置き換えます (エスケープハッチ).

例のリクエスト

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 実装詳細については、@capgo/capacitor-uploaderを参照してください。

バンドル

Understanding Bundles

手動でバンドルを作成する ( CLI を使用しない)

ステップ 1: アプリをビルドする

ステップ 2: Capgo CLI と同じパッケージを使用してバンドル ZIP を作成する

必要なパッケージをインストールする

JavaScript で Capgo CLI と同じように Zip アーカイブを作成する

Step 3: Calculate SHA256 Checksum Using Same Package as CLI

ステップ 4: バンドルをストレージにアップロード

Step 5: Register Bundle with Capgo API

APIのパラメータ

バンドル構造要件

有効なバンドル構造

完全な手動ワークフロー例

チェックサム検証

Capgo CLI と同等の JavaScript チェックサム計算

チェックサムの重要性

ベスト プラクティス

エンドポイント

GET

クエリパラメータ

Response Type

Terminal window

Copy to clipboard

DELETE

クエリ パラメータ

例のリクエスト

成功応答

POST

リクエストボディ

例のリクエスト

成功レスポンス

POST (メタデータ)

リクエストボディ

サンプル リクエスト

成功レスポンス

PUT

「リクエスト ボディ」セクション

例のリクエスト

成功レスポンス

エラー処理

一般的な使用例

ストレージの考慮事項

バンドルから続ける

ベストプラクティス

クエリパラメータ

サンプルリクエスト

「リクエストボディ」セクション