Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo:

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

Importa

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

Avvio rapido

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

await nativePlugin.cancel();

Errori comuni

• Sync nativo: esegui npx cap sync dopo gli aggiornamenti dei plugin.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Configura un CDN

Configura una volta l'URL base del CDN all'avvio dell'app. I percorsi relativi delle risorse verranno risolti rispetto a questo URL.

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

Puoi saltare cdnUrl se passi URL assoluti a bind, src, o resolve.

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

Associa un'immagine o un video

bind è il percorso di visualizzazione più trasparente. Segna l'elemento come in caricamento, recupera o riconvalida l'asset nativamente, quindi assegna l'URL della sorgente locale quando il file locale è pronto.

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;
}

Nota

L'elemento non riceve mai l'URL del CDN nel percorso di successo. Riceve l'URL locale del webview dopo che l'asset è presente nello storage persistente.

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>

Fonte diretta per lo stato del framework

Usa src quando il framework gestisce già il caricamento e lo stato degli errori. La promise si risolve con una stringa di fonte locale solo dopo che il file locale esiste.

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

videoElement.src = src;

Usa resolve quando hai anche bisogno dei metadati:

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

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

Asset protetti

Passa gli header al fetch nativo. Utile per percorsi CDN firmati, media autenticati o token a scadenza breve.

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

Le Headers vengono utilizzate dal plugin durante il fetch o la revalidazione del file remoto. Il tag image o video riceve comunque solo l'URL della sorgente locale restituito dal plugin.

Rivalidazione

Imposta una strategia predefinita con configure o sovrascrivila per un singolo asset.

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

Strategie disponibili:

Strategia	Usa quando
never	Un file locale in cache è sufficiente finché non lo rimuovi esplicitamente.
ttl	Vuoi una semplice finestra di validità.
always	Vuoi che il plugin controlli l'asset remoto ogni volta.
etag	Il tuo CDN restituisce header ETag stabili.
last-modified	Il tuo CDN restituisce header Last-Modified affidabili.

Storage e privacy

• iOS salva i file in Application Support ed esclude la radice della cache dal backup iCloud.
• Android salva i file nella directory interna dei file dell'app.
• Web usa la Cache del browser API e i metadati di localStorage come fallback di sviluppo.
• I file in cache sono nascosti all'interno del sandbox dell'app, non salvati nei media pubblici dell'utente.
• Cached files are removed on uninstall, app data clear, or plugin clear() oppure remove().

La cache è persistente, ma non è di per sé un confine di sicurezza. Crittografa gli asset altamente sensibili prima di servirli se devono restare illeggibili su un dispositivo compromesso.

Controllo avanzato della cache

La maggior parte delle UI code dovrebbe usare bind, src, o resolve. Usa questi helper quando ti serve gestire la cache in modo esplicito:

Metodo	Descrizione
get	Risolve un URL remoto nei metadati del file nativo.
list	Restituisce gli asset in cache ancora presenti su disco.
getCacheSize	Restituisce il totale dei byte in cache.
remove	Rimuove un asset in cache tramite chiave o URL.
clear	Rimuove ogni asset in cache gestito dal plugin.

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

Riferimento completo

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