Bundles

I pacchetti Bundle sono i pacchetti di aggiornamento principali in Capgo. Ogni pacchetto Bundle contiene gli asset web (HTML, CSS, JS) che compongono il contenuto dell'applicazione. Il Bundle API consente di gestire questi pacchetti di aggiornamento, inclusa la visualizzazione e la cancellazione di essi.

Capire i Bundle

Pacchetto rappresenta una versione specifica del contenuto web dell'app e include:

• Versione del pacchetto: Numero di versione semantico per il pacchetto
• Checksum: Hash univoca per verificare l'integrità del pacchetto
• Informazioni di archiviazione: Dettagli su dove e come il pacchetto è archiviato
• Requisiti nativi: Requisiti minimi di versione dell'app nativa
• Metadati: Ora di creazione, proprietà e altre informazioni di tracciamento

Creazione del Bundle Manuale (Senza CLI)

Ecco come creare e caricare manualmente i bundle senza utilizzare il Capgo CLI:

Passo 1: Costruisci l'App

Prima, costruisci gli asset web dell'app:

npm run build

Passo 2: Crea Zip del Bundle Utilizzando gli Stessi Pacchetti di Capgo CLI

Importante: Utilizza gli stessi pacchetti JavaScript interni di Capgo CLI per garantire la compatibilità.

Installa Pacchetti Richiesti

npm install adm-zip @tomasklaen/checksum

Creare Bundle Zip con JavaScript (Lo stesso di Capgo CLI)

Nota: Nelle esempi che seguono, version si riferisce al nome del bundle (versione) utilizzato dal 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();

Passo 3: Calcolare Checksum SHA256 Utilizzando lo stesso Pacchetto di 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();

Passo 4: Carica il Bundle nel tuo Archivio

Carica il tuo file zip in qualsiasi archivio accessibile da 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"

ImportanteLa tua raccolta deve essere accessibile al pubblico tramite URL HTTPS (nessuna autenticazione richiesta). I server di Capgo devono scaricare la raccolta da questo URL.

Esempi di URL pubblici validi:

• 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

Passo 5: Registra la Raccolta con Capgo API

Registra il bundle esterno con Capgo utilizzando chiamate dirette 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 Parametri

Parametro	Descrizione	Obbligatorio
app_id	Identificatore dell'applicazione	Sì
version	Versione del pacchetto (Bundle) versione semantica (ad esempio, “1.2.3”)	Sì
external_url	Accessibile al pubblico URL HTTPS dove il bundle può essere scaricato (nessuna autenticazione richiesta)	Sì
checksum	Checksum SHA256 del file zip	Sì

Requisiti di struttura del bundle

Il tuo file zip del bundle deve rispettare questi requisiti:

1. File di indice radice: Deve avere index.html al livello radice
2. Integrazione Capacitor: Deve chiamare notifyAppReady() in il tuo app code
3. Asset Paths: Utilizzare percorsi relativi per tutti gli asset

Struttura della Bundle Valida

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

Esempio di Flusso di Lavoro Manuale Completo

Script Node.js semplice per zip, checksum e caricare su 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);

Installare dipendenze:

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

Verifica del checksum

Calcolo del checksum JavaScript (Lo stesso di Capgo CLI)

Usa lo stesso pacchetto e metodo che Capgo CLI utilizza internamente:

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

Importanza del checksum

• Integrità del bundle: Assicura che il bundle non sia stato corrotto durante il trasferimento
• API Verifica: Capgo verifica i checksum prima di accettare i bundle
• Verifica del Plugin: Il plugin mobile verifica i checksum prima di applicare gli aggiornamenti

Prassi Raccomandate

1. Gestione del Bundle (versione): Utilizza : la versioning semantico : in modo coerente
2. Optimizzazione dello Storage: Rimuovi periodicamente le bundle non utilizzate
3. Compatibilità della bundle (versione): Imposta le richieste minime di versione nativa appropriate
4. Strategia di backup: Mantieni backup delle bundle critiche (versioni)

Endpoint

GET

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

Recupera informazioni sulla bundle. Restituisce 50 bundle per pagina.

Parametri di query

• app_id: Richiesto. L'ID del tuo app
• page: Opzionale. Numero di pagina per la paginazione

Tipo di Risposta

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
}

Esempio di Richiesta

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

Esempio di Risposta

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

Elimina

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

Elimina uno o tutti i pacchetti per un'app. Utilizza con cautela poiché questa azione non può essere annullata.

Parametri di query

Per eliminare un pacchetto specifico:

interface BundleDelete {
  app_id: string
  version: string
}

Per eliminare tutti i pacchetti:

interface BundleDeleteAll {
  app_id: string
}

Esempi di richiesta

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

Risposta di successo

{
  "status": "ok"
}

POST

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

Creare un nuovo bundle con URL esterna.

Corpo della richiesta

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

Esempio di richiesta

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/

Risposta di successo

{
  "status": "ok"
}

POST (Metadati)

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

Aggiorna i metadati del pacchetto, ad esempio informazioni di collegamento e commenti.

Corpo della richiesta

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

Esempio di richiesta

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

Risposta di successo

{
  "status": "success"
}

PUT

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

Imposta un bundle in un canale specifico. Questo collega un bundle (versione) a un canale per la distribuzione.

Corpo della richiesta

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

target controlla dove il bundle è collegato quando il canale ha configurato il rilascio progressivo:

• auto — obiettivo di rilascio quando è configurato il rilascio progressivo; stabile altrimenti (predefinito).
• rollout — imposta sempre l'obiettivo di rilascio; fallback stabile invariato.
• stable — sostituisci fallback stabile (uscita di emergenza).

Esempio di richiesta

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/

Risposta di successo

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

Gestione degli errori

Scenari di errori comuni e le loro risposte:

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

Casi d'uso comuni

1. Pulizia delle vecchie bundle (versioni)

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

2. Reset dell'app

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

Considerazioni sulla memorizzazione

1. Politica di conservazioneDefinisci la durata di archiviazione dei bundle vecchi
2. Gestione delle Dimensioni: Monitor bundle sizes and storage usage
3. Strategia di Backup: Considera di effettuare il backup dei bundle critici (versioni)
4. Optimizzazione dei CostiRimuovi bundle non necessari per ottimizzare i costi di archiviazione

Continua da qui: Bundle

Se stai utilizzando Bundle per pianificare lo storage e la gestione dei file, connettilo @capgo/capacitor-archiviazione-dati-sqlite per i dettagli di implementazione in @capgo/capacitor-archiviazione-dati-sqlite, Utilizzare @capgo/capacitor-archiviazione-dati-sqlite per la capacità nativa in Utilizzare @capgo/capacitor-archiviazione-dati-sqlite, @capgo/capacitor-file per i dettagli di implementazione in @capgo/capacitor-file, Utilizzare @capgo/capacitor-file per la capacità nativa in Utilizzare @capgo/capacitor-file, e uploader capgo-capacitor per i dettagli di implementazione in @capgo/capacitor-uploader.