Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command 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();

Kesalahan umum

• Sinkronisasi Native: jalankan npx cap sync setelah upgrade plugin.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Konfigurasi CDN

Konfigurasikan URL dasar CDN sekali saat aplikasi Anda dimulai. Path aset relatif akan di-resolve terhadap URL ini.

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

Anda dapat melewati cdnUrl jika Anda meneruskan URL absolut ke bind, src, atau resolve.

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

Hubungkan gambar atau video

bind adalah jalur tampilan paling transparan. Menandai elemen sebagai sedang dimuat, mengambil atau memvalidasi ulang 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 tersebut tidak pernah menerima URL CDN pada jalur yang berhasil. Elemen ini menerima URL webview lokal setelah aset tersedia di penyimpanan persisten.

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 ketika framework Anda sudah mengontrol loading dan state error. Promise akan resolve dengan string sumber lokal hanya setelah file lokal ada.

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

videoElement.src = src;

Gunakan resolve ketika Anda juga membutuhkan metadata:

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

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

Aset Terproteksi

Lewati headers ke native fetch. Ini berguna untuk jalur CDN yang ditandatangani, media terautentikasi, atau token berumur pendek.

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

Headers digunakan oleh plugin saat mengambil atau memvalidasi ulang file remote. Tag gambar atau video tetap hanya menerima URL sumber lokal yang dikembalikan plugin.

Validasi Ulang

Atur strategi default dengan configure atau timpa pengaturan itu untuk satu aset.

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

Strategi yang tersedia:

Strategi	Gunakan saat
never	File lokal yang sudah di-cache cukup sampai Anda menghapusnya secara eksplisit.
ttl	Anda ingin periode kesegaran yang sederhana.
always	Anda ingin plugin memeriksa aset remote setiap kali.
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 bawah Application Support dan mengecualikan root cache dari backup iCloud.
• Android menyimpan file di bawah direktori file internal aplikasi.
• Web menggunakan Cache API browser dan metadata localStorage sebagai fallback pengembangan.
• File yang di-cache disembunyikan di dalam sandbox aplikasi, tidak disimpan ke media pengguna publik.
• File yang di-cache dihapus saat uninstall, pembersihan data aplikasi, atau plugin clear() atau remove().

Cache bersifat persisten, tetapi bukan batas keamanan dengan sendirinya. Enkripsi aset yang sangat sensitif sebelum disajikan jika harus tetap tidak terbaca pada perangkat yang dikompromikan.

Kontrol cache lanjutan

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

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

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/
• Paket: @capgo/capacitor-asset-cache