Pembelajaran Dasar

Instal

Kamu bisa menggunakan Pengaturan Setup Bantuan AI kami untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI kamu 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 dasar CDN 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 melompati cdnUrl jika Anda memasukkan URL absolut ke bind, src, atau resolve.

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

Tautan Gambar atau Video

bind adalah jalur tampilan yang paling transparan. Ini menandai elemen sebagai sedang dimuat, mengambil atau memvalidasi kembali asset secara native, kemudian mengalokasikan 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;
}

Peringatan

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 Kerangka

Gunakan src ketika kerangka Anda sudah mengontrol muatan dan keadaan kesalahan. Promesnya 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 memerlukan metadata:

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

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

Aset Terlindungi

Lampirkan 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

Tetapkan strategi default dengan configure atau override untuk satu aset.

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

Strategi yang tersedia:

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

Cache tetap ada, tetapi itu bukan batasan keamanan sendiri. Enkripsi asset yang sensitif sebelum menyajikannya jika mereka harus tetap tidak dapat dibaca pada perangkat yang telah dibobol.

Pengendalian Cache Lanjutan

Sebagian besar UI code harus menggunakan bind, src, resolveatau

Gunakan helper ini ketika Anda membutuhkan pengelolaan cache eksplisit:	Deskripsi
get	Resolusi URL remote menjadi metadata file native.
list	Mengembalikan aset yang masih ada di disk.
getCacheSize	Mengembalikan total byte aset yang dicache.
remove	Menghapus satu aset yang dicache berdasarkan kunci atau URL.
clear	Menghapus 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-aset-cache/
• Paket: @capgo/capacitor-asset-cache