Bundles

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

Mengerti Bundel

Bundel mewakili versi tertentu konten web aplikasi Anda dan termasuk:

• Bundel (versi): Nomor versi semantik untuk bundel untuk bundel
• Checksum: Kunci unik untuk memverifikasi integritas bundle
• Informasi Penyimpanan: Detail tentang di mana dan bagaimana bundle disimpan
• Kebutuhan Nativ: Persyaratan aplikasi native minimum
• Metadata: Informasi tentang waktu pembuatan, kepemilikan, dan lain-lain

Pembuatan Bundle Manual (Tanpa CLI)

Berikut cara membuat dan mengunggah bundle secara manual tanpa menggunakan Capgo CLI:

Langkah 1: Bangun Aplikasi Anda

Pertama, bangunlah aset web aplikasi Anda:

npm run build

Langkah 2: Buat Zip Bundle Menggunakan Paket yang Sama seperti Capgo CLI

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

Pasang Paket yang Diperlukan

npm install adm-zip @tomasklaen/checksum

Buat Zip Bundle dengan JavaScript (Sama seperti Capgo CLI)

Perlu diingat: Dalam contoh-contoh di bawah, version merujuk pada nama bundle (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 SHA256 Checksum 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 Bundle 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"

Perlu diingat: Bundel Anda harus dapat diakses secara publik melalui URL HTTPS (tidak memerlukan autentikasi). Server __CAPGO_KEEP_0__ memerlukan untuk mengunduh bundel dari URL ini. via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

Langkah 5: Daftarkan Bundel dengan __CAPGO_KEEP_0__ __CAPGO_KEEP_1__

• 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

Judul Bagian “Langkah 5: Daftarkan Bundel dengan Capgo API”

Register the external bundle with Capgo using direct API calls:

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

Judul Bagian “Parameter API”

Parameter	Deskripsi	Diperlukan
app_id	Identifikasi Aplikasi Anda	Ya
version	Paket (versi) versi semantik (misalnya, “1.2.3”)	Ya
external_url	Akses Dapat Dilihat Umum URL HTTPS di mana paket dapat diunduh (tidak memerlukan autentikasi)	Ya
checksum	Checksum SHA256 dari file zip	Yes

Struktur Paket Persyaratan

Paket zip Anda harus memenuhi persyaratan berikut:

1. File Index Utama: Harus ada index.html di tingkat root
2. Integrasi Capacitor: Harus memanggil notifyAppReady() dalam aplikasi Anda code
3. Rute Asset: Gunakan rute relatif untuk semua asset

Struktur Bundle yang Sah

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

Contoh Penuh Alur Manual

Skrip Node.js Sederhana untuk Mengompres, Menghitung Cek Palsu, 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);

Pasang dependensi:

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

Verifikasi Cek Palsu

Perhitungan Cek Pemformatan JavaScript (Sama dengan Capgo CLI)

Gunakan paket dan metode yang sama persis seperti yang digunakan oleh Capgo CLI 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();

Ketetapan Cek Pemformatan

• Integritas Paket: Menjamin paket tidak rusak selama pengiriman
• API Verifikasi: Capgo memverifikasi cek pemformatan sebelum menerima paket
• Verifikasi Plugin: Plugin mobile memverifikasi cek pemformatan sebelum menerapkan update

Praktik Terbaik

1. Pengelolaan Paket (versi): Gunakan versi semantik secara konsisten Optimasi Penyimpanan
2. : Hapus paket yang tidak digunakan secara berkalaPaket (versi) Kompatibilitas
3. : Tetapkan persyaratan versi native minimum yang tepatStrategi Cadangan
4. : Lakukan cadangan kritis paket (versi)Paket (versi) Kompatibilitas

Endpoints

GET

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

Mengambil informasi bundle. Mengembalikan 50 bundle per halaman.

Parameter Pencarian

• app_id: Diperlukan. ID aplikasi Anda
• page: Opsional. Nomor halaman untuk pengaturan halaman

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"

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 Berhasil

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

{
  "status": "ok"
}

POST (Metadata)

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

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

{
  "status": "success"
}

PUT

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

Tetapkan sebuah bundle ke sebuah saluran khusus. 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. Membersihkan 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 Retensi: Tentukan berapa lama untuk menyimpan bundle lama
2. Pengelolaan Ukuran: Pantau ukuran bundle dan penggunaan penyimpanan
3. Strategi Cadangan: Pertimbangkan untuk mengambil cadangan bundle kritis (versi)
4. Optimasi Biaya: Hapus bundle yang tidak perlu untuk mengoptimalkan biaya penyimpanan

Lanjutkan dari Bundle

Jika Anda menggunakan Bundles untuk merencanakan penyimpanan dan pengelolaan file, hubungkannya dengan @capgo/capacitor-data-storage-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, @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.