Bundles

I pacchetti sono i pacchetti di aggiornamento principali in Capgo. Ogni pacchetto contiene i contenuti web (HTML, CSS, JS) che compongono il contenuto dell'applicazione. I pacchetti API consente di gestire questi pacchetti di aggiornamento, compresa la lista e la cancellazione di essi.

Capire i Pacchetti

Un pacchetto rappresenta una versione specifica dei contenuti web dell'applicazione e include:

• Pacchetto (versione): Numero di versione semantico per il bundle
• Checksum: Hash univoca per verificare l'integrità del bundle
• Info di archiviazione: Dettagli su dove e come il bundle è archiviato
• Requisiti nativi: Requisiti minimi di versione per l'app nativa
• Metadati: Informazioni 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

In primo luogo, costruisci i beni web dell'app:

npm run build

Passo 2: Crea Bundle Zip utilizzando gli stessi pacchetti di Capgo CLI

Importante: Utilizza gli stessi pacchetti JavaScript esatti che Capgo CLI utilizza internamente per garantire la compatibilità.

Installa i Pacchetti Richiesti

npm install adm-zip @tomasklaen/checksum

Creare un bundle ZIP con JavaScript (Lo stesso di Capgo CLI)

Nota: Nell'esempio seguente, 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 il 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: Caricare il bundle nel tuo storage

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

Importante: Il tuo bundle deve essere accessibile al pubblico tramite URL HTTPS (nessuna autenticazione richiesta). I server di Capgo devono scaricare il bundle 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 Bundle 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	Richiesto
app_id	Il tuo identificatore di app	Sì
version	Bundle (versione) 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 a livello radice
2. Integrazione Capacitor: Deve chiamare notifyAppReady() Inserisci code nel tuo app
3. Percorsi degli asset: Utilizza percorsi relativi per tutti gli asset

Struttura Bundle Valida

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

Esempio di Flusso di Lavoro 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);

Installa le 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 pacchetto : Assicura che il pacchetto non sia stato corrotto durante il trasferimento
• API Verifica: Capgo verifica i checksum prima di accettare i pacchetti
• Verifica Plugin: Il plugin mobile verifica i checksum prima di applicare gli aggiornamenti

Pratiche Ottimali

1. Gestione Pacchetti (versione): Utilizza la versioning semantico consistente
2. Optimizzazione del Storage: Rimuovi periodicamente i pacchetti non utilizzati
3. Compatibilità Pacchetti (versione): Impostare le versioni native minime richieste
4. Strategia di backup: Mantenere backup delle bundle critiche (versioni)

Punti finale

GET

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

Recupera informazioni sulla bundle. Restituisce 50 bundle per pagina.

Parametri di query

• app_id: Obbligatorio. L'ID del tuo app
• page: Facoltativo. 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
}

Richiesta di Esempio

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

Risposta di Esempio

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

Richieste di esempio

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

Crea 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 sul link e sul commento.

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/

Assegna un bundle a 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
}

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 relative 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. Riavvio dell'applicazione

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

Considerazioni di archiviazione

1. Politica di conservazione: Definisci per quanto tempo conservare i vecchi bundle
2. Gestione delle dimensioni : Monitora le dimensioni dei bundle e l'utilizzo dello spazio di archiviazione
3. Strategia di backup : Considera di backup le versioni critiche dei bundle
4. Optimizzazione dei costi: Rimuovi le bundle non necessarie per ottimizzare i costi di archiviazione

Continua da Bundles

Se stai utilizzando Bundles per pianificare l'archiviazione e il gestione dei file, connettilo con @capgo/capacitor-archiviazione-dati-sqlite per i dettagli di implementazione in @capgo/capacitor-archiviazione-dati-sqlite, Utilizza @capgo/capacitor-archiviazione-dati-sqlite per la capacità nativa in Utilizza @capgo/capacitor-archiviazione-dati-sqlite, @capgo/capacitor-file per i dettagli di implementazione in @capgo/capacitor-file, Usando @capgo/capacitor-file per la capacità nativa in Usando @capgo/capacitor-file, e @capgo/capacitor-uploader per il dettaglio di implementazione in @capgo/capacitor-uploader.