Bundles

Bundles sind die Kernaktualisierungsdateien in Capgo. Jeder Bundle enthält die Web-Assets (HTML, CSS, JS), die den Inhalt Ihrer App ausmachen. Die Bundles API ermöglicht es Ihnen, diese Aktualisierungsdateien zu verwalten, einschließlich der Auflistung und Löschung.

Bundles verstehen

Eine Bundle stellt eine bestimmte Bundle-Version (Version) Ihres Apps-Webinhalts dar und enthält:

• Bundles (Version): Semantische Versionsnummer für die Bundle
• Prüfsumme: Eindeutige Hash zum Überprüfen der Paketintegrität
• Speicher-Info: Details über den Ort und die Art der Speicherung des Pakets
• Native Anforderungen: Mindestanforderungen an die native App-Version
• Metadaten: Erstellungszeit, Eigentumsrechte und andere Tracking-Informationen

Manuelle Paket-Erstellung (Ohne CLI)

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

Schritt 1: Erstellen Sie Ihre App

Zuerst bauen Sie die Web-Ressourcen Ihrer App:

npm run build

Schritt 2: Erstellen Sie einen Bundle-Zip-Datei 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 die erforderlichen Pakete

npm install adm-zip @tomasklaen/checksum

Erstellen Sie eine Zip-Bundle mit JavaScript (gleich wie Capgo CLI)

Hinweis: In den folgenden Beispielen wird version bezieht sich auf den Bundle-Namen (Version) der 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: Berechne SHA256-Prüfsumme 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: Hochladen des Bundles in Ihren Speicher

Hochladen Ihres Zip-Dateis in einem 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 ü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 HTTPS-URL (keine Authentifizierung erforderlich) zugänglich sein. via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

Schritt 5: Registrieren Sie das 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 das 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”

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. 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 Manuallayout-Beispiel

Einfaches Node.js-Skript zum Zipping, 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-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 Prüfsummen, bevor es Bundles akzeptiert
• Plugin-Überprüfung: Das mobile Plugin überprüft Prüfsummen, bevor es Updates anwendet

Gute Praktiken

1. Bundle (Version) Verwaltung: Verwende semantische Versionsnummerierung konsistent
2. Speicheroptimierung: Entferne periodisch nicht benötigte Bundles
3. Kompatibilität von Bundles (Versionen): Setze angemessene Mindestanforderungen an die native Version
4. Sicherheitsstrategie: Halte Backup-Kopien kritischer Bundles (Versionen) aufrecht

Endpoints

GET

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

Bündelinformationen abrufen. Gibt 50 Bündel 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"

Beispielantwort

{
  "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 einen oder alle Pakete für eine App. Verwenden Sie Vorsicht, da diese Aktion nicht rückgängig gemacht werden kann.

Abfrageparameter

Für die Löschung einer bestimmten Bundle:

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/

Erstelle eine neue Bundle mit externer URL.

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/

Erfolgsantwort

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

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.

Anforderungs-Body

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 Verwendungsfälle

1. Alte Bundle (Versionen) löschen

// 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. Rückgabepolitik: Definieren Sie, wie lange alte Pakete aufbewahrt werden sollen
2. Größenmanagement: Überwachen Sie die Größe der Pakete und die Speicherverwaltung
3. Sicherheitsstrategie: Überlegen Sie, ob Sie kritische Pakete (Versionen) sichern sollten
4. Kostenoptimierung: Entfernen Sie unnötige Pakete, um die Speicherkosten zu optimieren

Weiter von Paketen

Wenn Sie diese Funktion verwenden Bundles um Speicherplatz und Dateimanagement zu planen, verbinden Sie es mit @capgo/capacitor-data-storage-sqlite für die Implementierungsdetails in @capgo/capacitor-data-storage-sqlite Verwenden Sie @capgo/capacitor-data-storage-sqlite für die native Fähigkeit in Verwenden Sie @capgo/capacitor-data-storage-sqlite @capgo/capacitor-file für die Implementierungsdetails in @capgo/capacitor-file Verwenden Sie @capgo/capacitor-file für die native Fähigkeit in Verwenden Sie @capgo/capacitor-file, und @capgo/capacitor-uploader für die Implementierungsdetails in @capgo/capacitor-Uploader.