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

Hizmet işçilerinin tarayıcılara hangi sayfaların çevrimdışı çalıştığını söylemesini sağlama

Jeff Posnick

Content Indexing API nedir?

Progresif web uygulaması kullanmak, ağ bağlantınızın mevcut durumundan bağımsız olarak kullanıcıların önemsediği bilgilere (resimler, videolar, makaleler vb.) erişmeniz anlamına gelir. Hizmet çalışanları, Cache Storage API ve IndexedDB gibi teknolojiler, kullanıcılar doğrudan bir PWA ile etkileşime geçtiğinde verileri depolamak ve sunmak için temel yapı taşlarını sağlar. Ancak yüksek kaliteli, çevrimdışı öncelikli bir PWA oluşturmak, işin yalnızca bir kısmıdır. Kullanıcılar bir web uygulamasının içeriğinin çevrimdışıyken de kullanılabileceğini fark etmezse bu işlevi uygulamak için yaptığınız çalışmalardan tam olarak yararlanamazlar.

Bu bir keşif sorunudur. PWA'nız, kullanıcıların mevcut içeriği keşfedip görüntüleyebilmesi için çevrimdışı içerikleri hakkında nasıl bilgi verebilir? İçerik Dizine Ekleme API'si bu soruna çözümdür. Bu çözümün geliştiricilere yönelik kısmı, hizmet işçilerinin bir uzantısıdır. Bu uzantı, geliştiricilerin çevrimdışı olarak kullanılabilen sayfaların URL'lerini ve meta verilerini tarayıcı tarafından yönetilen yerel bir dizine eklemesine olanak tanır. Bu geliştirme, Chrome 84 ve sonraki sürümlerde kullanılabilir.

Dizine, PWA'nızdaki ve diğer yüklü PWA'lardaki içerikler eklendikten sonra, tarayıcı tarafından aşağıda gösterildiği gibi gösterilir.

Chrome'un yeni sekme sayfasındaki İndirmeler menü öğesinin ekran görüntüsü.
Öncelikle Chrome'un yeni sekme sayfasında İndirilenler menü öğesini seçin.
Dizine eklenen medyalar ve makaleler.
Dizine eklenen medya ve makaleler, Size Özel Makaleler bölümünde gösterilir.

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

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

İşleyiş şeklini görün

İçerik dizine ekleme API'sini anlamanın 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ümlerle sınırlıdır. Kullandığınız Chrome sürümünü görmek için about://version bölümüne 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ışına alma simülasyonu yapmak için uçak modunu etkinleştirin.
  5. Chrome'un menüsünden İndirilenler'i seçin ve Sizin İçin 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.

Albüm PWA adlı başka bir örnek uygulama, Content Indexing API'nin Web Share Target API ile kullanımını gösterir. Bu kod, İçerik Dizine Ekleme API'sini Cache Storage API'yi kullanan bir web uygulaması tarafından depolanan öğelerle senkronize halde tutmak için bir teknik gösterir.

API'yi kullanma

API'yi kullanmak için uygulamanızda bir hizmet çalışanı ve çevrimdışı gezinilebilen URL'ler olmalıdır. Web uygulamanızın halihazırda bir Service Worker'ı yoksa Workbox kitaplıkları hizmet çalışanı oluşturma işlemini basitleştirebilir.

Hangi 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ınmış 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, temel medya URL'sini sorgu parametresi olarak kabul edebilecek ve ardından dosyanın içeriğini (muhtemelen sayfadaki ek kontroller veya içeriklerle birlikte) görüntüleyebilecek bir "görüntüleyici" HTML sayfası oluşturmaktır.

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

Genel Bakış

Content Indexing API üç işlemi destekler: meta veri ekleme, listeleme ve kaldırma. Bu yöntemler, ServiceWorkerRegistration arayüzüne eklenen yeni bir mülk olan index üzerinden gösterilir.

