Bundles

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

バンドルは、Capgo のコアアップデートパッケージです。各バンドルには、Webアセット (HTML、CSS、JS) が含まれ、これらはアプリのコンテンツを構成します。バンドル管理機能の API を使用すると、これらのアップデートパッケージを管理できます。これには、リストと削除が含まれます。

バンドルの理解

バンドルは、アプリのWebコンテンツの特定のバージョンを表し、以下を含みます:

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

手動バンドル作成 (Without CLI)

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

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

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

npm run build

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

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

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

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：CLIと同じパッケージを使用してSHA256チェックサムを計算する

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 ファイルを任意の Web アクセス可能なストレージにアップロードしてください。

# 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 のサーバーは、この 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

ステップ 5: 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`	SHA256 チェックサム	はい

バンドル構造要件

バンドル zip は次の要件に従う必要があります:

ルートインデックスファイル: 必要なもの index.html ルートレベルに
Capacitor統合: 必ず呼び出す notifyAppReady() in your app 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はチェックサムを検証することでバンドルを受け入れる
プラグイン検証: プラグインはアップデートを適用する前にチェックサムを検証する

ベストプラクティス

バンドル(バージョン)管理: 一貫してバンドル管理 consistently
ストレージ最適化: 使わないバンドルを定期的に削除する
バンドル (バージョン) の互換性: 互換性のある最小のネイティブバージョンを指定する
バックアップストラテジー: 重要なバンドル (バージョン) のバックアップを維持する

エンドポイント

GET

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

クエリパラメータ version または id, は同じ JSON 配列の形を持ち、0 または 1 のバンドルを返します。

パラメータのクエリ

app_id: 必須。アプリの ID
page: 任意。ページ番号 (ページネーション用) (ページネーションを無視する場合) version または id 設定されている場合
version: 任意。バンドルのバージョン名 (例えば)app_versions.name: 任意。バンドルのバージョン名 (例えば) 1.2.3、
id例えばapp_versions.id、

を返します。 authorization ヘッダーとAPIキーのアプリスコープは、ページネーションされたリストです。クエリスキーマ検証で却下された値は invalid_query error.

バージョンが存在するかどうかを確認する (CI)

CLIの代わりにHTTPチェックが必要な場合、アップロードまたはチャンネル割り当て前に使用してください。

curl -H "authorization: YOUR_API_KEY" \
  "https://api.capgo.app/bundle/?app_id=com.example.app&version=1.2.3"

アプリのバージョンがすでに存在する場合、非空のJSON配列が返されます。存在しない場合、空の配列が返されます。

For upload workflows, the Capgo CLI bundle upload --version-exists-ok レスポンスタイプ

レスポンスタイプセクション

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
}

サンプルリクエスト

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

# Look up one bundle by version name
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123&version=1.0.0"

# Look up one bundle by id
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123&id=456"

サンプルレスポンス

[
  {
    "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"
}

Capacitor

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

ストレージに関する考慮事項

保持ポリシー:古いバンドルの保持期間を定義する
サイズ管理:バンドルのサイズとストレージ使用量を監視する
バックアップ戦略:重要なバンドル (バージョン) をバックアップすることを検討する
コスト最適化: 必要なバンドルを削除してストレージコストを最適化する

続けてバンドル

Capgoを使用している場合 バンドル ストレージとファイルの管理を計画するために使用する場合、バンドルを @capgo/capacitor-データストレージ-SQLite @capgo/capacitor-data-storage-sqliteの実装詳細 Capgoを使用して@capgo/capacitorデータストレージを実装します。 Capgoのネイティブ機能のために@capgo/capacitor-data-storage-sqliteを使用します。 @capgo/capacitorファイル @capgo/capacitorファイルの実装詳細のために @capgo/capacitorファイルを使用します。 for the native capability in Using @capgo/capacitor-file, and @capgo/capacitor-アップローダー Capgoの実装詳細については、@capgo/capacitor-uploaderを参照してください。

Bundles

バンドルの理解

手動バンドル作成 (Without CLI)

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

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

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

JavaScriptと同様のZIPアーカイブを作成する（Capgo CLIと同じ）

ステップ3：CLIと同じパッケージを使用してSHA256チェックサムを計算する

ステップ4：バンドルをあなたのストレージにアップロードする

ステップ 5: Capgo API にバンドルを登録する

API パラメータ

バンドル構造要件

バンドル構造

手動ワークフロー全体例

チェックサム検証

Capgo CLI の JavaScript チェックサム計算 (同様)

チェックサムの重要性

ベストプラクティス

エンドポイント

GET

パラメータのクエリ

バージョンが存在するかどうかを確認する (CI)

レスポンスタイプセクション

サンプル リクエスト

サンプル レスポンス

DELETE

クエリ パラメータ

例の要求

成功応答

POST

リクエスト ボディ

例のリクエスト

成功レスポンス

POST (メタデータ)

リクエストボディ

例のリクエスト

成功レスポンス

PUT

リクエストボディ

例: リクエスト

成功レスポンス

エラー処理

一般的な使用例

ストレージに関する考慮事項

続けてバンドル

サンプルリクエスト

サンプルレスポンス

クエリパラメータ

リクエストボディ