Çevrimdışı özellikli sayfalarınızı İçerik Dizine Ekleme API'si ile dizine ekleme

Service Worker'ların tarayıcılara hangi sayfaların çevrimdışı çalıştığını bildirmesini sağlama

Jeff Posnick

İçerik Dizine Ekleme API'si nedir?

Progresif web uygulaması kullanmak, ağ bağlantınızın mevcut durumundan bağımsız olarak insanların önem verdiği bilgilere (resimler, videolar, makaleler ve daha fazlası) erişebilmek anlamına gelir. Service Worker, Cache Storage API ve IndexedDB gibi teknolojiler, kullanıcılar doğrudan PWA ile etkileşim kurduğunda veri depolayıp sunmak için yapı taşlarını sunar. Ancak yüksek kaliteli, çevrimdışına öncelik veren bir PWA oluşturmak işin sadece bir parçasıdır. Kişiler bir web uygulamasının içeriğinin çevrimdışıyken de kullanılabildiğini fark etmezse bu işlevi uygulamak için harcadığınız emeğin tam olarak yararına olmaz.

Bu bir keşif sorunudur. PWA'nız, kullanıcıların kullanılabilir içerikleri keşfedip görüntüleyebilmeleri için çevrimdışı kullanım özelliğine sahip içeriklerden haberdar olmalarını nasıl sağlayabilir? İçerik Dizine Ekleme API'si bu soruna çözüm sağlar. Bu çözümün geliştiriciye yönelik kısmı Service Worker'lara yönelik bir uzantıdır. Bu uzantı, geliştiricilerin çevrimdışı özellikli sayfaların URL'lerini ve meta verilerini tarayıcı tarafından yönetilen yerel bir dizine eklemelerine olanak tanır. Bu geliştirme, Chrome 84 ve sonraki sürümlerde kullanılabilir.

Dizin, PWA'nızın içeriğiyle ve yüklenen diğer PWA'ların içeriğiyle doldurulduktan sonra, tarayıcı tarafından aşağıda gösterildiği gibi gösterilir.

Ayrıca Chrome, bir kullanıcının çevrimdışı olduğunu algıladığında proaktif olarak içerik önerebilir.

İçerik Dizine Ekleme API'si, içeriği önbelleğe almanın alternatif bir yolu değildir. Bu, hizmet çalışanınız tarafından önbelleğe alınmış sayfalarla ilgili meta veri sağlamanın bir yoludur. Böylece tarayıcı, bu sayfaları kullanıcıların görüntülemek isteyebileceği durumlarda gösterebilir. İçerik Dizine Ekleme API'si, önbelleğe alınan sayfaların keşfedilebilirliğine yardımcı olur.

İşleyiş şeklini görün

İçerik Dizine Ekleme API'si hakkında fikir edinmenin en iyi yolu örnek bir uygulamayı denemektir.

1. Desteklenen bir tarayıcı ve platform kullandığınızdan emin olun. Şu anda bu özellik Android'de Chrome 84 veya sonraki sürümler ile sınırlıdır. Hangi Chrome sürümünü kullandığınızı öğrenmek için about://version adresine gidin.
2. https://contentindex.dev adresini ziyaret edin
3. Listedeki bir veya daha fazla öğenin yanındaki + düğmesini tıklayın.
4. (İsteğe bağlı) Cihazınızın kablosuz ve hücresel veri bağlantısını devre dışı bırakın veya tarayıcınızı çevrimdışı hale getirme simülasyonu yapmak için uçak modunu etkinleştirin.
5. Chrome'un menüsünden İndirilenler'i seçin ve Size Özel Makaleler sekmesine geçin.
6. Daha önce kaydettiğiniz içeriklere göz atın.

Örnek uygulamanın kaynağını GitHub'da görüntüleyebilirsiniz.

Başka bir örnek uygulama olan Scrapbook PWA, İçerik Dizine Ekleme API'sinin Web Paylaşımı Hedef API'si ile birlikte kullanımını göstermektedir. Kodda, İçerik Dizine Ekleme API'sini Cache Storage API kullanarak bir web uygulaması tarafından depolanan öğelerle senkronize tutmak için bir teknik gösterilmektedir.

