본문 바로가기

시작하기

GitHub

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.

수동 설정을 선호하는 경우, 다음을 실행하여 플러그인을 설치하세요:

터미널 창
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 구성” 섹션

앱이 시작될 때 CDN 기본 URL을 한 번 구성하세요. 상대 자산 경로는 이 URL을 기준으로 해석됩니다.

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

다음에 절대 URL을 전달하는 경우 cdnUrl 를 건너뛸 수 있습니다 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;
}
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" />;
}
<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);

네이티브 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플러그인이 매번 원격 에셋을 확인하도록 하려면.
etagCDN이 안정적인 ETag 헤더를 반환할 때.
last-modifiedCDN이 신뢰할 수 있는 Last-Modified 헤더를 반환합니다.

스토리지 및 개인정보 보호

“Storage And Privacy” 섹션
  • 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' },
});

전체 레퍼런스

“Full Reference” 섹션