Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa 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:

bun add @capgo/capacitor-asset-cache
npx cap sync

Importar

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

Inicio rápido

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

await nativePlugin.cancel();

Errores comunes

• Sync nativo: ejecutar npx cap sync tras actualizar los plugins.
• Fuente de verdad: confiar src/definitions.ts en el repo de GitHub.

Configura un CDN

Configura una URL base de CDN al iniciar tu app. Las rutas de assets relativos se resolverán usando esta URL.

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

Puedes omitirlo cdnUrl si pasas URLs absolutas a bind, src, o resolve.

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

Vincula una imagen o video

bind es la ruta de visualización más transparente. Marca el elemento como cargando, obtiene o revalida el asset de forma nativa y asigna la URL local cuando el archivo 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 del CDN en el flujo exitoso. Recibe la URL local del webview una vez que el asset 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 framework

Usa src cuando tu framework ya controla el estado de carga y error. La promesa se resuelve con un string de la fuente local solo cuando el archivo local existe.

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);

Assets protegidos

Pasa headers al fetch nativo. Esto es útil para rutas de CDN firmadas, contenido autenticado o tokens de corta duración.

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

El plugin usa los headers al hacer el fetch o revalidar el archivo remoto. La etiqueta de imagen o video solo recibe la URL de la fuente local devuelta por el plugin.

Revalidación

Define una estrategia por defecto con configure o sobrescríbela para un asset específico.

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

Estrategias disponibles:

Estrategia	Usar cuando
never	Un archivo local en caché es suficiente hasta que lo elimines explícitamente.
ttl	Buscas un periodo de frescura simple.
always	Quieres que el plugin verifique el asset remoto siempre.
etag	Tu CDN devuelve headers ETag estables.
last-modified	Tu CDN devuelve headers Last-Modified fiables.

Almacenamiento y privacidad

• iOS guarda los archivos en Application Support y excluye la raíz del cache del backup de iCloud.
• Android almacena los archivos en el directorio interno de la aplicación.
• La web utiliza el Cache API del navegador y metadatos de localStorage como fallback de desarrollo.
• Los archivos en cache están ocultos en el sandbox de la app, no se guardan en la galería pública.
• Los archivos en cache se eliminan al desinstalar, borrar datos de la app o el plugin clear() o remove().

El cache es persistente, pero no es un límite de seguridad por sí mismo. Encripta assets muy sensibles antes de servirlos si deben ser ilegibles en un dispositivo comprometido.

Control de cache avanzado

La mayoría de los code de la UI deberían usar bind, src, o resolve. Usa estos helpers cuando necesites gestión de caché explícita:

Método	Descripción
get	Resuelve una URL remota en metadatos de archivo nativos.
list	Devuelve los assets en caché que aún existen en disco.
getCacheSize	Devuelve el total de bytes en caché.
remove	Elimina un asset en caché por clave o URL.
clear	Elimina todos los assets en 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-asset-cache/
• Paquete: @capgo/capacitor-asset-cache