Configuración inicial

Instalar

Puede utilizar nuestra configuración asistida por inteligencia artificial para instalar el complemento. Agregue las Capgo habilidades a su herramienta de inteligencia artificial utilizando el siguiente comando:

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

Luego utilice el siguiente prompt:

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

Si prefiere la configuración manual, instale el complemento ejecutando:

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

Importar

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

Configurar una CDN

Configura la URL base de la CDN una vez que se inicia tu aplicación. Los caminos de activos relativos se resolverán en función de esta URL.

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

Puedes saltarte esto cdnUrl si pasas URLs absolutas a bind, srco resolve.

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

Unir una imagen o video

bind es el camino de visualización más transparente. Marca el elemento como de carga, obtiene o revalida el activo nativamente, y luego asigna la URL de origen local cuando el archivo local esté listo.

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

El elemento nunca recibe la URL de CDN en el camino exitoso. Recibe la URL de la vista web local después de que el activo existe en almacenamiento 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>

Fuente Directa Para El Estado Del Marco

Usar src cuando su marco ya controla la carga y el estado de error. La promesa se resuelve con una cadena de fuente local solo después de que el archivo local exista.

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

videoElement.src = src;

Usar resolve cuando también necesitas metadatos:

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

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

Activos Protegidos

Enviar encabezados a la llamada nativa de fetch. Esto es útil para rutas de CDN firmadas, medios autenticados o tokens de vida corta.

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

Los encabezados se utilizan por el plugin mientras se está cargando o revalidando el archivo remoto. La etiqueta de imagen o video todavía recibe solo la URL de origen local devuelta por el plugin.

Revalidación

Establecer una estrategia por defecto con configure o sobrescribirla para un activo.

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

Estrategias disponibles:

Estrategia	Usar cuando
never	Un archivo local cacheado es suficiente hasta que lo elimines explícitamente.
ttl	Quieres una ventana de frescura simple.
always	Quieres que el plugin compruebe el activo remoto cada vez.
etag	Tu CDN devuelve encabezados ETag estables.
last-modified	Tu CDN devuelve encabezados Last-Modified fiables.

Almacenamiento y Privacidad

• iOS almacena archivos bajo Aplicación de Soporte y excluye la raíz de la caché de iCloud.
• Android almacena archivos bajo el directorio de archivos internos de la aplicación.
• Web utiliza el Cache API y localStorage como fallback de desarrollo.
• Los archivos caché están ocultos dentro del sandbox de la aplicación, no se guardan en medios de usuario públicos.
• Los archivos caché se eliminan al desinstalar, al borrar datos de la aplicación o al plugin clear() o remove().

La caché es persistente, pero no es un límite de seguridad por sí sola. Encrípala antes de servirla si los activos deben permanecer inaccesibles en un dispositivo comprometido.

Control de Caché Avanzado

La mayoría de las UI code deben utilizar bind, src, o resolve. Utilice estos ayudantes cuando necesite un control explícito de la caché:

Método	Descripción
get	Resuelve una URL remota en metadatos de archivo nativos.
list	Devuelve activos de caché que aún existen en disco.
getCacheSize	Devuelve bytes totales de caché.
remove	Elimina un activo de caché por clave o URL.
clear	Elimina todos los activos de caché gestionados por el plugin.

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

Referencia completa

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