Inicio

Instalar

Puedes utilizar nuestra configuración asistida por inteligencia artificial para instalar el plugin. Agrega las Capgo habilidades a tu herramienta de inteligencia artificial utilizando el siguiente comando:

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

Luego utiliza 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 prefieres la configuración manual, instala el plugin ejecutando:

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

Importar

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

Configura una CDN

Configura la URL base de una 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 cdnUrl si pasas URLs absolutas a bind, src, o resolve.

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

Asocia 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, 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 el 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

Usa src cuando tu 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;

Usa 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

Pasa encabezados al fetch nativo. 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 realiza la solicitud o se revalida el archivo remoto. La etiqueta de imagen o video sigue recibiendo solo la URL de fuente 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 de ETag estable.
last-modified	Su CDN devuelve encabezados Last-Modified fiables.

Almacenamiento y Privacidad

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

El caché es persistente, pero no es una barrera de seguridad por sí solo. Cifre activos altamente sensibles antes de servirlos si deben permanecer inaccesibles en un dispositivo comprometido.

Control Avanzado de Caché

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

Método	Descripción
get	Resuelve una URL remota en metadatos de archivo nativo.
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-recursos/
• Paquete: @capgo/capacitor-asset-cache