Inizia

Installazione

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo competenze al tuo strumento AI utilizzando il seguente comando:

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

Poi utilizza la seguente richiesta:

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 l'URL base del CDN una volta che il tuo app inizia. Le percorrenze relative degli asset saranno risolte 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 è la via di visualizzazione più trasparente. Segna l'elemento come in carico, recupera o riconvalida l'asset nativamente, 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 nel percorso di successo. Riceve l'URL del webview locale dopo che l'asset esiste nella memoria di archiviazione 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à il caricamento e lo stato degli errori. 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 intestazioni alla fetch nativa. 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 riconvalidazione del file remoto. L'immagine o il tag video riceve solo l'URL di origine locale restituita 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	Utilizza quando
never	Un file locale memorizzato è sufficiente fino a quando non lo rimuovi esplicitamente.
ttl	Desideri una semplice finestra di freschezza.
always	Vuoi che il plugin controlli l'asset remoto ogni volta.
etag	La tua CDN restituisce intestazioni ETag stabili.
last-modified	La tua CDN restituisce intestazioni Last-Modified affidabili.

Archiviazione E Riservatezza

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

Se desideri una soluzione più sicura, considera l'uso di un plugin diverso da Capgo, come ad esempio Appflow o Capawesome, che offrono funzionalità di sicurezza avanzate e un controllo più granulare sulle cache. In alternativa, puoi utilizzare un servizio di archiviazione esterno, come Cloudflare o GitHub, che offrono funzionalità di sicurezza avanzate e un controllo più granulare sulle cache. In ogni caso, assicurati di utilizzare un protocollo di crittografia sicuro per proteggere i tuoi dati sensibili. Se hai altre domande o desideri ulteriori informazioni, non esitare a contattarci. La cache di Capgo è persistente, ma non è un confine di sicurezza da solo. Se devi mantenere gli asset sensibili inaccessibili su un dispositivo compromesso, assicurati di cifrarli prima di servirli.

Controllo Cache Avanzato

La maggior parte delle interfacce utente code dovrebbe utilizzare bind, src, o resolve. Utilizza questi aiuti quando hai bisogno di un gestione cache esplicita:

Metodo	Descrizione
get	Risolve una URL remota in metadati di file nativi.
list	Restituisce gli asset cached che ancora esistono sul disco.
getCacheSize	Restituisce il totale di byte cached.
remove	Elimina un asset cached per chiave o URL.
clear	Elimina ogni asset cached 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