Mulai Menggunakan

Instal

Anda dapat menggunakan Setup Bantuan AI kami untuk menginstal plugin ini. Tambahkan Capgo kemampuan ke alat 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 Setup Manual, instal plugin dengan menjalankan:

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

Import

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

Konfigurasi CDN

Konfigurasi URL CDN dasar sekali ketika aplikasi Anda dimulai. Jalur aset relatif akan diresolusi terhadap URL ini.

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

Anda bisa melompat cdnUrl jika Anda melewati URL absolut ke bind, srcatau resolve.

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

Tautan Gambar atau Video

bind Jalur tampilan yang paling transparan. Ini menandai elemen sebagai sedang dimuat, mengambil atau memvalidasi kembali asset secara native, kemudian mengasignkan URL sumber lokal ketika 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 di jalur sukses. Ia menerima URL webview lokal setelah aset ada 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 Negara Framework

Pakai src ketika framework Anda sudah mengontrol loading dan error state. Promesnya akan menyelesaikan dengan string sumber lokal hanya setelah file lokal ada.

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

videoElement.src = src;

Pilih resolve Gunakan ketika Anda juga memerlukan metadata:

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

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

Aset Dilindungi

Kirimkan header ke fetch native. Ini berguna untuk jalur CDN yang ditandatangani, media yang terautentikasi, atau token yang hidup 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 mengambil atau memvalidasi ulang file remote. Tag gambar atau video masih menerima hanya URL sumber lokal yang dikembalikan oleh plugin.

Memvalidasi Ulang

Setel strategi default dengan configure atau menggantinya untuk satu aset.

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

Strategi yang tersedia:

Strategi	Pakai ketika
never	Sebuah file lokal yang ditambahkan sampai Anda menghapusnya secara eksplisit.
ttl	Anda ingin jendela kelembaban yang sederhana.
always	Anda ingin plugin memeriksa aset remote setiap kali.
etag	CDN Anda mengembalikan ETag stabil.
last-modified	CDN Anda mengembalikan Last-Modified yang dapat diandalkan.

Penyimpanan dan Privasi

• Pengguna iOS menyimpan file di bawah Application Support dan mengabaikan root cache dari backup iCloud.
• Pengguna Android menyimpan file di bawah direktori file aplikasi internal.
• Web menggunakan Cache browser API dan metadata localStorage sebagai fallback pengembangan.
• File-file yang disimpan di cache disembunyikan di dalam sandbox aplikasi, bukan disimpan ke media pengguna publik.
• File yang dikasih akan dihapus ketika aplikasi diuninstall, data aplikasi dihapus, atau plugin clear() atau remove().

The cache is persistent, but it is not a security boundary by itself. Encrypt highly sensitive assets before serving them if they must remain unreadable on a compromised device.

Pengendalian Cache Lanjutan

Most UI code should use bind, src, or resolve, atau dapat menggunakan kunci ini ketika Anda memerlukan pengelolaan cache eksplisit:

Metode	Deskripsi
get	Mengubah URL remote menjadi metadata file asli.
list	Mengembalikan aset yang disimpan di disk yang masih ada.
getCacheSize	Mengembalikan total byte aset yang disimpan.
remove	Hapus satu aset cache dengan kunci atau URL.
clear	Menghapus semua aset yang disimpan yang dikelola oleh plugin.

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