API'yi kullanın

API'yi kullanmak için uygulamanızda bir hizmet çalışanı ve çevrimdışı gezinilebilen URL'ler olmalıdır. Web uygulamanızda şu anda bir hizmet çalışanı yoksa Workbox kitaplıkları daha kolay oluşturulabilir.

Ne tür URL'ler çevrimdışı özellikli olarak dizine eklenebilir?

API, HTML dokümanlarına karşılık gelen URL'lerin dizine eklenmesini destekler. Örneğin, önbelleğe alınan bir medya dosyasının URL'si doğrudan dizine eklenemez. Bunun yerine, medya görüntüleyen ve çevrimdışı çalışan bir sayfanın URL'sini sağlamanız gerekir.

Önerilen kalıp, alttaki medya URL'sini sorgu parametresi olarak kabul edebilecek ve daha sonra dosyanın içeriğini, muhtemelen sayfada ek kontroller veya içerikle birlikte görüntüleyebilecek bir "görüntüleyen" HTML sayfası oluşturmaktır.

Web uygulamaları, içerik dizinine yalnızca geçerli hizmet çalışanının kapsamı kapsamındaki URL'leri ekleyebilir. Diğer bir deyişle, bir web uygulaması tamamen farklı bir alana ait bir URL'yi içerik dizinine ekleyemez.

Genel bakış

İçerik Dizine Ekleme API'si üç işlemi destekler: meta veri ekleme, listeleme ve kaldırma. Bu yöntemler, ServiceWorkerRegistration arayüzüne eklenen yeni bir özelliği (index) temel alır.

İçeriği dizine eklemenin ilk adımı, mevcut ServiceWorkerRegistration için referans almaktır. navigator.serviceWorker.ready kullanmak en basit yoldur:

const registration = await navigator.serviceWorker.ready;

// Remember to feature-detect before using the API:
if ('index' in registration) {
  // Your Content Indexing API code goes here!
}

İçerik Dizine Ekleme API'sine bir web sayfası yerine bir hizmet çalışanının içinden çağrı yapıyorsanız doğrudan registration aracılığıyla ServiceWorkerRegistration öğesine başvurabilirsiniz. ServiceWorkerGlobalScope. kapsamında önceden tanımlanmış

Dizine ekleniyor

URL'leri ve ilişkili meta verilerini dizine eklemek için add() yöntemini kullanın. Öğelerin dizine ne zaman ekleneceğini seçmek size kalmıştır. "Çevrimdışı kaydet" düğmesini tıklamak gibi bir girişe yanıt olarak dizine ekleme yapmak isteyebilirsiniz. Alternatif olarak, önbelleğe alınan veriler periyodik arka plan senkronizasyonu gibi bir mekanizma aracılığıyla her güncellendiğinde öğeleri otomatik olarak ekleyebilirsiniz.

await registration.index.add({
  // Required; set to something unique within your web app.
  id: 'article-123',

  // Required; url needs to be an offline-capable HTML page.
  url: '/articles/123',

  // Required; used in user-visible lists of content.
  title: 'Article title',

  // Required; used in user-visible lists of content.
  description: 'Amazing article about things!',

  // Required; used in user-visible lists of content.
  icons: [{
    src: '/img/article-123.png',
    sizes: '64x64',
    type: 'image/png',
  }],

  // Optional; valid categories are currently:
  // 'homepage', 'article', 'video', 'audio', or '' (default).
  category: 'article',
});

Giriş eklemek yalnızca içerik dizinini etkiler; önbelleğe herhangi bir şey eklemez.

Uç durum: Simgeleriniz bir fetch işleyiciye dayanıyorsa window bağlamından add() çağrısı yapın

add() yöntemini çağırdığınızda Chrome, dizine eklenen içeriklerin listesini gösterirken kullanılacak simgenin bir kopyasının bulunduğundan emin olmak için her simgenin URL'sini ister.

• add() öğesini window bağlamından (yani web sayfanızdan) çağırırsanız bu istek, hizmet çalışanınızda bir fetch etkinliğini tetikler.

