Guida rapida

Installazione

Puoi usare il nostro Setup assistito dall'AI per installare il plugin. Aggiungi le skill Capgo al tuo tool AI con il comando seguente:

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

Poi usa questo 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 una CDN

Configura una volta la base URL del CDN all'avvio dell'app. I percorsi relativi degli asset verranno risolti rispetto a questo URL.

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

Puoi saltare questo passaggio 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 revalida l'asset nativamente e assegna l'URL della sorgente locale quando il file è 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 della 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>

Sorgente diretta per lo stato del framework

Usa src quando il tuo framework gestisce già lo stato di caricamento e di errore. La promise si risolve con una stringa della sorgente locale solo dopo che il file locale esiste.

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

videoElement.src = src;

Usa resolve quando hai bisogno anche 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 breve scadenza.

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

Il plugin utilizza gli header durante il fetch o la revalidation del file remoto. Il tag image o video riceverà comunque solo l'URL della sorgente locale restituito dal plugin.

Revalidation

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 root della cache dal backup iCloud.
• Android salva i file nella directory interna dell'app.
• Il Web usa la Cache API del browser e i metadati di localStorage come fallback in sviluppo.
• I file in cache sono nascosti nel sandbox dell'app, non vengono salvati nei media pubblici dell'utente.
• Cached files are removed on uninstall, app data clear, or plugin clear() o remove().

La cache è persistente, ma non costituisce di per sé un confine di sicurezza. Cripta gli asset altamente sensibili prima di servirli se devono rimanere 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 di un file nativo.
list	Restituisce gli asset in cache che esistono ancora su disco.
getCacheSize	Restituisce il totale dei byte in cache.
remove	Rimuove un asset in cache tramite chiave o URL.
clear	Rimuove tutti gli asset in cache gestiti 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