はじめに

インストール

AIアシストセットアップを使ってプラグインをインストールできます。以下のコマンドで、お使いのAIツールに Capgo スキルを追加してください：

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

次に、以下のプロンプトを使用します：

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

手動でのセットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールしてください：

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

インポート

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

クイックスタート

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

await nativePlugin.cancel();

よくある落とし穴

• ネイティブ同期: 実行 npx cap sync プラグインのアップグレード後。
• 信頼できる情報源: 信頼する src/definitions.ts GitHub リポジトリ内に

CDNの設定

アプリ起動時にCDNのベースURLを一度設定します。相対的なアセットパスはこのURLに基づいて解決されます。

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

スキップ可能です cdnUrl に絶対URLを渡す場合は bind, src、または resolve.

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

画像や動画のバインド

bind は、最も透過的な表示パスです。要素をロード中としてマークし、ネイティブにアセットの取得または再検証を行い、ローカルファイルの準備ができ次第、ローカルのソースURLを割り当てます。

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

注意

正常なフローでは、要素にCDN URLが渡されることはありません。アセットが永続ストレージに保存された後は、ローカルのwebview URLが渡されます。

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>

フレームワークの状態への直接的なソース

使用するのは src フレームワーク側ですでにロード中やエラーの状態を管理している場合に使用します。ローカルファイルが存在する場合にのみ、Promiseがローカルのソース文字列を返して解決されます。

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

videoElement.src = src;

使用するのは resolve メタデータも必要な場合：

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

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

保護されたアセット

ネイティブのfetchにヘッダーを渡します。署名付きCDNパス、認証が必要なメディア、または有効期限の短いトークンの使用に便利です。

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

ヘッダーは、プラグインがリモートファイルをフェッチまたは再検証する際に使用されます。imageタグやvideoタグには、プラグインから返されたローカルのソースURLのみが渡されます。

再検証

次の方法でデフォルトの戦略を設定、 configure または特定の資産に対して上書きできます。

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

利用可能な戦略:

戦略	以下の条件で使用します:
never	明示的に削除するまで、キャッシュされたローカルファイルで十分な場合。
ttl	単純な鮮度管理（freshness window）を行いたい場合。
always	毎回プラグインにリモート資産を確認させたい場合。
etag	CDNが安定したETagヘッダーを返す場合。
last-modified	CDNが信頼性の高いLast-Modifiedヘッダーを返します。

ストレージとプライバシー

• iOSではファイルはApplication Supportに保存され、キャッシュルートはiCloudバックアップから除外されます。
• Androidではファイルはアプリの内部ファイルディレクトリに保存されます。
• Webでは、開発時のフォールバックとしてブラウザのCache APIとlocalStorageのメタデータを使用します。
• キャッシュされたファイルはアプリのサンドボックス内に隠蔽されており、ユーザーの公開メディアには保存されません。
• キャッシュファイルは、アプリのアンインストール、アプリデータの消去、またはプラグインの clear() または remove().

キャッシュは永続的ですが、それ自体がセキュリティ境界になるわけではありません。デバイスが侵害された際に読み取られないようにする必要がある極めて機密性の高いアセットは、配信前に暗号化してください。

高度なキャッシュ制御

ほとんどのUI code で推奨される方法 bind, src、または resolve明示的なキャッシュ管理が必要な場合は、以下のヘルパーを使用してください：

メソッド	説明
get	リモートURLをネイティブのファイルメタデータに変換します。
list	ディスク上に存在するキャッシュ済みアセットを返します。
getCacheSize	キャッシュされている合計バイト数を返します。
remove	キーまたはURLを指定して、特定のキャッシュ済みアセットを削除します。
clear	プラグインが管理するすべてのキャッシュ済みアセットを削除します。

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

リファレンス全文

• GitHub: https://github.com/Cap-go/capacitor-asset-cache/
• パッケージ: @capgo/capacitor-asset-cache