Erste Schritte

Installieren

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

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

Nutze anschließend 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 eine manuelle Installation 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 Fehlerquellen

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

CDN konfigurieren

Konfiguriere beim App-Start einmal die CDN-Base-URL. Relative Asset-Pfade werden dann über diese URL aufgelöst.

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

Du kannst diesen Schritt überspringen, cdnUrl 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 Display-Pfad. Er markiert das Element als ladend, lädt oder revalidiert das Asset nativ und weist die lokale Source-URL zu, sobald die 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

Im Erfolgsfall erhält das Element nie die CDN-URL. Stattdessen erhält es die lokale Webview-URL, sobald 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-State

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

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

videoElement.src = src;

Nutze 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}`,
  },
});

Die Header werden vom Plugin beim Abrufen oder Revalidieren der Remote-Datei verwendet. Das Image- oder Video-Tag erhält weiterhin nur die lokale Source-URL, die das Plugin zurückgibt.

Revalidierung

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

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

Verfügbare Strategien:

Strategie	Anwenden, wenn
never	Eine lokale Cache-Datei ausreicht, bis sie explizit gelöscht wird.
ttl	Du möchtest ein einfaches Freshness-Fenster.
always	Das Plugin das Remote-Asset jedes Mal prüfen soll.
etag	Dein CDN stabile ETag-Header liefert.
last-modified	Dein CDN zuverlässige Last-Modified-Header liefert.

Speicher & Datenschutz

• iOS speichert Dateien unter Application Support und schließt den Cache-Root vom iCloud-Backup 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 liegen versteckt im App-Sandbox und werden nicht in den öffentlichen Medien des Nutzers gespeichert.
• Gecachte Dateien werden bei Deinstallation, dem Löschen der App-Daten oder dem Plugin- clear() oder remove().

Der Cache ist persistent, stellt aber für sich genommen keine Sicherheitsbarriere dar. Verschlüssele hochsensible Assets vor der Bereitstellung, falls diese auf einem kompromittierten Gerät unlesbar bleiben müssen.

Erweiterte Cache-Steuerung

Die meisten UI code sollten bind, src, oder resolveNutze diese Helfer für explizites Cache-Management:

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

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