Avvio

Installa

Puoi utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo abilità al tuo strumento di AI utilizzando il seguente comando:

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

Usa poi 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 l'installazione manuale, installa il plugin eseguendo:

npm install @capgo/capacitor-asset-cache
npx cap sync

Importa

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

Configura un CDN

Configura l'URL base del CDN una volta che il tuo app inizia. Le relative percorso degli asset saranno risolti in base a questa 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');

Leggi un'immagine o un video

bind è il percorso di visualizzazione più trasparente. Segna l'elemento come caricamento, recupera o riconvalida l'asset in modo nativo, quindi assegna l'URL della fonte 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

The elemento non riceve mai l'URL CDN nella path di successo. Riceve l'URL del webview locale dopo che l'asset esiste nel 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 tuo framework controlla già lo stato di caricamento e di errore. La promessa si risolve con una stringa di origine 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 di metadati:

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

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

Asset protetti

Passa i header al fetch nativo. Questo è utile per percorsi CDN firmati, media autenticati o token a breve durata.

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

I header vengono utilizzati dal plugin mentre si effettua il fetch o la riconvalidazione del file remoto. L'immagine o il tag video riceve comunque solo l'URL di origine locale restituito dal plugin.

Riconvalidazione

Imposta una strategia di default 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 memorizzato è sufficiente fino a quando non lo rimuovi esplicitamente.
ttl	Vuoi una semplice finestra di freschezza.
always	Vuoi che il plugin controlli l'asset remoto ogni volta.
etag	Il tuo CDN restituisce intestazioni ETag stabili.
last-modified	Il tuo CDN restituisce intestazioni Last-Modified affidabili.

Archiviazione e Privacy

• iOS memorizza i file sotto Application Support e esclude la radice della cache dal backup iCloud.
• I dispositivi Android memorizzano i file nella directory dei file interni dell'applicazione.
• Web utilizza il cache del browser API e i metadati di localStorage come fallback di sviluppo.
• I file memorizzati sono nascosti all'interno del sandbox dell'applicazione, non sono salvati nei media pubblici dell'utente.
• I file memorizzati vengono eliminati alla disinstallazione, pulizia dei dati dell'applicazione o plugin clear() o remove().

Il cache è persistente, ma non è un confine di sicurezza da solo. Crittografa gli asset altamente sensibili prima di servirli se devono rimanere inaccessibili su un dispositivo compromesso.

Controllo avanzato del cache

La maggior parte dell'interfaccia utente code dovrebbe utilizzare bind, src, o resolveUtilizza questi aiuti quando hai bisogno di un gestione del cache esplicita:

Metodo	Descrizione
get	Risolve un URL remoto in metadati di file nativi.
list	Restituisci asset memorizzati che ancora esistono sul disco.
getCacheSize	Restituisci byte totali memorizzati.
remove	Elimina un singolo asset memorizzato per chiave o URL.
clear	Elimina ogni asset memorizzato 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-cache-asset/
• Package: @capgo/capacitor-asset-cache