Bundles

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

Capire i Pacchetti

Un pacchetto rappresenta una versione specifica del contenuto web dell'applicazione e include:

• Versione del pacchetto: Numero di versione semantico per il pacchetto
• Checksum: Hash univoco per verificare l'integrità del pacchetto
• Informazioni di archiviazione: Dettagli su dove e come il bundle viene archiviato
• Requisiti nativi: Requisiti minimi di versione dell'app nativa
• Metadati: Tempo 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 gli asset web dell'app:

npm run build

Passo 2: Crea archivio zip utilizzando le stesse librerie di Capgo CLI

Importante: Utilizza le stesse librerie JavaScript esattamente come Capgo CLI le utilizza internamente per garantire la compatibilità.

Installa le librerie richieste

npm install adm-zip @tomasklaen/checksum

Crea archivio zip con JavaScript (lo stesso di Capgo CLI)

Nota: Nelle esempi che seguono, version si riferisce al nome del pacchetto (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: Calcola il checksum SHA256 utilizzando lo stesso pacchetto come 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 pacchetto nella tua archiviazione

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 pacchetto deve accessibile al pubblico tramite l'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;
}

Parametri di API

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

Requisiti di struttura del pacchetto

Il tuo pacchetto zip deve seguire queste richieste:

1. File di Indice Radice: Deve avere index.html al livello radice
2. Integrazione Capacitor: Deve chiamare notifyAppReady() nel tuo app code
3. Perimetrazioni degli Asset: Utilizzare percorsi relativi per tutti gli asset

Struttura di Pacchetto Validata

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

Esempio completo del flusso di lavoro manuale

Script Node.js semplice per creare un archivio, calcolare il 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 in 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 del plugin: Il plugin mobile verifica i checksum prima di applicare gli aggiornamenti

Pratiche raccomandate

1. Gestione di bundle (versione): Utilizza semantica versioning consistente
2. Optimizzazione di Storage: Rimuovi periodicamente i bundle non utilizzati
3. Compatibilità di bundle (versione): Imposta le richieste di versione nativa minima appropriate
4. Strategia di Backup: Mantieni backup dei bundle critici (versioni)

Endpoint

GET

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

Recupera informazioni sul 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
}

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"

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

DELETE

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/

Crea un nuovo pacchetto 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 commento.

__CAPGO_KEEP_0__

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
}

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

Utilizzo comune

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 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 effettuare un backup dei bundle critici (versioni)
4. Optimizzazione dei costi: Elimina i bundle non necessari per ottimizzare i costi di archiviazione

Continua da qui da Bundles

Bundles If you are using __CAPGO_KEEP_0__ per pianificare lo storage e la gestione dei file, connettilo con @capgo/capacitor-storage-dati-sqlite per i dettagli di implementazione in @capgo/capacitor-storage-dati-sqlite, Utilizzare @capgo/capacitor-storage-dati-sqlite per la capacità nativa in Utilizzare @capgo/capacitor-storage-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 @capgo/capacitor-uploader per i dettagli di implementazione in @capgo/capacitor-uploader.