Getting Started

インストール

CapgoのAI-Assisted Setupを使用してプラグインをインストールできます。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.

Manual Setupを使用する場合は、以下のコマンドを実行してプラグインをインストールしてください。

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

インポート

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

CDNを設定する

アプリケーションが起動したときに、CDNの基本URLを一度設定します。相対的なアセットのパスは、このURLに対して解決されます。

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

スキップすることができます cdnUrl if bind, src絶対URLを渡す場合、または 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は成功パスで受信されません。ローカルウェブビュー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 フレームワークが既にロードとエラーの状態を制御している場合に使用してください。ローカルファイルが存在するまでにのみ、ローカルソースの文字列がresolveされます。

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}`,
  },
});

プラグインはリモートファイルを取得したり、再検証したりする際にヘッダーを使用します。画像または動画タグは、プラグインによって返されたローカルソースURLのみを受け取ります。

再検証

デフォルトの戦略を設定する configure または、1つのアセットにのみオーバーライドします。

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

利用可能な戦略:

戦略	使用する場合
never	キャッシュされたローカルファイルは、明示的に削除するまで十分です。
ttl	簡単な新鮮さのウィンドウが必要です。
always	プラグインがリモートアセットを毎回チェックしたい
etag	CDNが安定したETagヘッダーを返します
last-modified	CDNが信頼できるLast-Modifiedヘッダーを返します

データ保存とプライバシー

• iOSはファイルをApplication Supportに格納し、キャッシュルートをiCloudバックアップから除外します
• Androidはアプリ内ファイルディレクトリにファイルを格納します
• ブラウザのキャッシュ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