İçerik dizine ekleme işleminin ilk adımı, mevcut ServiceWorkerRegistration referansını almaktır. navigator.serviceWorker.ready kullanmak en basit yöntemdir:

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ı içinden değil, bir servis çalışanı içinden çağrı gönderiyorsanız ServiceWorkerRegistration doğrudan registration üzerinden referans verebilirsiniz. ServiceWorkerGlobalScope. kapsamında zaten tanımlanmış

Dizine ekleme

URL'leri ve bunlarla ilişkili meta verileri dizine eklemek için add() yöntemini kullanın. Öğelerin dizine ne zaman ekleneceğini seçebilirsiniz. "Çevrimdışı kaydet" düğmesini tıklamak gibi bir girişe yanıt olarak dizine ekleme yapmak isteyebilirsiniz. Alternatif olarak, önbelleğe alınan veriler her güncellendiğinde düzenli arka plan senkronizasyonu gibi bir mekanizma aracılığıyla öğ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 dizini üzerinde etkilidir ve önbelleğe hiçbir şey eklemez.

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

add() işlevini çağırdığınızda Chrome, dizine eklenen içeriklerin listesini görüntülerken simgenin bir kopyasının bulunduğundan emin olmak amacıyla her simgenin URL'si için istekte bulunur.

  • add() işlevini window bağlamından (yani web sayfanızdan) çağırırsanız bu istek, hizmet işleyicinizde bir fetch etkinliği tetikler.

  • Hizmet çalışanınızda (başka bir etkinlik işleyici içinde) add() çağrısı yaparsanı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 bağlıysa (ör. ağda değil, yalnızca yerel önbellekte mevcut oldukları için) bunu göz önünde bulundurun. Destekleniyorsa add() işlevini yalnızca window bağlamından çağırdığınızdan emin olun.

Dizin içeriğini listeleme

getAll() yöntemi, dizine eklenen girişlerin ve bunların meta verilerinin yinelenebilir bir listesi için bir taahhüt 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, kaldırılacak öğenin id ile delete() işlevini çağırın:

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

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

Kullanıcı silme etkinliğini işleme

Tarayıcı, dizine eklenen içeriği görüntülediğinde, Sil menü öğesiyle birlikte kendi kullanıcı arayüzünü içerebilir. Bu da kullanıcılara daha önce dizine eklenen içeriği tamamladıklarını gösterme fırsatı verir. Chrome 80'de silme arayüzü şu şekilde görünür:

Sil menü öğesi.

Bir kullanıcı bu menü öğesini seçtiğinde web uygulamanızın hizmet çalışanı bir contentdelete etkinliği alır. Bu etkinliği işlemek isteğe bağlıdır ancak hizmet çalışanınızın, kullanıcının artık kullanmadığını belirttiği içerikleri (ör. yerel olarak önbelleğe alınmış medya dosyaları) "temizlemesi" için bir fırsat sunar.

contentdelete işleyicinizin içinde registration.index.delete() işlevini çağırmanız gerekmez. 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ıyla ilgili geri bildirim

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

Content Indexing API açıklamalı GitHub deposunda sorun bildirin veya mevcut bir soruna düşüncelerinizi ekleyin.

Uygulamayla ilgili sorun mu yaşıyorsunuz?

Chrome'un uygulamasında bir hata mı buldunuz?

https://new.crbug.com adresinden hata kaydı oluşturun. Olabildiğince fazla ayrıntı ve hatayı yeniden oluşturmayla ilgili basit talimatlar ekleyin. 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ı tedarikçi firmalarına bu özellikleri desteklemenin ne kadar önemli olduğunu gösterir.

İçerik dizine eklemenin güvenlik ve gizlilikle ilgili bazı sonuçları nelerdir?

W3C'nin Güvenlik ve Gizlilik Anketi'ne verilen yanıtlara göz atın. Başka sorularınız varsa lütfen projenin GitHub deposunda bir tartışma başlatın.

Unsplash'taki Maksym Kaharlytskyi tarafından oluşturulan hero resim.