• Hizmet çalışanınızdan (belki başka bir etkinlik işleyicinin içinde) add() öğesini çağırırsanız istek, hizmet çalışanının fetch işleyicisini tetiklemez. Simgeler, hizmet çalışanı müdahalesi olmadan doğrudan getirilir. Simgeleriniz fetch işleyicinize dayanıyorsa bunu göz önünde bulundurun. Bunun nedeni, simgelerin ağda değil, yalnızca yerel önbellekte bulunması olabilir. Arama yapıyorlarsa add() öğesini yalnızca window bağlamından çağırdığınızdan emin olun.

Dizin içeriğini listeleme

getAll() yöntemi, dizine eklenmiş girişlerin ve bunların meta verilerinin yinelenebilir bir listesi için söz döndürür. Döndürülen girişler, add() ile kaydedilen tüm verileri içerir.

const entries = await registration.index.getAll();
for (const entry of entries) {
  // entry.id, entry.launchUrl, etc. are all exposed.
}

Öğeler dizinden kaldırılıyor

Bir öğeyi dizinden kaldırmak için delete() işlemini öğenin id numarasıyla birlikte kaldırın:

await registration.index.delete('article-123');

delete() çağrısı yalnızca dizini etkiler. Önbellekten hiçbir şeyi silmez.

Kullanıcı silme etkinliğini işleme

Tarayıcı dizine eklenen içeriği görüntülediğinde, Sil menü öğesi içeren kendi kullanıcı arayüzünü ekleyebilir. Böylece, kullanıcılara önceden dizine eklenmiş içeriği tamamladıklarını gösterme şansı verilir. Chrome 80'de silme arayüzü şu şekilde görünür:

Bir kullanıcı bu menü öğesini seçtiğinde, web uygulamanızın hizmet çalışanı bir contentdelete etkinliği alır. Bu etkinliğin işlenmesi isteğe bağlı olsa da, Service Worker'ınızın yerel olarak önbelleğe alınmış medya dosyaları gibi içeriği "temizleyebilmesi" için bir fırsat sağlar.

contentdelete işleyicinizin içinden registration.index.delete() kodunu çağırmanıza gerek yoktur; etkinlik tetiklendiyse ilgili dizin silme işlemi tarayıcı tarafından zaten gerçekleştirilmiştir.

self.addEventListener('contentdelete', (event) => {
  // event.id will correspond to the id value used
  // when the indexed content was added.
  // Use that value to determine what content, if any,
  // to delete from wherever your app stores it—usually
  // the Cache Storage API or perhaps IndexedDB.
});

API tasarımı hakkında geri bildirim

API ile ilgili garip veya beklendiği gibi çalışmayan bir şey var mı? Yoksa fikrinizi uygulamak için gereken eksik parçalar var mı?

İçerik Dizine Ekleme API'si açıklayıcı GitHub deposunda sorun bildirin veya mevcut bir sorunla ilgili düşüncelerinizi ekleyin.

Uygulamayla ilgili bir sorun mu var?

Chrome'un uygulamasında bir hata buldunuz mu?

https://new.crbug.com adresinden hata bildiriminde bulunun. Mümkün olduğunca fazla ayrıntı ekleyin, yeniden oluşturmaya ilişkin basit talimatları ekleyin ve Bileşenler'i Blink>ContentIndexing olarak ayarlayın.

API'yi kullanmayı mı planlıyorsunuz?

Web uygulamanızda İçerik Dizine Ekleme API'sini kullanmayı mı planlıyorsunuz? Herkese açık desteğiniz, Chrome'un özelliklere öncelik vermesine yardımcı olur ve diğer tarayıcı satıcılarına, bu özellikleri desteklemenin ne kadar kritik olduğunu gösterir.

• #ContentIndexingAPI hashtag'ini ve bu hashtag'i nerede ve nasıl kullandığınızla ilgili ayrıntıları kullanarak @ChromiumDev adresine tweet gönderin.

İçerik dizine eklemenin güvenlik ve gizliliğe ilişkin yanları nelerdir?

W3C'nin Güvenlik ve Gizlilik anketine yanıt olarak verilen cevaplara göz atın. Başka sorularınız varsa lütfen projenin GitHub deposu üzerinden tartışma başlatın.

Maksym Kaharlytskyi'nin Unsplash'teki lokomotif resmi.