Ç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

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 ve daha fazlası) erişebilmeniz 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 medyalar ve makaleler, Sizin için makaleler bölümünde gösterilir.

Ayrıca Chrome bir 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 zaten önbelleğe alınmış sayfalarla ilgili meta veriler sağlamanın bir yoludur. Böylece tarayıcı, kullanıcıların görüntülemek isteyebileceği zamanlarda bu sayfaları 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'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ı) Tarayıcınızın çevrimdışı olduğunu simüle etmek için cihazınızın kablosuz bağlantısını ve hücresel veri bağlantısını devre dışı bırakın veya uçak modunu etkinleştirin.
  5. Chrome menüsünden İndirilenler'i seçin ve Sizin iç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. Kod, Content Indexing API'nin Cache Storage API'yi kullanarak bir web uygulaması tarafından depolanan öğelerle senkronize edilmesini sağlayan bir tekniği göstermektedir.

API'yi kullanma

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ı, hizmet çalışanı oluşturmayı kolaylaştırabilir.

Ne tür URL'ler çevrimdışı 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.

Temel medya URL'sini sorgu parametresi olarak kabul edebilen ve daha sonra, muhtemelen sayfada ek kontroller veya içerikle birlikte dosyanın içeriğini görüntüleyen 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.

İçeriği dizine eklemenin ilk adımı, mevcut ServiceWorkerRegistration öğesine referans vermektir. 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 önceden tanımlanmıştır.

Dizine ekleme

URL'leri ve ilişkili meta verilerini 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 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 fetch işleyici kullanıyorsa window bağlamından add()'ü çağırın

add() işlevini çağırdığınızda Chrome, dizine eklenen içeriklerin listesini görüntülerken kullanacağı simgenin bir kopyasına sahip olduğundan emin olmak için her bir simgenin URL'si için istek gönderir.

  • 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 add()'ü çağırırsanız (belki başka bir etkinlik işleyici içinde) 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 meta verilerinin yinelenebilir bir listesi için bir promise 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.
}

Öğeleri dizinden kaldırma

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() işlevinin çağrılması 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ülerken Sil menü öğesini içeren kendi kullanıcı arayüzünü gösterebilir. Bu sayede kullanıcılar, daha önce dizine eklenen içeriği görüntülemeyi bitirdiklerini belirtebilir. 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ı hakkında geri bildirim

API ile ilgili tuhaf olan veya beklendiği gibi çalışmayan bir şey mi var? 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 uygulanmasıyla ilgili bir hata buldunuz mu?

https://new.crbug.com adresinden hata bildiriminde bulunun. Mümkün olduğunca çok ayrıntı ekleyin, yeniden oluşturma için 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ı tedarikçi firmalarına bu özellikleri desteklemenin ne kadar önemli olduğunu gösterir.

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

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

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

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