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.

Abschnitt mit dem Titel “Bundles verstehen”

Bundle (Version)

• : Semantische Versionsnummer für das Bundle: Eindeutiger Hash zur Überprüfung der Integrität des Bundles
• Bundles sind die Kernaktualisierungsdateien in __CAPGO_KEEP_0__. Jeder Bundle enthält die Web-Assets (HTML, CSS, JS), die den Inhalt Ihrer App ausmachen. Die Bundles __CAPGO_KEEP_1__ ermöglichen Ihnen, diese Aktualisierungsdateien zu verwalten, einschließlich der Auflistung und Löschung.Ein Bundle stellt eine bestimmte Version Ihres Apps-Webinhalts dar und enthält:
• Speicher-Info: Details über den Ort und die Art der Speicherung der Bundle
• Native Anforderungen: Mindestanforderungen an die native App-Version
• Metadaten: Erstellungszeit, Eigentumsrechte und andere Tracking-Informationen

Manuelle Bundle-Erstellung (Ohne CLI)

Hier erfahren Sie, wie Sie Bundle manuell erstellen und hochladen können, ohne die Capgo CLI zu verwenden:

Schritt 1: App erstellen

Zuerst müssen Sie die Web-Assets Ihrer App erstellen:

npm run build

Schritt 2: Erstelle eine Bundle-Zip-Datei mit denselben Paketen wie Capgo CLI

Wichtig: Verwende die genauen JavaScript-Pakete, die Capgo CLI intern verwendet, um die Kompatibilität sicherzustellen.

Installiere erforderliche Pakete

npm install adm-zip @tomasklaen/checksum

Erstelle eine Zip-Bundle mit JavaScript (gleich Capgo CLI)

Hinweis: In den folgenden Beispielen bezieht sich __CAPGO_KEEP_0__ auf den Namen der Bundle (Version) verwendet durch das __CAPGO_KEEP_0__. version API bezieht sich auf den Namen der Bundle (Version) verwendet durch das 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();

Schritt 3: Berechnen Sie den SHA256-Prüfsummen mithilfe der gleichen Pakete wie 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();

Schritt 4: Hochladen Sie das Bundle in Ihr Speicher

Hochladen Sie Ihr Zip-Datei an einen webzugänglichen Speicher:

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

Wichtig: Ihr Bundle muss öffentlich über einen HTTPS-URL (keine Authentifizierung erforderlich) zugänglich sein. __CAPGO_KEEP_0__’s Server müssen das Bundle von dieser URL herunterladen. über einen öffentlichen HTTPS-URL zugänglich via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

Schritt 5: Registrieren Sie Ihr Bundle bei __CAPGO_KEEP_0__ __CAPGO_KEEP_1__

• 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

Abschnitt mit dem Titel ‘Schritt 5: Registrieren Sie Ihr Bundle bei Capgo API’

Register the external bundle with Capgo using direct API calls:

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

Abschnitt mit dem Titel ‘API-Parameter’

Beschreibung	Parameter	Erforderlich
app_id	Ihre App-Identifikation	Ja
version	Bündel (Version) semantische Version (z.B. „1.2.3“)	Ja
external_url	Öffentlich zugänglich HTTPS-URL, an der das Bündel heruntergeladen werden kann (keine Auth erforderlich)	Ja
checksum	SHA256-Prüfsumme des Zip-Dateis	Ja

Anforderungen an die Bündelstruktur

Ihr Bundle ZIP muss folgende Anforderungen erfüllen:

1. Root-Index-Datei: Muss haben index.html auf der obersten Ebene
2. Capacitor-Integration: Muss aufrufen notifyAppReady() in Ihrer App code
3. Asset-Pfade: Verwenden Sie relative Pfade für alle Assets

Gültige Bundle-Struktur

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

Vollständiges Manuell-Workflow-Beispiel

Einfaches Node.js-Skript zum Ziehen, Prüfen der Integrität und Hochladen auf 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);

Abhängigkeiten installieren:

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

Prüfung der Integrität

JavaScript-Integritätsberechnung (Gleichbedeutend mit Capgo CLI)

Verwenden Sie die gleiche Pakete und Methode, die Capgo CLI intern verwendet:

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

Prüfsummenwichtigkeit

• Bundle-Integrität: Stellt sicher, dass das Bundle während der Übertragung nicht beschädigt wurde
• API-Verifizierung: Capgo überprüft Prüfsummen, bevor es Bundles akzeptiert
• Plugin-Verifizierung: Das mobile Plugin überprüft Prüfsummen, bevor es Updates anwendet

Gute Praxis

1. Bundle- (Version)-Verwaltung: Verwenden Sie konsistentes semantisches Versionsmanagement
2. Speicheroptimierung: Entfernen Sie unbegrenzte Bundel regelmäßig
3. Kompatibilität von Bundel (Version): Legen Sie die Mindestanforderungen an die native Version fest
4. Backup-Strategie: Halten Sie Backup-Kopien kritischer Bundel (Versionen) auf

Endpunkte

GET

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

Abrufen von Bundelinformationen. Gibt 50 Bundel pro Seite zurück.

Anfrageparameter

• app_id: Pflichtfeld. Die ID Ihrer App
• page: Optional. Seitennummer für die Paginierung

Antworttyp

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
}

Beispielanfrage

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

Beispielergebnis

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

Einen oder alle Bundles für eine App löschen. Verwenden Sie Vorsicht, da diese Aktion nicht rückgängig gemacht werden kann.

Abfrageparameter

Für die Löschung eines bestimmten Bundles:

interface BundleDelete {
  app_id: string
  version: string
}

Für die Löschung aller Bundles:

interface BundleDeleteAll {
  app_id: string
}

Beispielanfragen

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

Erfolgsantwort

{
  "status": "ok"
}

POST

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

Anforderungskörper

Beispielanforderung

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

Beispielanfrage

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/

Erfolgreiche Antwort

{
  "status": "ok"
}

POST (Metadaten)

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

Bündelmetadaten wie Link- und Kommentarinformationen aktualisieren.

Anforderungskörper

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

Beispielanfrage

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

Erfolgsantwort

{
  "status": "success"
}

PUT

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

Ein Bundle einer bestimmten Kanal zuweisen. Dies verknüpft ein Bundle (Version) mit einem Kanal für die Verteilung.

Anforderungskörper

interface SetChannelBody {
  app_id: string
  version_id: number // bundle (version) id
  channel_id: number
}

Beispielanfrage

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/

Erfolgreiche Antwort

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

Fehlerbehandlung

Gemeinsame Fehlerfälle und ihre Antworten:

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

Gemeinsame Verwendungsfälle

1. Alte Pakete bereinigen (Versionen)

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

2. App-Neustart

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

Speicherbedenken

1. Aufbewahrungsrichtlinie: Definieren Sie, wie lange alte Pakete aufbewahrt werden sollen
2. Größenmanagement: Monitor Paketgrößen und Speicherplatznutzung
3. Backup-Strategie: Überlegen Sie, kritische Pakete (Versionen) zu sichern
4. Kostenoptimierung: Entfernen Sie unnötige Pakete, um Speicherplatzkosten zu optimieren