Bundles

Bundles sind die Kernaktualisierungs-Pakete in Capgo. Jedes Bundle enthält die Web-Assets (HTML, CSS, JS), die den Inhalt Ihrer App ausmachen. Die Bundles API ermöglichen Ihnen, diese Aktualisierungs-Pakete 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: 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 Trackinginformationen

Manuelle Bundle-Erstellung (ohne CLI)

Hier erfahren Sie, wie Sie Bundles manuell ohne die Verwendung von Capgo CLI erstellen und hochladen:

Schritt 1: App erstellen

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

npm run build

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

Wichtig (Seite: Bug-bounty-Programm-Seite. Rolle: UI-Label. Gesehen in: Seite bug-bounty.astro. Nachrichten Schlüssel `bug_bounty_important_label` (Wichtige Nachricht für Bug-Bounty)): 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

Erstellen Sie ein Zip-Bundle mit JavaScript (gleichartig wie Capgo CLI)

Hinweis: In den folgenden Beispielen bezieht sich __CAPGO_KEEP_0__ auf die von __CAPGO_KEEP_0__ verwendete Bundle (Version) Bezeichnung. version refers to the bundle (version) name used by the 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();

Abschnitt mit dem Titel „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: Hochladen des Bundles in Ihren Speicher

Laden Sie Ihr Zip-Datei in einen webzugänglichen Speicher hoch.

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

WichtigIhr Bundle muss (I removed the placeholder __CAPGO_KEEP_0__ as it was not provided in the source text) öffentlich zugänglich Ü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 mit 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. (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 index.html auf der obersten Ebene
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 zippen, 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);

Abhängigkeiten installieren:

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: Entfernen Sie regelmäßig nicht benötigte Bundles
3. Kompatibilität von Bundles (Version): Legen Sie die geeigneten Mindestanforderungen für die native Version fest
4. Backup-Strategie: Halten Sie Backup-Kopien kritischer Bundles (Versionen) aufrecht

Endpunkte

GET

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

Abrufen von Bundle-Informationen. Gibt 50 Bundles 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"

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

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

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

Erstelle 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

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 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
  target?: "auto" | "stable" | "rollout" // default: auto
}

target Steuert, wo das Bundle verknüpft ist, wenn beim Kanal eine progressive Rollout-Konfiguration eingerichtet ist:

• auto — Rollout-Ziel, wenn eine progressive Rollout-Konfiguration eingerichtet ist; stabil andernfalls (Standard).
• rollout — Setze immer das Rollout-Ziel; stabiles Fallback bleibt unverändert.
• stable — Ersetze stabiles Fallback (Notfallausgang).

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 Fehlerzenarien 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 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ückhalteregelung: Definieren Sie die Zeit, die alte Pakete aufbewahren sollen
2. Größe-Verwaltung: Überwachen Sie die Größe der Pakete und die Speicherplatznutzung
3. Sicherheitsstrategie: Überlegen Sie, kritische Pakete (Versionen) sichern zu lassen
4. Kostenoptimierung: Entfernen Sie unnötige Pakete, um die Speicherplatzkosten zu optimieren

Weiter von Paketen

Wenn Sie "Pakete" verwenden Pakete um Speicher und Dateihandling zu planen, verbinden Sie es mit @capgo/capacitor-Speicherplatz-Dateisystem zur Implementierungsdetail in @capgo/capacitor-Speicherplatz-Dateisystem, Mit @capgo/capacitor-Speicherplatz-Dateisystem zur nativen Fähigkeit in Mit @capgo/capacitor-Speicherplatz-Dateisystem, @capgo/capacitor-Datei zur Implementierungsdetail in @capgo/capacitor-Datei, Mit @capgo/capacitor-Datei zur nativen Fähigkeit in Mit @capgo/capacitor-Datei und @capgo/capacitor-Uploader zur Implementierungsdetail in @capgo/capacitor-Uploader.