Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-asset-cache` plugin in my project.

Wenn du das manuelle Setup bevorzugst, installiere das Plugin mit:

bun add @capgo/capacitor-asset-cache
npx cap sync

Importieren

import { AssetCache } from '@capgo/capacitor-asset-cache';

Quickstart

import { nativePlugin } from '@capgo/capacitor-asset-cache';

await nativePlugin.cancel();

Häufige Stolperfallen

• Nativer Sync: ausführen npx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

CDN konfigurieren

Konfiguriere die CDN-Basis-URL einmal beim App-Start. Relative Asset-Pfade werden gegen diese URL aufgelöst.

AssetCache.configure({
  cdnUrl: 'https://cdn.example.com/assets/',
  revalidate: {
    strategy: 'ttl',
    maxAgeSeconds: 86400,
  },
});

Du kannst cdnUrl überspringen, wenn du absolute URLs an bind, src, oder resolve.

const src = await AssetCache.src('https://cdn.example.com/assets/videos/intro.mp4');

Bild oder Video binden

bind ist der transparenteste Anzeigepfad. Er markiert das Element als ladend, ruft das Asset nativ ab oder validiert es neu und setzt die lokale Quell-URL, sobald die lokale Datei bereit ist.

const image = document.querySelector<HTMLImageElement>('#hero');

if (image) {
  const binding = AssetCache.bind(image, 'images/hero.jpg');
  await binding.promise;
}

<img id="hero" alt="Product preview" />

img[data-asset-cache-state='loading'],
video[data-asset-cache-state='loading'] {
  opacity: 0.45;
}

img[data-asset-cache-state='ready'],
video[data-asset-cache-state='ready'] {
  opacity: 1;
}

Hinweis

Das Element erhält im Erfolgsfall nie die CDN-URL. Es erhält die lokale Webview-URL, nachdem das Asset im persistenten Speicher vorhanden ist.

React

import { useEffect, useRef } from 'react';
import { AssetCache } from '@capgo/capacitor-asset-cache';

AssetCache.configure({ cdnUrl: 'https://cdn.example.com/assets/' });

export function HeroImage() {
  const imageRef = useRef<HTMLImageElement>(null);

  useEffect(() => {
    if (!imageRef.current) return;

    const binding = AssetCache.bind(imageRef.current, 'images/hero.jpg');
    return () => binding.cancel();
  }, []);

  return <img ref={imageRef} alt="Product preview" />;
}

Vue

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';
import { AssetCache, type AssetCacheBinding } from '@capgo/capacitor-asset-cache';

const image = ref<HTMLImageElement | null>(null);
let binding: AssetCacheBinding | undefined;

onMounted(() => {
  if (image.value) {
    binding = AssetCache.bind(image.value, 'images/hero.jpg', {
      cdnUrl: 'https://cdn.example.com/assets/',
    });
  }
});

onUnmounted(() => binding?.cancel());
</script>

<template>
  <img ref="image" alt="Product preview" />
</template>

Direkte Quelle für Framework-Zustand

Nutzt src wenn dein Framework den Loading- und Error-State bereits steuert. Das Promise wird erst mit einem lokalen Source-String aufgelöst, sobald die lokale Datei existiert.

const src = await AssetCache.src('videos/intro.mp4');

videoElement.src = src;

Nutzt resolve wenn du zusätzlich Metadaten brauchst:

const source = await AssetCache.resolve('images/hero.jpg');

console.log(source.src, source.local, source.fromCache, source.status);

Geschützte Assets

Übergib Header an den nativen Fetch. Das ist nützlich für signierte CDN-Pfade, authentifizierte Medien oder kurzlebige Token.

const src = await AssetCache.src('private/videos/intro.mp4', {
  cdnUrl: 'https://cdn.example.com/assets/',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Das Plugin nutzt die Header beim Fetch oder Revalidieren der Remote-Datei. Das Image- oder Video-Tag erhält weiterhin nur die lokale Source-URL vom Plugin.

Revalidierung

Standardstrategie festlegen mit configure oder für ein einzelnes Asset überschreiben.

await AssetCache.src('videos/intro.mp4', {
  revalidate: {
    strategy: 'etag',
  },
});

Verfügbare Strategien:

Strategie	Anwendungsfall
never	Eine lokal zwischengespeicherte Datei reicht aus, bis sie explizit entfernt wird.
ttl	Sie möchten ein einfaches Aktualisierungsintervall.
always	Sie möchten, dass das Plugin das Remote-Asset jedes Mal überprüft.
etag	Ihr CDN liefert stabile ETag-Header.
last-modified	Ihr CDN liefert zuverlässige Last-Modified-Header.

Speicher und Datenschutz

• iOS speichert Dateien unter Application Support und schließt den Cache-Root von der iCloud-Sicherung aus.
• Android speichert Dateien im internen Verzeichnis der App.
• Web nutzt den Browser-Cache API und localStorage-Metadaten als Fallback für die Entwicklung.
• Gecachte Dateien sind im App-Sandbox verborgen und werden nicht in öffentlichen Benutzermedien gespeichert.
• Gecachte Dateien werden bei Deinstallation, Löschen der App-Daten oder Plugin entfernt clear() oder remove().

Der Cache ist persistent, aber keine Sicherheitsgrenze an sich. Verschlüsseln Sie hochsensible Assets vor dem Ausliefern, wenn sie auf einem kompromittierten Gerät unlesbar bleiben müssen.

Erweiterte Cache-Steuerung

Die meisten UI-code sollten bind, src, oder resolve. Nutze diese Helper, wenn du das Cache-Management explizit steuern willst:

Methode	Beschreibung
get	Löst eine Remote-URL in native Datei-Metadaten auf.
list	Gibt gecachte Assets zurück, die noch auf der Festplatte liegen.
getCacheSize	Gibt die gesamten gecachten Bytes zurück.
remove	Entfernt ein gecachtes Asset per Key oder URL.
clear	Entfernt alle gecachten Assets, die das Plugin verwaltet.

const asset = await AssetCache.get({
  url: 'https://cdn.example.com/assets/videos/intro.mp4',
  key: 'videos/intro.mp4',
  revalidate: { strategy: 'last-modified' },
});

Vollständige Referenz

• GitHub: https://github.com/Cap-go/capacitor-asset-cache/
• Paket: @capgo/capacitor-asset-cache