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öglichen Ihnen, diese Aktualisierungsdateien zu verwalten, einschließlich der Auflistung und Löschung.

Bundles verstehen

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

• Bundle (Version): Semantische Versionsnummer für das Bundle
• Prüfsumme: Eindeutige Hash, um die Integrität des Bundles zu überprüfen
• Speicherinformationen: Details über den Ort und die Art der Speicherung des Bundles
• Native Anforderungen: Mindestanforderungen für native Apps
• Metadaten: Erstellungszeit, Eigentumsrechte 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

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

npm run build

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

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

Installieren von erforderlichen Paketen

npm install adm-zip @tomasklaen/checksum

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

Hinweis: In den folgenden Beispielen bezieht sich version auf die vom API verwendete Bundle (Version)-Bezeichnung.

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 gleicher Paketdatei 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 Sie Ihr Zip-Datei in 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 öffentliche zugänglich sein über HTTPS-URL (keine Authentifizierung erforderlich). Capgo’s Server müssen das Bundle von dieser URL herunterladen.

Beispiele für gültige öffentliche URLs:

• 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

Schritt 5: Registrieren Sie das Bundle bei Capgo API

Registrieren Sie das externe Bundle bei 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	Pflichtfeld
app_id	Die Identifikation Ihres Apps	Yes
version	Paket (Version) semantische Version (z.B. „1.2.3“)	Yes
external_url	Öffentlich zugänglich HTTPS-URL, an der das Paket heruntergeladen werden kann (keine Auth erforderlich)	Yes
checksum	SHA256-Prüfsumme des Zip-Dateis	Yes

Paketstruktur-Anforderungen

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 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-Integritätsberechnung (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ü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 semantische Versionsnummerierung konsistent
2. Speicheroptimierung: Entfernen Sie periodisch nicht benötigte Bundles
3. Kompatibilität von Bundles (Version): Legen Sie die geeigneten Mindestanforderungen an die native Version fest
4. Sicherheitsstrategie: Halten Sie Backup-Kopien von kritischen Bundles (Versionen) auf

Endpunkte

GET

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

Bündelinformationen abrufen. Gibt 50 Bündel pro Seite zurück.

Abfrageparameter

• app_id: Pflichtfeld. Die ID Ihres Apps
• 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"
    }
  ]
}

DELETE

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

Erfolgreiche Antwort

{
  "status": "ok"
}

POST

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

Erstellen Sie ein neues 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/

Erfolgreiche Antwort

{
  "status": "ok"
}

POST (Metadaten)

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

Das Update von 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 verbindet 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 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. Rückhalteregelung: Länge für alte Bundles festlegen
2. Größenverwaltung: Überwache die Größe von Bundles und den Speicherplatzverbrauch
3. Backup-Strategie: Überlege, kritische Bundles (Versionen) zu sichern
4. Kostenoptimierung: Entferne unnötige Bundles, um den Speicherplatzkosten zu optimieren

Fortsetzen von Bundles

Wenn Sie Bundles verwenden Bundles um den Speicherplatz und die Dateiverwaltung zu planen, verbinden Sie es mit @capgo/capacitor-Speicherung in einer Datenbank für die Implementierungsdetails in @capgo/capacitor-Speicherung in einer Datenbank Verwendung von @capgo/capacitor-Speicherung in einer Datenbank für die native Fähigkeit in Verwendung von @capgo/capacitor-Speicherung in einer Datenbank @capgo/capacitor-Datei für die Implementierungsdetails in @capgo/capacitor-Datei Verwendung von @capgo/capacitor-Datei für die native Fähigkeit in Verwendung von @capgo/capacitor-Datei und @capgo/capacitor-Hochloader für die Implementierungsdetails in @capgo/capacitor-Hochloader