Getting Started

Instalar

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

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

Luego utilice la siguiente solicitud:

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 una URL base de CDN una vez que se inicie tu aplicación. Las rutas de activos relativas 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, srco resolve.

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

Asignar 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 CDN en el camino exitoso. Recibe la URL del navegador 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 el estado de carga y errores. La promesa se resuelve con una cadena de fuente local solo después de que el archivo local existe.

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

videoElement.src = src;

Usar resolve cuando también necesites metadatos:

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

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

Recursos protegidos

Pasa encabezados al fetch nativo. 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 complemento mientras se realiza la solicitud o se revalida el archivo remoto. La etiqueta de imagen o video sigue recibiendo solo la URL de origen local devuelta por el complemento.

Revalidación

Establecer una estrategia por defecto con configure o reemplazarlo 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	Tu CDN devuelve encabezados de 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.
• Archivos caché están ocultos dentro del sandbox de la aplicación, no se guardan en medios de usuario públicos.
• Archivos caché se eliminan al desinstalar, limpiar datos de la aplicación o plugin. clear() o remove().

The cache is persistent, but it is not a security boundary by itself. Encrypt highly sensitive assets before serving them if they must remain unreadable on a compromised device.

Control de Caché Avanzado

Most UI code should use bind, src, or resolveUtiliza estos ayudantes cuando necesitas un manejo de caché explícito:

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