バンドル

このプラグインのインストール手順とフルマークダウンガイドを含むセットアップコマンドをコピーしてください。

インストール、同期、ソースマークダウンガイドを含むセットアップコマンドが用意されています。 __CAPGO_KEEP_0__のバンドルは、更新パッケージの核となる部分です。各バンドルには、Webアセット(HTML、CSS、JS)が含まれ、これらはアプリのコンテンツを構成します。__CAPGO_KEEP_1__のバンドル機能を使用すると、これらの更新パッケージを管理できます。これには、リストや削除が含まれます。

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.

更新パッケージの核となる部分です。

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

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

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

手動でバンドルを作成してアップロードする方法については、以下の手順を参照してください。Capgo CLI を使用せずに。

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

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

npm run build

ステップ 2：Capgo CLI が内部で使用する同一のパッケージを使用してバンドル ZIP を作成する

重要: Capgo CLI が内部で使用する同一の JavaScript パッケージを使用して、互換性を確保するようにしてください。

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

npm install adm-zip @tomasklaen/checksum

CapgoとCLIの同等のJavaScriptで作成したZIPアーカイブを作成する

以下の例では、 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();

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();

Step 4: __CAPGO_KEEP_0__をアップロードする

__CAPGO_KEEP_0__の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"

重要：__CAPGO_KEEP_0__のバンドルは 公開アクセス 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

Step 5: 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を直接__CAPGO_KEEP_1__呼び出しで登録する

__CAPGO_KEEP_0__のパラメーター	__CAPGO_KEEP_0__のパラメーター	パラメーター
`app_id`	説明	必要
`version`	アプリケーションID	はい
`external_url`	バンドル（バージョン）シーケンスバージョン（例：「1.2.3」） HTTPS URL から bundle をダウンロードできます (認証なし)	はい
`checksum`	__CAPGO_KEEP_0__ の SHA256 チェックサム	はい

bundle の構造要件

bundle zip を以下の要件に従ってください:

root index file: 必ず index.html root level に
Capacitor統合: 必ず呼び出す notifyAppReady() あなたのアプリ内で code
アセットパス: 相対パスをすべてのアセットに使用します

有効なバンドル構造

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

完全なマニュアルワークフロー例

シンプルな Node.js スクリプトで、 Capgo: を ZIP、チェックサム、アップロードします

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 の内部で使用する同じパッケージとメソッドを使用してください：

Use the exact same package and method that Capgo CLI uses internally:

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();

バンドルの整合性

__CAPGO_KEEP_0__ 検証バンドルの保存中に損傷していないことを確認します
API 検証: Capgo のチェックサムを検証する
プラグイン検証: モバイルプラグインはアップデートを適用する前にチェックサムを検証する

ベストプラクティス

バンドル (バージョン) 管理: 一貫してシーケンスバージョニングを使用する
ストレージオプティミゼーション: 不要なバンドルを定期的に削除する
バンドル (バージョン) 相容性: 適切な最小のネイティブバージョン要件を設定する
バックアップストラテジー: __CAPGO_KEEP_0__のバックアップを定期的に行ってください (バージョン)

エンドポイント

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/

__CAPGO_KEEP_0__

リクエストボディ

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/

特定のチャネルにバンドルを設定します。このリンクはバンドル（バージョン）を配布用のチャネルと関連付けます。

Request Body

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

Example Request

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

ストレージの考慮事項

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

バンドル

更新パッケージの核となる部分です。

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

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

ステップ 2：Capgo CLI が内部で使用する同一のパッケージを使用してバンドル ZIP を作成する

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

CapgoとCLIの同等のJavaScriptで作成したZIPアーカイブを作成する

CLIと同等のパッケージを使用してSHA256チェックサムを計算する

Step 4: __CAPGO_KEEP_0__をアップロードする

Step 5: Capgo APIとバンドルを登録する

APIを直接__CAPGO_KEEP_1__呼び出しで登録する

bundle の構造要件

有効なバンドル構造

完全なマニュアル ワークフロー例

チェックサム検証

Capgo CLI の内部で使用する同じパッケージとメソッドを使用してください：

バンドルの整合性

ベスト プラクティス

エンドポイント

GET

クエリパラメータ

レスポンスのタイプ

例のリクエスト

例のレスポンス

DELETE

クエリパラメータ

例のリクエスト

成功応答

POST

リクエストボディ

サンプルリクエスト

成功レスポンス

POST (メタデータ)

リクエストボディ

サンプルリクエスト

成功レスポンス

PUT

Request Body

Example Request

成功応答

エラー処理

一般的な使用例

ストレージの考慮事項

完全なマニュアルワークフロー例

ベストプラクティス