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.

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

Ein Bundle stellt eine bestimmte Version Ihres Apps Webinhalts dar und enthält:

• Bundle (Version): Semantische Versionsnummer für das Bundle
• Prüfsumme: Eindeutiger Hash zur Verifizierung der Bundle-Integrität
• Speicherinformationen: Details über den Ort und die Art der Speicherung des Bundles
• Native Anforderungen: Mindestanforderungen an die native App-Version
• Metadaten: Erstellungszeit, Eigentumsrecht und andere Tracking-Informationen

Manuelle Bundle-Erstellung (Ohne CLI)

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

Schritt 1: App erstellen

Zunächst müssen Sie die Web-Assets Ihrer App erstellen:

npm run build

Schritt 2: Erstellen Sie ein Bundle-Zip mit denselben Paketen wie Capgo CLI

Wichtig: Verwenden Sie die gleichen JavaScript-Pakete, die Capgo CLI intern verwendet, um die Kompatibilität sicherzustellen.

Installieren Sie erforderliche Pakete

npm install adm-zip @tomasklaen/checksum

Erstelle Zip-Bundle mit JavaScript (Gleich wie Capgo CLI)

Hinweis: In den folgenden Beispielen wird version bezieht sich auf den Bundle- (Version)-namen, der von API verwendet wird.

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üfsummenwert mit demselben Paket 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: Bundle hochladen auf Ihr Speichermedium

Hochladen Sie Ihr zip-Datei auf ein webzugängliches Speichermedium:

# 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 über eine HTTPS-URL (keine Authentifizierung erforderlich) öffentlich zugänglich sein. via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

Schritt 5: Bundle bei __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ registrieren

• 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

Registrieren Sie das externe Bundle mit Capgo mithilfe direkter API-Aufrufe:

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-Parameter

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

Anforderungen an die Bundle-Struktur

Ihr Bundle-Zip muss folgende Anforderungen erfüllen:

1. Hauptindexdatei: Muss vorhanden sein index.html auf der Wurzelstufe
2. Capacitor-Integration: Muss aufgerufen werden 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 Manueller Workflow-Beispiel

Einfaches Node.js-Skript, um zu komprimieren, zu überprüfen und hochzuladen 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);

Installieren Sie die Abhängigkeiten:

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

Prüfsummenüberprüfung

JavaScript-Prüfsummenberechnung (Gleichbedeutend mit Capgo CLI)

Verwenden Sie die gleiche Paket- 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üfsummenbedeutung

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

Gute Praxis

1. Bundle- (Version) -Verwaltung: Verwende semantische Versionsnummerierung konsistent
2. Speicheroptimierung: Entferne unbegrenzte Bundel regelmäßig
3. Bundle (Version) - Kompatibilität: Setze die geeigneten Mindestanforderungen für die native Version
4. Backup-Strategie: Halte Backup-Kopien kritischer Bundel (Versionen) aufrecht

Endpunkte

GET

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

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

Abfrageparameter

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

Beispielsantwort

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

LÖSCHEN

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

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

Abfrageparameter

Für das Löschen eines bestimmten Pakets:

interface BundleDelete {
  app_id: string
  version: string
}

Für das Löschen aller Pakete:

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/

Ein neues Bundle mit externer URL erstellen.

Anforderungskörper

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

Aktualisieren Sie die Bundle-Metadaten wie Link- und Kommentarinformationen.

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

Erfolgreiche Antwort

{
  "status": "success"
}

PUT

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

Ein Bundle auf eine bestimmte Kanal setzen. Dies verbindet 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/

Erfolgsantwort

{
  "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 Anwendungsfälle

1. Alte Pakete (Versionen) bereinigen

// 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. AufbewahrungsrichtlinieDefinieren Sie die Zeit, für die alte Pakete aufbewahrt werden sollen
2. GrößenmanagementÜberwachen Sie die Größe der Pakete und die Speicherplatznutzung
3. Sicherheitsstrategie: Überlegen Sie, ob Sie kritische Bundles (Versionen) sichern sollten
4. Kostenoptimierung: Entfernen Sie unnötige Bundles, um die Speicherungskosten zu optimieren

Weiter von Bundles

Wenn Sie Bundles verwenden Bundles um die Speicherung und Dateihandling zu planen, verbinden Sie es mit @capgo/capacitor-data-storage-sqlite für die Implementierungsdetails in @capgo/capacitor-data-storage-sqlite Mit @capgo/capacitor-data-storage-sqlite für die native Fähigkeit in @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-datei für die Implementierungsdetail in @capgo/capacitor-datei, Mit @capgo/capacitor-datei für die native Fähigkeit in Mit @capgo/capacitor-datei, und @capgo/capacitor-hochloader für die Implementierungsdetail in @capgo/capacitor-hochloader.