Bundles

I pacchetti Bundle sono i pacchetti di aggiornamento centrali 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 lista e la cancellazione di essi.

Capire i Bundle

Un bundle rappresenta una versione specifica del contenuto web del tuo app e include:

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

Prima, costruisci gli asset web dell'app:

npm run build

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

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

Installare i Pacchetti Richiesti

npm install adm-zip @tomasklaen/checksum

Creare un Pacchetto Zip con JavaScript (Lo stesso di Capgo CLI)

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

Fase 3: Calcolare il Checksum SHA256 Usando 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 via 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"

Importantecontexto: Pagina/area: Pagina del programma di ricompensa per bug. Ruolo: Etichetta di interfaccia utente. Visualizzato in: pagina bug-bounty.astro. Chiave di messaggio `bug_bounty_important_label` (Etichetta importante del programma di ricompensa per bug). : Il tuo bundle deve essere via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

tramite URL HTTPS (nessuna autenticazione richiesta). I server di __CAPGO_KEEP_0__ devono scaricare il bundle da questo URL.

• 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

Step 5: Register Bundle with 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'app	Sì
version	Bundle (versione) versione semantica 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 At livello radice
2. Capacitor Integration: Deve chiamare notifyAppReady() in il tuo app code
3. Percorsi di Risorse: Utilizzare percorsi relativi per tutte le risorse

Struttura della Raccolta Valida

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

Esempio completo del Flusso di Lavoro Manuale

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 del Plugin: Il plugin mobile verifica i checksum prima di applicare gli aggiornamenti

Pratiche Consigliate

1. Gestione del Pacchetto (versione): Utilizza : versionamento semantico : in modo coerente
2. Optimizzazione del 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)

Punti di Accesso

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
}

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/

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 di collegamento e 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/

Imposta un bundle su 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 errore 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"
}

Uso comune

1. Pulizia vecchi 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 vecchi bundle
2. Gestione della dimensione: Monitora le dimensioni dei bundle e l'utilizzo della memoria
3. Estrategia di Backup: Considerare l'archiviazione dei bundle critici (versioni)
4. Optimizzazione dei Costi: Eliminare i bundle non necessari per ottimizzare i costi di archiviazione

Continua da Bundles

Se stai utilizzando Bundles per pianificare l'archiviazione e il trattamento dei file, connettilo con @capgo/capacitor-data-storage-sqlite per i dettagli di implementazione in @capgo/capacitor-data-storage-sqlite Utilizzando @capgo/capacitor-data-storage-sqlite per la capacità nativa in Utilizzare @capgo/capacitor-dati-di-archiviazione-sqlite, @capgo/capacitor-file per il dettaglio di implementazione in @capgo/capacitor-file, Utilizzare @capgo/capacitor-file per la capacità nativa in Utilizzare @capgo/capacitor-file, e @capgo/capacitor-caricatore for the implementation detail in @capgo/capacitor-uploader.