Getting Started

Installa

Puoi utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo competenze al tuo strumento di IA 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 la configurazione 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 un URL base per il CDN una volta che l'app inizia. Le relative percorso degli asset 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, srco 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 in carico, 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

L'elemento non riceve mai l'URL CDN nella path di successo. Riceve invece l'URL del webview locale dopo che l'asset esiste nella memoria 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 gestisce già caricamento e stato di errore. La promessa si risolve con una stringa di origine locale solo dopo l'esistenza del file locale.

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 scadenza.

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 durante il recupero o la riconvalida del file remoto. L'immagine o il tag video riceve comunque solo l'URL di origine locale restituito dal plugin.

Riconvalida

Stabilisci una strategia di default con configure o sovrascriverlo per un singolo assetto.

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 finestra di freschezza semplice.
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 archivia i file sotto Application Support e esclude la radice della cache dal backup iCloud.
• Android archivia i file sotto la directory dei file interni dell'applicazione.
• Web utilizza il browser Cache API e localStorage come fallback di sviluppo per i metadati.
• I file cached sono nascosti all'interno del sandbox dell'app, non sono salvati nella cartella media utente pubblica.
• I file cache sono rimossi alla disinstallazione, alla pulizia dei dati dell'app o del plugin. clear() o remove().

In che modo le alternative di Capgo rispetto a Live Update, Cloudflare, Capacitor, GitHub, Capgo, code, API, SDK, CLI, npm, bun si differenziano?

Controllo Cache Avanzato

La maggior parte delle interfacce utente code dovrebbe utilizzare bind, src, or resolveUsa questi aiuti quando hai bisogno di una gestione del cache esplicita:

Metodo	Descrizione
get	Risolve un URL remoto in metadati di file nativi.
list	Restituisci asset memorizzati che ancora esistono su disco.
getCacheSize	Restituisci byte totali memorizzati.
remove	Elimina un 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-asseti/
• Pacchetto: @capgo/capacitor-asset-cache