Topics API Geliştirici Kılavuzu

Test amacıyla Chrome işaretlerini kullanma da dahil olmak üzere API ile çalışmayı öğrenin.

Uygulama durumu

  • Herkese açık tartışma aşamasını tamamlayan Topics API, şu anda kullanıcıların %99'unun kullanımına sunulmuştur ve ölçeği %100'e kadar çıkmaktadır.
  • Topics API hakkında geri bildirimde bulunmak için Topics açıklayıcı'da bir sorun oluşturun veya Web Advertising Business Group'u (Web Reklamcılığını İyileştirme İşletme Grubu) tartışmalarına katılın. Açıklayıcıda hâlâ daha ayrıntılı tanımlama gereken birkaç açık soru vardır.
  • Özel Korumalı Alan zaman çizelgesi, Topics API ve diğer Özel Korumalı Alan teklifleri için uygulama zaman çizelgeleri sağlar.
  • Topics API: son güncellemeler Topics API ve uygulamalarla ilgili değişiklikler ve geliştirmeleri ayrıntılarıyla açıklar.

Demoyu deneyin

Topics'i tek bir kullanıcı olarak denemeniz için iki Topics API demosu vardır.

Konular sınıflandırıcı modelini denemek için Konular colab'ini de çalıştırabilirsiniz.

Konulara erişmek ve gözlemlenen şekilde kaydetmek için JavaScript API'yi kullanın

Topics JavaScript API'nin tek bir yöntemi vardır: document.browsingTopics(). Bunun iki amacı vardır:

  • Tarayıcıya, geçerli sayfa ziyaretini arayan için gözlemlenmiş olarak kaydetmesini söyleyin. Böylece bu, daha sonra kullanıcının konularını hesaplamak (arayan için) amacıyla kullanılabilir.
  • Kullanıcı için, arayan tarafından gözlemlenen erişim konuları.

Yöntem, en son üç sıfır zamanın her biri için rastgele sırada olmak üzere en fazla üç konu dizisine çözümlenen bir söz döndürür. Dönem, Chrome uygulamasında bir hafta olarak ayarlanmış bir süredir.

document.browsingTopics() tarafından döndürülen dizideki her konu nesnesinin özellikleri şu şekildedir:

  • configVersion: Geçerli Topics API yapılandırmasını tanımlayan bir dize, örneğin chrome.2
  • modelVersion: Siteyle ilgili konuları anlamak için kullanılan makine öğrenimi sınıflandırıcısını tanımlayan bir dize (ör. 4)
  • taxonomyVersion: Tarayıcı tarafından kullanılan konu grubunu tanımlayan bir dize (örneğin, 2)
  • topic: Sınıflandırmada konuyu tanımlayan bir sayı (örneğin, 309)
  • version: configVersion, taxonomyVersion ve modelVersion karakterlerini birleştiren bir dize (örneğin, chrome.2:2:4)

Bu kılavuzda açıklanan parametreler ve API ayrıntıları (sınıflandırma boyutu, haftalık olarak hesaplanan konu sayısı ve arama başına döndürülen konu sayısı gibi), ekosistem geri bildirimlerini dahil ettikçe ve API iterasyonu yaptıkça değişebilir.

document.browsingTopics için desteği algılama

API'yi kullanmadan önce tarayıcı tarafından desteklenip desteklenmediğini ve dokümanda mevcut olup olmadığını kontrol edin:

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
 console.log('document.browsingTopics() is supported on this page') :
 console.log('document.browsingTopics() is not supported on this page');

JavaScript API ile konulara erişme

Mevcut kullanıcının konularına erişmek için olası API kullanımına dair temel bir örneği burada bulabilirsiniz.

try {
  // Get the array of top topics for this user.
  const topics = await document.browsingTopics();
  
  // Request an ad creative, providing topics information.
  const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
  })
  
  // Get the JSON from the response.
  const creative = await response.json();
  
  // Display ad.

} catch (error) {
  // Handle error.
}

Konulara durumu değiştirmeden erişme

