バンドル

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

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

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

バンドル (バージョン): バンドル (バージョン) のセマンティックバージョン番号
バンドルのチェックサム
: バンドルの完全性を確認するためのユニークなハッシュストレージ情報
: バンドルがどの場所でどのように保存されているかについての詳細ネイティブ要件
: ネイティブアプリの最低バージョン要件: __CAPGO_KEEP_0__の作成日時、所有権、他に追跡情報

CLIの手動作成 (Without __CAPGO_KEEP_1__)

ここでは、Capgo 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"

重要あなたのバンドルは パブリックにアクセス可能 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`	アプリケーション識別子	はい
`version`	バンドル（バージョン）バージョン番号（例：「1.2.3」）	はい
`external_url`	一般に公開されている HTTPS URL からバンドルをダウンロードできる場所 (認証なし)	はい
`checksum`	zip ファイルの SHA256 チェックサム	バンドル構造要件

バンドル構造要件のセクション

ルートインデックスファイル

: 必ず持つ必要がありますBundle Structure Requirements index.html rootレベル
Capacitor統合: 必ず呼び出す notifyAppReady() アプリケーション内でcode
アセットパス: アセットのすべてのパスを相対パスで使用する

バンドル構造

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

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

Simple Node.js script to zip, checksum, and upload to 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: オプション。ページネーションのページ番号

レスポンスのタイプ

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"

例のレスポンス

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

例のリクエスト

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 を使用している場合 バンドル ストレージとファイルの管理を計画するために使用している場合、@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-data-storage-sqlite に接続してください @capgo/capacitor-data-storage-sqlite の実装詳細については、@capgo/capacitor-data-storage-sqlite を参照してください @capgo/capacitor-data-storage-sqlite を使用しています Using @capgo/capacitor-data-storage-sqlite Capacitorデータストレージのネイティブ機能を使用するには、@capgo/capacitor-data-storage-sqliteを使用します。 @capgo/capacitor-file Capacitorファイルの実装詳細を参照するには、@capgo/capacitor-fileを参照してください。 @capgo/capacitor-fileを使用してCapacitorファイルを使用します。 Capacitorデータストレージのネイティブ機能を使用するには、@capgo/capacitor-fileを使用し、 @capgo/capacitor-uploader Capacitorアップローダーの実装詳細を参照するには、@capgo/capacitor-uploaderを参照してください。

バンドル

Understanding Bundles

CLIの手動作成 (Without __CAPGO_KEEP_1__)

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

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

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

JavaScript で Capgo CLI と同じように ZIP バンドルを作成する

Step 3: Calculate SHA256 Checksum Using Same Package as CLI

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

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

API パラメータ

バンドル構造要件のセクション

バンドル構造

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

チェックサム検証

CapgoとCLIで使用されるJavaScriptのチェックサム計算 (同等)

チェックサムの重要性

ベスト プラクティス

エンドポイント

GET

クエリパラメータ

レスポンスのタイプ

例のリクエスト

例のレスポンス

DELETE

クエリ パラメータ

例のリクエスト

成功応答

POST

リクエストボディ

例のリクエスト

成功応答

POST (メタデータ)

リクエストボディ

サンプル リクエスト

成功応答

PUT

リクエスト ボディ

例のリクエスト

成功レスポンス

エラー処理

一般的な使用例

ストレージの考慮事項

バンドルから続けて

ベストプラクティス

クエリパラメータ

サンプルリクエスト

リクエストボディ