시작하기

설치

AI 지원 설정으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그다음 아래 prompt를 사용하세요:

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가 로컬 소스 문자열과 함께 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);

보호된 에셋

Native fetch에 헤더를 전달합니다. 서명된 CDN 경로, 인증된 미디어 또는 유효 기간이 짧은 토큰을 사용할 때 유용합니다.

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

헤더는 플러그인이 원격 파일을 fetch하거나 revalidate하는 동안 사용됩니다. 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 메타데이터를 개발용 fallback으로 사용합니다.
• 캐시된 파일은 앱 샌드박스 내부에 숨겨지며, 사용자의 공개 미디어 폴더에 저장되지 않습니다.
• 앱 삭제, 데이터 삭제 또는 플러그인 제거 시 캐시된 파일이 삭제됩니다. clear() 또는 remove().

캐시는 지속되지만, 그 자체로 보안 경계가 되지는 않습니다. 기기가 해킹될 경우를 대비해 민감한 에셋은 제공 전 반드시 암호화하세요.

고급 캐시 제어

대부분의 UI code은 다음을 사용해야 합니다 bind, src, 또는 resolve명시적인 캐시 관리가 필요한 경우 다음 헬퍼를 사용하세요:

메서드	설명
get	원격 URL을 네이티브 파일 메타데이터로 변환합니다.
list	디스크에 남아 있는 캐시된 에셋을 반환합니다.
getCacheSize	전체 캐시 용량(byte)을 반환합니다.
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