Prise en main

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 la 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écuter npx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Configurer un CDN

Configurez une URL de base de CDN une fois, au démarrage de votre app. 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 URL 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 en cours de chargement, récupère ou revalide l'asset nativement, puis attribue l'URL source locale une fois le fichier local 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;
}

Remarque

L'élément ne reçoit jamais l'URL du CDN dans le cas de succès. Il reçoit l'URL locale de la webview une fois l'asset 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 de l'état du framework

Utiliser src lorsque votre framework gère déjà le chargement et l’état d’erreur. La promesse ne se résout avec une chaîne de source locale qu’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);

Assets protégés

Transmettez les en-têtes au fetch natif. C’est utile pour les chemins CDN signés, les médias authentifiés ou les tokens à 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 lorsqu’il récupère ou revalide le fichier distant. La balise image ou vidéo ne reçoit toujours que l’URL source locale renvoyée par le plugin.

Révalidation

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

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 en-têtes Last-Modified fiables.

Stockage et confidentialité

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

Le cache est persistant, mais il ne constitue pas à lui seul une frontière de sécurité. Chiffrez les ressources très sensibles avant de les servir si elles doivent rester illisibles sur un appareil compromis.

Contrôl’avancé du cache

La plupart des code d'interface 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	Renvoie les assets en cache qui existent encore sur le disque.
getCacheSize	Renvoie le nombre total d'octets mis en cache.
remove	Supprime un asset mis en cache par sa clé ou son 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