Premiers pas

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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 une configuration manuelle, installez le plugin en exécutant :

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

Importer

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

Démarrage rapide

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

await nativePlugin.cancel();

Erreurs courantes

• Sync native : exécutez npx cap sync après la mise à jour des plugins.
• Source de vérité: trust src/definitions.ts dans le repo GitHub.

Configurer un CDN

Configurez une URL de base CDN une seule fois au démarrage de votre application. Les chemins d'assets relatifs seront résolus par rapport à cette URL.

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

Vous pouvez ignorer cette étape cdnUrl si vous passez des URLs absolues à bind, src, ou resolve.

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

Lier une image ou une vidéo

bind est le chemin d'affichage le plus transparent. Il marque l'élément comme étant en cours de chargement, récupère ou revalide l'asset nativement, puis assigne l'URL de la source locale une fois le fichier 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

L'élément ne reçoit jamais l'URL du CDN lors du parcours réussi. Il reçoit l'URL locale de la webview une fois que l'asset est présent 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 directe pour l'état du framework

Utilisez src lorsque votre framework gère déjà le chargement et les états d'erreur. La promesse se résout avec une chaîne de source locale uniquement une fois que le fichier local existe.

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

videoElement.src = src;

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

Assets protégés

Passez des headers au fetch natif. C'est utile pour les chemins CDN signés, les médias authentifiés ou les tokens à courte durée de vie.

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

Les headers sont utilisés par le plugin lors de la récupération ou de la revalidation du fichier distant. La balise image ou vidéo ne reçoit toujours que l'URL de source locale renvoyée par le plugin.

Revalidation

Définissez une stratégie par défaut avec configure ou remplacez-la pour un asset.

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

Stratégies disponibles :

Stratégie	À utiliser quand
never	Un fichier local en cache suffit jusqu'à sa suppression explicite.
ttl	Vous souhaitez une simple fenêtre de fraîcheur.
always	Vous voulez que le plugin vérifie l'asset distant à chaque fois.
etag	Votre CDN renvoie des headers ETag stables.
last-modified	Votre CDN renvoie des headers Last-Modified fiables.

Stockage et confidentialité

• iOS stocke les fichiers sous Application Support et exclut la racine du cache de la sauvegarde iCloud.
• Android stocke les fichiers dans le répertoire interne de l'application.
• Le Web utilise le cache du navigateur API et les métadonnées localStorage comme solution de repli pour le 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().

Le cache est persistant, mais il ne constitue pas en soi une barrière de sécurité. Chiffrez les assets hautement sensibles avant de les servir s'ils doivent rester illisibles sur un appareil compromis.

Contrôle de cache avancé

La plupart des code d'interface utilisateur devraient utiliser bind, src, ou resolve. Utilisez ces helpers pour une gestion explicite du cache :

Méthode	Description
get	Résout une URL distante en métadonnées de fichier natif.
list	Retourne les assets mis en cache toujours présents sur le disque.
getCacheSize	Retourne le nombre total d'octets en cache.
remove	Supprime un asset en cache par clé ou par URL.
clear	Supprime tous les assets 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-asset-cache/
• Package : @capgo/capacitor-asset-cache