Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda menggunakan perintah berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih suka Manual Setup, instal plugin dengan menjalankan:

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

Impor

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

Mulai cepat

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

await nativePlugin.cancel();

Masalah umum

• Sinkronisasi native: jalankan npx cap sync setelah upgrade plugin.
• Sumber kebenaran: percaya src/definitions.ts pada repo GitHub.

Konfigurasi CDN

Konfigurasikan base URL CDN sekali saat aplikasi dimulai. Path aset relatif akan diselesaikan terhadap URL ini.

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

Anda bisa melewati ini cdnUrl jika Anda menggunakan URL absolut pada bind, src, atau resolve.

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

Bind Image atau Video

bind adalah jalur tampilan yang paling transparan. Ini menandai elemen sebagai sedang memuat, mengambil atau merevalidasi aset secara native, lalu menetapkan URL sumber lokal saat file lokal siap.

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

Catatan

Elemen tidak akan pernah menerima URL CDN pada jalur sukses. Elemen akan menerima URL webview lokal setelah asset tersedia di persistent storage.

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>

Sumber Langsung Untuk State Framework

Gunakan src saat framework Anda sudah mengontrol state loading dan error. Promise akan resolve dengan string source lokal hanya setelah file lokal tersedia.

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

videoElement.src = src;

Gunakan resolve saat Anda juga membutuhkan metadata:

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

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

Aset Terproteksi

Kirimkan header ke native fetch. Ini berguna untuk signed CDN paths, media terautentikasi, atau token berdurasi singkat.

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

Header digunakan oleh plugin saat fetching atau revalidating file remote. Tag image atau video tetap hanya menerima local source URL yang dikembalikan oleh plugin.

Revalidation

Atur strategi default dengan configure atau timpa untuk satu aset.

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

Strategi yang tersedia:

Strategi	Gunakan saat
never	File lokal yang di-cache sudah cukup sampai Anda menghapusnya secara eksplisit.
ttl	You want a simple freshness window.
always	Anda ingin plugin mengecek aset remote setiap saat.
etag	CDN Anda mengembalikan header ETag yang stabil.
last-modified	CDN Anda mengembalikan header Last-Modified yang andal.

Penyimpanan dan Privasi

• iOS menyimpan file di Application Support dan mengecualikan root cache dari backup iCloud.
• Android menyimpan file di direktori internal files aplikasi.
• Web menggunakan Cache API browser dan metadata localStorage sebagai fallback pengembangan.
• File yang di-cache tersembunyi di dalam sandbox aplikasi, tidak disimpan ke media publik pengguna.
• File cache dihapus saat uninstall, hapus data aplikasi, atau plugin clear() atau remove().

Cache bersifat persisten, namun bukan merupakan batasan keamanan tersendiri. Enkripsi aset yang sangat sensitif sebelum disajikan jika harus tetap tidak terbaca pada perangkat yang terkompromi.

Kontrol Cache Lanjutan

Sebagian besar UI code sebaiknya menggunakan bind, src, atau resolve. Gunakan helper ini saat Anda butuh manajemen cache eksplisit:

Metode	Deskripsi
get	Resolve URL remote menjadi metadata file native.
list	Kembalikan asset yang tersimpan di cache dan masih ada di disk.
getCacheSize	Kembalikan total byte yang tersimpan di cache.
remove	Hapus satu asset di cache berdasarkan key atau URL.
clear	Hapus semua asset yang dikelola oleh plugin di cache.

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

Referensi Lengkap

• GitHub: https://github.com/Cap-go/capacitor-asset-cache/
• Package: @capgo/capacitor-asset-cache