Getting Started

Installer

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA en utilisant la commande suivante :

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

Utilisez ensuite la prompt suivante :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-asset-cache` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin en exécutant :

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

Importer

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

Configurer un CDN

Configurez une URL de base CDN une fois que votre application démarre. Les chemins d'actifs relatifs seront résolus par rapport à cette URL.

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

Vous pouvez passer à côté cdnUrl si vous passez des URLs absolues à bind, srcou resolve.

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

lier une image ou un vidéo

bind est le chemin de visualisation le plus transparent. Il marque l'élément comme chargement, récupère ou révalide l'asset nativement, puis affecte l'URL de source locale lorsque le fichier local est prêt.

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

Note

Le composant ne reçoit jamais l'URL CDN dans le chemin réussi. Il reçoit l'URL de la vue web locale après que l'asset existe dans le stockage persistant.

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>

Source direct pour l'état du framework

Utilisez src Lorsque votre framework contrôle déjà la charge et l'état d'erreur. La promesse se résout par une chaîne de source locale uniquement après l'existence du fichier local.

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

videoElement.src = src;

Utiliser resolve Lorsque vous avez également besoin de métadonnées :

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

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

Actifs protégés

Transmettre les en-têtes au fetch natif. Cela est utile pour les chemins CDN signés, les médias authentifiés ou les jetons à durée de vie courte.

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

Les en-têtes sont utilisés par le plugin lors de la récupération ou de la révalidation du fichier distant. La balise d'image ou de vidéo reçoit uniquement l'URL de source locale renvoyée par le plugin.

Révalidation

Définir une stratégie par défaut avec configure ou le remplacer pour un seul élément.

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

Stratégies disponibles :

Stratégie	Utilisez lorsque
never	Un fichier local en cache est suffisant jusqu'à ce que vous le supprimiez explicitement.
ttl	Vous souhaitez une fenêtre de fraîcheur simple.
always	Vous souhaitez que le plugin vérifie l'élément distant chaque fois.
etag	Votre CDN retourne des en-têtes ETag stables.
last-modified	Votre CDN retourne des en-têtes Last-Modified fiables.

Stockage et Confidentialité

• iOS stocke les fichiers sous Application Support et exclut la racine de la cache des sauvegardes iCloud.
• Android stocke les fichiers sous le répertoire de fichiers internes de l'application.
• Le navigateur Web utilise le cache API et les métadonnées de localStorage comme fallback de développement.
• Cached files are hidden inside the app sandbox, not saved to public user media.
• Cached files are removed on uninstall, app data clear, or plugin clear() ou 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.

Contrôle de Cache Avancé

Most UI code should use bind, src, or resolveUtilisez ces helpers lorsque vous avez besoin d'une gestion de cache explicite :

Méthode	Description
get	Résoudre une URL distante en métadonnées de fichiers natifs.
list	Renvoyer des actifs en cache qui existent toujours sur le disque.
getCacheSize	Renvoyer le total de bytes en cache.
remove	Supprimer un actif en cache par clé ou URL.
clear	Supprimer tous les actifs en cache gérés par le plugin.

const asset = await AssetCache.get({
  url: 'https://cdn.example.com/assets/videos/intro.mp4',
  key: 'videos/intro.mp4',
  revalidate: { strategy: 'last-modified' },
});

Référence complète

• GitHub: https://github.com/Cap-go/capacitor-cache-d'actifs/
• Package : @capgo/capacitor-asset-cache