document.browsingTopics(), arayan tarafından geçerli kullanıcı için gözlemlenen konuları döndürür. Varsayılan olarak, bu yöntem aynı zamanda tarayıcının, geçerli sayfa ziyaretini arayan tarafından gözlemlendiği şekilde kaydetmesine neden olur; böylece, daha sonra konu hesaplamasında kullanılabilir. Chrome 108'den itibaren, sayfa ziyaretinin kaydedilmesini atlamak için yönteme isteğe bağlı bir bağımsız değişken iletilebilir: {skipObservation:true}.

Diğer bir deyişle, {skipObservation:true}, yöntem çağrısının, geçerli sayfanın konuların hesaplamasına dahil edilmemesine neden olmayacağı anlamına gelir.

Konulara erişmek ve gözlemlenen olarak işaretlemek için başlıkları kullanın

Konulara erişebilir ve ayrıca istek ve yanıt başlıklarının yardımıyla sayfa ziyaretlerini gözlemlendi olarak işaretleyebilirsiniz. Başlık yaklaşımını kullanmak, JavaScript API'sini çağırmaktan çok daha etkili olabilir.

Konulara, fetch() veya XHR isteğinin Sec-Browsing-Topics başlığından erişilebilir.

İsteğe verilen yanıtta Observe-Browsing-Topics: ?1 üstbilgisi ayarlamak, tarayıcının mevcut sayfa ziyaretini arayan tarafından gözlemlendiği şekilde kaydetmesine neden olur. Böylece, daha sonra konu hesaplamasında kullanılabilir.

Konulara HTTP üst bilgileri ile iki şekilde erişilebilir ve bunlar gözlemlenebilir:

  • fetch(): fetch() isteğinin options parametresine {browsingTopics: true} ekleyin. Konu başlığı demosu, bunun basitleştirilmiş bir örneğini gösterir.
  • iframe özelliği: browsingtopics özelliğini bir <iframe> öğesine ekleyin veya eşdeğer JavaScript özelliğini iframe.browsingTopics = true ayarlayın. iframe kaynağının kaydedilebilir alan adı, çağrı yapan alan adıdır. Örneğin, <iframe src="https://example.com" browsingtopics></iframe> için: Arayan alan adı: example.com.

Başlıklar hakkında bazı ek notlar:

  • Yönlendirmeler izlenir ve yönlendirme isteğinde gönderilen konular, yönlendirme URL'sine özel olur.
  • İstek başlığı, karşılık gelen bir yanıt başlığı olmadığı sürece arayanın durumunu değiştirmez. Yani, yanıt başlığı olmadan sayfa ziyareti gözlemlenmiş olarak kaydedilmez. Bu nedenle, kullanıcının bir sonraki dönem için konu hesaplamasını etkilemez.
  • Yalnızca ilgili istekte konu başlığı varsa yanıt başlığı dikkate alınır.
  • İsteğin URL'si, arayan alan adı olarak kaydedilen kaydedilebilir alanı sağlar.

API uygulamanızdaki hataları ayıklayın

Topics API'yi etkinleştirdiğinizde chrome://topics-internals sayfası masaüstündeki Chrome'da kullanılabilir. Mevcut kullanıcıyla ilgili konular, ana makine adlarıyla ilgili olarak belirlenen konular ve API uygulamasıyla ilgili teknik bilgiler burada gösterilir. Sayfanın tasarımını geliştiricilerden aldığımız geri bildirimlere göre geliştiriyor ve iyileştiriyoruz: Geri bildiriminizi bugs.chromium.org adresinden ekleyin.

Tarayıcınız için hesaplanan konuları görüntüleme

Kullanıcılar, chrome://topics-internals içinde mevcut ve önceki dönemlerde tarayıcılarında gözlemlenen konularla ilgili bilgileri görüntüleyebilir.

Konu Durumu panelinin seçili olduğu chrome://topics-internals sayfası.
chrome://topics-internals sayfasındaki Konular Durumu panelinde konu kimlikleri, rastgele ve gerçek konu atamaları, sınıflandırma ve model sürümleri gösterilir.

