Les Bundles

Bundles are the core update packages in Capgo. Each bundle contains the web assets (HTML, CSS, JS) that make up your app’s content. The Bundles API allows you to manage these update packages, including listing and deleting them.

Sous-titre : Comprendre les Bundles

Une bundle représente une version spécifique du contenu web de votre application et comprend :

• Numéro de version semantique: Numéro de version sémantique pour le paquet
• Checksum : Hash unique pour vérifier l'intégrité du paquet
• Informations de stockage : Détails sur l'emplacement et la manière dont le paquet est stocké
• Exigences natives : Exigences minimales de version de l'application native
• Métadonnées : Temps de création, propriété et autres informations de suivi

Création manuelle du paquet (Sans CLI)

Voici comment créer et télécharger des paquets manuellement sans utiliser le Capgo CLI :

Étape 1 : Créez votre application

First, build your app’s web assets:

npm run build

Étape 2 : Créez un fichier ZIP de bundle en utilisant les mêmes packages que Capgo CLI

Important: Utilisez les mêmes packages JavaScript exacts que Capgo CLI utilise internement pour garantir la compatibilité.

Installez les packages requis

npm install adm-zip @tomasklaen/checksum

Créer un fichier Zip avec JavaScript (Même que Capgo CLI)

Remarque : Dans les exemples ci-dessous, version se réfère au nom du fichier (version) utilisé par l’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();

Étape 3 : Calculer la somme de contrôle SHA256 à l'aide du même package que 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();

Étape 4 : Télécharger le fichier dans votre stockage

Téléchargez votre fichier zip vers un stockage accessible en ligne.

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

Important: Votre bundle doit être accessible au public via l'URL HTTPS (aucune authentication requise). Les serveurs de Capgo doivent télécharger le bundle à partir de cette URL.

Exemples de URL publiques valides :

• 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

Étape 5 : Inscrivez le bundle avec Capgo API

Inscrivez le bundle externe avec Capgo à l'aide d'appels directs 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;
}

Paramètres de API

Paramètre	Description	Obligatoire
app_id	Votre identifiant d'application	Oui
version	Version du paquet version semantique (par exemple, « 1.2.3 »)	Oui
external_url	Accessible au public URL HTTPS où le bundle peut être téléchargé (pas d'authentification requise)	Oui
checksum	Fichier zip avec somme de contrôle SHA256	Oui

Exigences de structure du paquet

Votre fichier zip de paquet doit respecter ces exigences :

1. Fichier d'index principal: Devoir avoir index.html au niveau racine
2. Intégration Capacitor: Devoir appeler notifyAppReady() à partir de votre application code
3. Chemins d'Actifs: Utilisez des chemins relatifs pour tous les actifs

Structure de Bundle Valide

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

Exemple complet du flux de travail manuel

Script Node.js simple pour zipper, calculer le checksum et télécharger sur 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);

Installez les dépendances :

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

Vérification de la cohérence de somme

Calcul de checksum JavaScript (Même que Capgo CLI)

Utilisez le même paquet et la même méthode que Capgo CLI utilise internement :

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

Importance du checksum

• Intégrité du paquet: Assure que le paquet n'a pas été corrompu pendant le transfert
• API de la vérification: Capgo vérifie les sommets de contrôl’avant d'accepter les paquets
• Vérification des plugins: Le plugin mobile vérifie les checksums avant d'appliquer les mises à jour.

Meilleures Pratiques

1. Gestion des Bundles (version): Utilisez la gestion de version semantique consistently
2. Optimisation de Stockage: Supprimez périodiquement les bundles inutilisés
3. Compatibilité des Bundles (version): Définissez les exigences de version native minimale appropriées
4. Stratégie de sauvegarde: Sauvegardez des copies de sécurité des bundles critiques (versions)

Endpoints

GET

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

Récupérez les informations sur les bundles. Retourne 50 bundles par page.

Paramètres de requête

• app_id: Obligatoire. L'ID de votre application
• page: Facultatif. Numéro de page pour la pagination

Type de réponse

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
}

Exemple de requête

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

Exemple de réponse

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

Supprimer

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

Supprimer un ou plusieurs bundles pour une application. Utilisez avec précaution car cette action ne peut pas être annulée.

Paramètres de requête

Pour supprimer un bundle spécifique :

interface BundleDelete {
  app_id: string
  version: string
}

Pour supprimer tous les bundles :

interface BundleDeleteAll {
  app_id: string
}

Exemples de requêtes

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

Section intitulée « Réponse de succès »

{
  "status": "ok"
}

POST

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

Créer un nouveau bundle avec une URL externe.

Corps de la demande

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

Exemple de demande

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/

Réponse de succès

{
  "status": "ok"
}

POST (Métadonnées)

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

Mettre à jour les métadonnées du bundle, comme les informations de lien et de commentaire.

Corps de la demande

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

Exemple de demande

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

Réponse de Succès

{
  "status": "success"
}

PUT

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

Définir un bundle sur un canal spécifique. Cela relie un bundle (version) à un canal pour la distribution.

Corps de la demande

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

target détermine où le bundle est lié lorsque le canal a une mise à jour progressive configurée :

• auto — cible de mise à jour progressive lorsqu'elle est configurée ; stable sinon (par défaut).
• rollout — définir toujours la cible de mise à jour ; fallback stable inchangé.
• stable — remplacez la version stable par défaut (échappatoire).

Exemple de requête

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/

Réponse de succès

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

Gestion des erreurs

Scénarios d'erreurs courants et leurs réponses :

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

Utilisations courantes

1. Nettoyage des anciens bundles (versions)

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

2. App Reset

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

Considérations de stockage

1. Politique de conservationDéfinir la durée de conservation des anciens bundles
2. Gestion de la taille: Monitor bundle sizes and storage usage
3. Stratégie de sauvegarde: Pensez à sauvegarder les bundles critiques (versions)
4. Optimisation des coûts: Supprimez les bundles inutiles pour optimiser les coûts de stockage

Continuez avec les Bundles

Si vous utilisez les Bundles pour planifier le stockage et la gestion des fichiers, connectez-l’avec @capgo/capacitor-stockage-de-données-sqlite pour les détails d'implémentation dans @capgo/capacitor-stockage-de-données-sqlite, Utilisation de @capgo/capacitor-stockage-de-données-sqlite pour la capacité native dans Utiliser @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-fichier pour le détail d'implémentation dans @capgo/capacitor-fichier, Utiliser @capgo/capacitor-fichier pour la capacité native dans Utiliser @capgo/capacitor-fichier, et @capgo/capacitor-téléchargeur pour le détail d'implémentation dans @capgo/capacitor-téléchargeur.