Iniciación

Instalar

Puedes utilizar nuestra configuración asistida por inteligencia artificial para instalar el complemento. 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 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 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 esto cdnUrl si pasas URLs absolutas a bind, srco resolve.

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

Asociar 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 del navegador 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 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 sigue recibiendo 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.
• El navegador utiliza la caché 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().

¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | ¿Qué sucede si utilizamos otras alternativas de actualización en vivo de Capacitor? | Los archivos caché son persistentes, pero no son una barrera de seguridad por sí mismos. Si los activos deben permanecer inaccesibles en un dispositivo comprometido, cifralos antes de servirlos.

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 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-activos/
• Paquete: @capgo/capacitor-asset-cache