Bu ekran görüntüsü, en son ziyaret edilen sitelerin topics-demo-cats.glitch.me ve cats-cats-cats-cats.glitch.me içerdiğini göstermektedir. Bu durum, Topics API'nin Pets ve Cats konularını mevcut dönemin en önemli konulardan ikisi olarak seçmesine neden olur. Geri kalan üç konu rastgele seçildi. Bunun nedeni, beş konu sunmak için yeterli tarama geçmişi (konuların gözlemlenen sitelerde) bulunmamasıdır.

Bağlam tarafından gözlemlenen alan adları (karma oluşturma işlemi uygulanmış) sütunu, bir konunun gözlemlendiği ana makine adının karma oluşturma işlemi uygulanmış değerini sağlar.

Ana makine adları için tahmin edilen konuları görüntüleme

chrome://topics-internals içinde bir veya daha fazla ana makine adı için Konular sınıflandırıcı modeli tarafından tahmin edilen konuları da görüntüleyebilirsiniz.

Sınıflandırıcı panelinin seçili olduğu chrome://topics-internals sayfası.
chrome://topics-internals sayfası Sınıflandırıcı paneli; seçilen konuları, ziyaret edilen ana makineleri ve model sürümü ile yolunu gösterir.

Topics API'nin geçerli uygulaması, konuları URL'nin herhangi bir bölümünden değil, yalnızca ana makine adlarından çıkarır.

chrome://topics-internals Sınıflandırıcı'dan çıkarılan konuları görüntülemek için yalnızca ana makine adlarını (protokol veya yol olmadan) kullanın. Host (Barındırıcı) alanına "/" karakteri eklemeye çalışırsanız chrome://topics-internals bir hata görüntüler.

Topics API bilgilerini görüntüleme

chrome://topics-internals bölümünde Topics API'nin uygulanması ve ayarları (sınıflandırma sürümü ve dönem süresi gibi) hakkında bilgi bulabilirsiniz. Bu değerler, API'nin varsayılan ayarlarını veya komut satırından başarıyla ayarlanmış parametreleri yansıtır. Bu işlem, komut satırı işaretlerinin beklendiği gibi çalıştığını doğrulamanıza yardımcı olabilir.

Örnekte time_period_per_epoch 15 saniyeye (varsayılan süre yedi gündür) ayarlanmıştır.

Özellikler ve Parametreler panelinin seçili olduğu chrome://topics-internals sayfası.
chrome://topics-internals Özellikler ve Parametreler panelinde etkin özellikler, dönem başına süre, konuların hesaplanmasında kullanılacak dönem sayısı, sınıflandırma sürümü ve diğer ayarlar gösterilir.

Ekran görüntüsünde gösterilen parametreler, Chrome'u komut satırından çalıştırırken ayarlanabilecek işaretlere karşılık gelir. Örneğin, topics-fetch-demo.glitch.me adresindeki demo, aşağıdaki işaretlerin kullanılmasını önerir:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

Aşağıdaki listede her parametre, varsayılan değeri ve amacı açıklanmaktadır.

Chrome flag'leri

BrowsingTopics
Varsayılan değer: etkin
Topics API'nin etkin olup olmadığı.

PrivacySandboxAdsAPIsOverride
Varsayılan değer: etkin
Ads API'lerini etkinleştirir: İlişkilendirme Raporları, Korunan Kitle, Konular, Kısıtlanmış Çerçeveler.

PrivacySandboxSettings4
Varsayılan değer: devre dışı
Özel Korumalı Alan kullanıcı arayüzü ayarlarının dördüncü sürümünü etkinleştirir.

OverridePrivacySandboxSettingsLocalTesting
Varsayılan değer: etkin
Etkinleştirilirse tarayıcı, Özel Korumalı Alan özelliklerini etkinleştirmek için artık temel ayarların etkinleştirilmesini gerektirmez.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Varsayılan değer: devre dışı
Bu özellik etkinleştirilirse bir sayfanın konu hesaplamasına dahil edilmeye uygun olup olmadığı belirlenirken IP adresinin herkese açık şekilde yönlendirilebilir olup olmadığı kontrolü atlanır.

