Bundles

Bundles adalah paket pembaruan inti di Capgo. Setiap bundle mengandung aset web (HTML, CSS, JS) yang membentuk konten aplikasi Anda. Paket Bundles API memungkinkan Anda untuk mengelola paket pembaruan ini, termasuk menampilkan dan menghapusnya.

Pengertian Bundles

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
• Info Penyimpanan: Detail tentang di mana dan bagaimana bundle disimpan
• Kebutuhan Nativ: Versi aplikasi native minimum yang diperlukan
• Metadata: Waktu pembuatan, kepemilikan, dan informasi pelacakan lainnya

Pembuatan Paket Manual (Tanpa CLI)

Berikut cara membuat dan mengunggah paket 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 yang digunakan oleh Capgo CLI secara internal untuk memastikan konsistensi.

Instalasi Paket yang Diperlukan

npm install adm-zip @tomasklaen/checksum

Buat Arsip Zip dengan JavaScript (Sama seperti Capgo CLI)

Catatan: Dalam contoh-contoh di bawah, version Mengacu pada nama paket (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();

merujuk pada nama paket (versi) yang digunakan oleh 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 perlu mengunduh bundle 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	Terbuka untuk umum 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. Integrasi Capacitor: Harus dipanggil notifyAppReady() di aplikasi code
3. Jalur Asset: Gunakan jalur relatif untuk semua asset

Struktur Bundle yang Valid

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

Contoh Langkah-Langkah Manual yang Lengkap

Skrip Node.js sederhana untuk mengompres, melakukan cek checksum, dan mengunggah ke 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

Verifikasi Cek Pintu

Penghitungan Cek Pintu JavaScript (Sama seperti Capgo CLI )

Pakai metode dan paket yang sama seperti Capgo CLI gunakan 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 Pintu

• Integritas Paket: Memastikan bundle tidak rusak selama transfer
• API Verifikasi: Capgo memverifikasi checksum sebelum menerima bundle
• Verifikasi Plugin: Plugin mobile memverifikasi checksum sebelum menerapkan update

Praktik Terbaik

1. Pengelolaan Bundle (versi): Gunakan : Penggunaan versi semantik secara konsisten consistently
2. Penggunaan yang Baik: Hapus bundle yang tidak digunakan secara berkala
3. Kompatibilitas Bundle (versi): Tetapkan persyaratan versi native minimum yang tepat
4. Strategi Cadangan: Tahan cadangan bundle kritis (versi)

Endpoint

GET

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

Pilih informasi bundle. Tanpa filter, mengembalikan 50 bundle per halaman. Dengan version atau id, mengembalikan array JSON yang sama dengan bentuk dengan nol atau satu bundle.

Parameter Pencarian

• app_id: Wajib. ID Aplikasi Anda
• page: Opsional. Nomor halaman untuk pengaturan halaman (diabaikan ketika version atau id Ditentukan
• versionVersi bundle spesifik (opsional)app_versions.name: Mengembalikan array JSON dengan item nol atau satu. 1.2.3Mengembalikan sebuah array JSON dengan item nol atau satu.
• idID Bundle Opsional. ID numerik bundle (app_versions.idMengembalikan sebuah array JSON dengan item nol atau satu.

parameter pencarian authorization header dan API kunci aplikasi skoping sebagai daftar yang dipaginasi. Nilai yang ditolak oleh validasi schema kueri mengembalikan sebuah invalid_query error.

Percayakan apakah versi ada (CI)

Pakai hal ini sebelum unggah atau penugasan saluran ketika Anda membutuhkan cek HTTP daripada CLI:

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

Array JSON tidak kosong berarti versi sudah ada untuk aplikasi. Array kosong berarti tidak ada.

Untuk aliran kerja unggah, flag Capgo CLI digunakan bundle upload --version-exists-ok Sudah ada ketika versi target ada, yang mencakup banyak pekerjaan CI tanpa perlu memanggil endpoint ini.

Jenis Respon

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"

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

Contoh Respons

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

Mengirimkan

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

Buat bundle baru dengan URL eksternal.

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

Judul Bagian “Mengirimkan Contoh”

{
  "status": "ok"
}

POST (Metadata)

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

Perbarui metadata paket seperti informasi tautan dan komentar.

Badan 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 Berhasil

{
  "status": "success"
}

PUT

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

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

Badan Permintaan

interface SetChannelBody {
  app_id: string
  version_id: number // bundle (version) id
  channel_id: number
  target?: "auto" | "stable" | "rollout" // default: auto
}

target menentukan di mana paket terkait ketika saluran memiliki pengaturan pergeseran progresif yang dikonfigurasi:

• auto – target pergeseran ketika pengaturan pergeseran progresif dikonfigurasi; stabil lainnya (default).
• rollout – selalu tetapkan target pergeseran; fallback stabil tidak berubah.
• stable – ganti fallback stabil (pintu keluar darurat).

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/

Respon Berhasil

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

Judul Bagian “Respons Sukses”

Judul Bagian “Pengelolaan Kesalahan”

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

Skenario Kesalahan Umum dan Responsnya:”,

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

Pulihkan Aplikasi

1. Judul Bagian: Pertimbangan PenyimpananTentukan berapa lama untuk menyimpan bundle lama
2. Pengelolaan Ukuran: Pantau ukuran bundle dan penggunaan penyimpanan
3. Strategi Pemulihan: Pertimbangkan untuk mengembalikan bundle kritis (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-penyimpanan-data-sqlite untuk detail implementasi di @capgo/capacitor-data-storage-sqlite, Menggunakan @capgo/capacitor-data-storage-sqlite untuk kemampuan asli di Menggunakan @capgo/capacitor-data-storage-sqlite, di @capgo/capacitor-file untuk detail implementasi di @capgo/capacitor-file, Menggunakan @capgo/capacitor-file untuk kemampuan native di Menggunakan @capgo/capacitor-file, dan @capgo/capacitor-uploader untuk detail implementasi di @capgo/capacitor-uploader.