Bundles

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.

Judul bagian “Mengerti Bundles”

A bundle mewakili versi tertentu dari konten web aplikasi Anda dan termasuk:

• Bundle (versi): Nomor versi semantik untuk bundle
• Checksum: Hash unik untuk memverifikasi integritas bundle
• Pengaturan Penyimpanan: Detail tentang di mana dan bagaimana bundle disimpan
• Kebutuhan Nativ: Persyaratan versi aplikasi native minimal
• Metadata: Waktu pembuatan, kepemilikan, dan informasi pelacakan lain

Pembuatan Paket Manual (Tanpa CLI)

Ini cara membuat dan mengunggah paket secara manual tanpa menggunakan Capgo CLI:

Langkah 1: Bangun Aplikasi Anda

Pertama-tama, bangun aset web aplikasi Anda:

npm run build

Langkah 2: Buat Paket Zip Menggunakan Paket yang Sama dengan Capgo CLI

Penting: Gunakan paket JavaScript yang sama persis yang digunakan oleh Capgo CLI secara internal untuk memastikan konsistensi.

Instal Paket yang Diperlukan

npm install adm-zip @tomasklaen/checksum

Buat Arsip Zip dengan JavaScript (Sama seperti Capgo CLI)

Perlu diingat: Dalam contoh-contoh di bawah, version merujuk pada nama arsip (versi) yang digunakan oleh 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();

Langkah 3: Hitung Checksum SHA256 Menggunakan Paket yang Sama dengan 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();

Langkah 4: Unggah Paket ke Penyimpanan Anda

Unggah file zip Anda ke penyimpanan web yang dapat diakses:

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

Penting: Paket Anda harus tersedia secara publik melalui URL HTTPS (tidak memerlukan autentikasi). Server Capgo memerlukan untuk mengunduh paket dari URL ini.

Contoh URL publik yang valid:

• 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

Langkah 5: Daftarkan Paket dengan Capgo API

Daftarkan bundle eksternal dengan Capgo menggunakan panggilan API langsung:

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 Parameter

Parameter	Deskripsi	Diperlukan
app_id	Identifikasi aplikasi Anda	Ya
version	Bundle (versi) versi semantik (misalnya, “1.2.3”)	Ya
external_url	Akses publik URL HTTPS di mana bundle dapat diunduh (tidak memerlukan autentikasi)	Ya
checksum	Checksum SHA256 dari file zip	Ya

Persyaratan Struktur Bundle

Zip bundle Anda harus memenuhi persyaratan berikut:

1. File Index Utama: Harus ada index.html di tingkat root
2. Capacitor Integrasi: Harus dipanggil notifyAppReady() di aplikasi code
3. Rute Aset: Gunakan jalur relatif untuk semua aset

Struktur Paket yang Valid

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

Judul Bagian “Contoh Alur Manual yang Lengkap”

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

Instalasi dependensi:

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

Pengverifikasi Cek Hasil

Perhitungan Cek Hasil JavaScript (Sama dengan Capgo CLI)

Gunakan paket dan metode yang sama persis seperti Capgo CLI yang digunakan secara internal:

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

Ketertarikan Cek Hasil

• Integritas Paket BundelPastikan bundle tidak rusak selama transfer
• API VerifikasiCapgo memverifikasi checksum sebelum menerima bundle
• Verifikasi PluginPlugin mobile memverifikasi checksum sebelum menerapkan update

Praktik Terbaik

1. Pengelolaan Bundle (versi)Gunakan versi semantik secara konsisten Optimasi Penyimpanan
2. Gunakan penyimpanan secara konsistenHapus bundle yang tidak digunakan secara berkala
3. Kompatibilitas Bundle (versi)Halaman berjudul “Endpoints”
4. Rencana CadanganHalaman berjudul “Backup Strategy”

Halaman berjudul “Maintain backups of critical bundles (versions)”

Halaman berjudul “GET”

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

Halaman berjudul “Query Parameters”

Halaman berjudul “Section titled “Query Parameters””

• app_id : Wajib. ID aplikasi Anda
• page : Opsional. Nomor halaman untuk pagination

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
}

Contoh Permintaan

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

Contoh Respons

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

HAPUS

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

Hapus satu atau semua bundle untuk aplikasi. Gunakan dengan hati-hati karena aksi ini tidak dapat dibatalkan.

Parameter Kueri

Untuk menghapus bundle tertentu:

interface BundleDelete {
  app_id: string
  version: string
}

Untuk menghapus semua bundle:

interface BundleDeleteAll {
  app_id: string
}

Contoh Permintaan

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

Respons Sukses

{
  "status": "ok"
}

POST

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

Buat bundle baru dengan URL eksternal.

Tubuh Permintaan

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

Contoh Permintaan

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/

Respons Sukses

{
  "status": "ok"
}

POST (Metadata)

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

Update metadata paket seperti informasi link dan komentar.

Tubuh Permintaan

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

Contoh Permintaan

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

Respons Sukses

{
  "status": "success"
}

PUT

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

Tetapkan sebuah bundle ke sebuah saluran tertentu. Ini menghubungkan sebuah bundle (versi) ke sebuah saluran untuk distribusi.

Badan Permintaan

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

Contoh Permintaan

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/

Respons Berhasil

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

Pengelolaan Kesalahan

Skenario Kesalahan Umum dan Responsnya:

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

Penggunaan Umum

1. Pembersihan Paket Lama (Versi)

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

2. Reset Aplikasi

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

Konsiderasi Penyimpanan

1. Kebijakan RetensiTentukan berapa lama menyimpan paket lama
2. Pengelolaan UkuranMonitor ukuran paket dan penggunaan penyimpanan
3. Strategi Back-up: Pertimbangkan untuk mengembalikan bundle-critical (versi)
4. Optimasi Biaya: Hapus bundle yang tidak perlu untuk mengoptimalkan biaya penyimpanan

Teruskan dari Bundle

Jika Anda menggunakan Bundle untuk merencanakan penyimpanan dan pengelolaan file, hubungkan dengan @capgo/capacitor-data-storage-sqlite untuk detail implementasi di @capgo/capacitor-data-storage-sqlite, Menggunakan @capgo/capacitor-data-storage-sqlite untuk kemampuan native di Menggunakan @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-file untuk detail implementasi di @capgo/capacitor-file Menggunakan @capgo/capacitor-file untuk kemampuan asli di Menggunakan @capgo/capacitor-file, dan @capgo/capacitor-uploader untuk detail implementasi di @capgo/capacitor-uploader.