BrowsingTopics:number_of_epochs_to_expose
Varsayılan değer: 3
İstekte bulunan bağlama verilecek konuların hesaplanacağı dönem sayısı. Tarayıcı, N+1 dönemlerini dahili olarak saklar.

BrowsingTopics:time_period_per_epoch
Varsayılan değer: 7d-0s-0d-0s
Her dönemin süresi. Hata ayıklama için bu süreyi varsayılan yedi gün yerine 15 saniyeye ayarlamak yararlı olabilir.

BrowsingTopics:number_of_top_topics_per_epoch
Varsayılan değer: 5
Dönem başına hesaplanan konu sayısı.

BrowsingTopics:use_random_topic_probability_percent
Varsayılan değer: 5
Bir dönemdeki tek bir konunun, tüm konu sınıflandırmasından rastgele döndürülme olasılığı. Rastgele, bir dönem ve siteye bağlı.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
Varsayılan değer: 3
Bir çağrı bağlamı için konuları filtrelemek amacıyla API kullanım verilerinin kaç döneminin (konu gözlemleri) kullanılacağını belirtir.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Varsayılan değer: 1.000
Her bir en önemli konu için bağlama göre gözlemlenen maksimum alan sayısı. Amaç, kullanımdaki belleği sınırlamaktır.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Varsayılan değer: 100000
API kullanım bağlamları için her sorgu için veritabanından alınmasına izin verilen maksimum giriş sayısı. Sorgu, konular hesaplaması zamanında her dönemde bir kez gerçekleşir. Amaç, en yüksek bellek kullanımını sınırlamaktır.

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
Varsayılan değer: 30
Sayfa yükleme başına depolanmasına izin verilen maksimum API kullanım bağlamı alanı sayısı.

BrowsingTopics:config_version
Varsayılan değer: 1
Topics API yapılandırma parametrelerini kodlar. Her sürüm numarası yalnızca bir yapılandırma grubuna eşlenmelidir. Yapılandırma parametrelerini config_version güncellemesinden güncellemek yerel test için genellikle herhangi bir sorun oluşturmaz ancak bazı durumlarda tarayıcıyı tutarsız bir durumda bırakabilir ve bu durum, number_of_top_topics_per_epoch güncellemesinin güncellenmesi gibi bir tarayıcı kilitlenmesine yol açabilir.

BrowsingTopics:taxonomy_version
Varsayılan değer: 1
API tarafından kullanılan sınıflandırma sürümü.

Sitenizi kapsam dışında bırakma

Konu hesaplamasını yalnızca bir sayfadaki tüm kullanıcılar için engellemek amacıyla Permissions-Policy: browsing-topics=() Permissions-Policy başlığını ekleyerek sitenizdeki belirli sayfalar için konu hesaplamayı devre dışı bırakabilirsiniz. Sitenizdeki diğer sayfalara yapılacak sonraki ziyaretler etkilenmez: Bir sayfada Topics API'yi engelleyecek bir politika ayarlarsanız bu durum diğer sayfaları etkilemez.

Topics API'ye üçüncü taraf erişimini kontrol etmek için Permissions-Policy başlığını kullanarak sayfanızdaki konulara hangi üçüncü tarafların erişebileceğini kontrol edebilirsiniz. Başlık parametresi olarak self ve API'ye erişmesine izin vermek istediğiniz tüm alan adlarını kullanın. Örneğin, kendi kaynağınız ve https://example.com dışındaki tüm göz atma bağlamlarında Topics API'nin kullanımını tamamen devre dışı bırakmak için aşağıdaki HTTP yanıt başlığını ayarlayın:

Permissions-Policy: browsing-topics=(self "https://example.com")

Sonraki adımlar

Daha fazla bilgi

Etkileşimde bulunun ve geri bildirim paylaşın