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: ejecuta npx cap sync tras actualizar los plugins.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Configurar un CDN

Configura una URL base de CDN una vez al iniciar tu app. Las rutas de recursos relativas se resolverán contra esta URL.

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

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

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

Vincular una imagen o video

bind es la ruta de visualización más transparente. Marca el elemento como en carga, obtiene o revalida el recurso de forma nativa y 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 del CDN en la ruta exitosa. Recibe la URL local del webview una vez que el asset ya 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 la carga y el estado de error. La promesa se resuelve con una cadena de origen local solo cuando el archivo local ya existe.

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

videoElement.src = src;

Usa resolve cuando también necesites 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. Ú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}`,
  },
});

Los headers se usan por el plugin al obtener o revalidar el archivo remoto. La etiqueta de imagen o video sigue recibiendo solo la URL de origen local devuelta por el plugin.

Revalidación

Establece una estrategia predeterminada con configure o sobrescríbela para un solo asset.

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

Estrategias disponibles:

Estrategia	Cuándo usar
never	Un archivo local en caché es suficiente hasta que lo elimines explícitamente.
ttl	Quieres una ventana de frescura simple.
always	Quieres que el plugin verifique el recurso remoto cada vez.
etag	Tu CDN devuelve encabezados ETag estables.
last-modified	Tu CDN devuelve headers Last-Modified fiables.

Almacenamiento y privacidad

• iOS almacena 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 app.
• Web usa la Cache API del navegador y los metadatos de localStorage como fallback de desarrollo.
• Los archivos en caché se guardan dentro del sandbox de la app, no en la galería pública del usuario.
• Los archivos en caché se eliminan al desinstalar, borrar los datos de la app o quitar el plugin. clear() o remove().

La caché es persistente, pero no es un límite de seguridad por sí misma. Cifra los assets muy sensibles antes de servirlos si deben permanecer ilegibles en un dispositivo comprometido.

Control avanzado de caché

La mayoría de las interfaces de usuario code deben usar bind, src, o resolve. Usa estos helpers cuando necesites gestionar la caché de forma explícita:

Método	Descripción
get	Resuelve una URL remota en metadatos de archivo nativo.
list	Devuelve los assets en caché que aún existen en disco.
getCacheSize	Devuelve los bytes totales 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