Mulai

Ready untuk dipasang

Anda dapat menggunakan Setup Bantuan AI kami untuk menginstal plugin. 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

Impor

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 dapat melompat cdnUrl jika Anda melewatkan URL absolut ke bind, src, atau resolve.

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

Bindkan Gambar Atau Video

bind adalah jalur tampilan yang paling transparan. Ini menandai elemen sebagai loading, mengambil atau memvalidasi kembali asset secara native, kemudian mengasign 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 ini 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

Gunakan src ketika kerangka Anda sudah mengontrol muatan dan keadaan kesalahan. Promesinya akan menyelesaikan 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 Terlindungi

Lampirkan kepala ke akses 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}`,
  },
});

Kepala digunakan oleh plugin saat mengakses atau memvalidasi ulang file remote. Tag gambar atau video masih menerima hanya URL sumber lokal yang dikembalikan oleh plugin.

Revalidasi

Tetapkan strategi default dengan configure atau ubahnya untuk satu asset.

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

Strategi yang tersedia:

Strategi	Gunakan ketika
never	File lokal yang dicache cukup sampai Anda secara eksplisit menghapusnya.
ttl	Anda ingin jendela kebaruan yang sederhana.
always	Anda ingin plugin memeriksa asset remote setiap kali.
etag	CDN Anda mengembalikan header ETag yang stabil.
last-modified	CDN Anda mengembalikan header Last-Modified yang dapat diandalkan.

Penyimpanan Dan Privasi

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

Cache yang persisten, tetapi tidak merupakan batasan keamanan sendiri. Enkripsi aset yang sangat sensitif sebelum menyajikannya jika mereka harus tetap tidak dapat dibaca pada perangkat yang telah disusup.

Pengendalian Cache Lanjutan

Most UI code seharusnya menggunakan bind, src, atau resolve. Gunakan bantuan ini ketika Anda membutuhkan manajemen cache yang eksplisit:

Metode	Deskripsi
get	Resolusi URL remote ke metadata file native.
list	Kembalikan aset yang dicache yang masih ada di disk.
getCacheSize	Kembalikan total byte yang dicache.
remove	Hapus satu aset yang dicache dengan kunci atau URL.
clear	Hapus setiap aset yang dicache 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-asset-cache/
• Paket: @capgo/capacitor-asset-cache