Topics API Geliştirici Kılavuzu

Test için Chrome flag'lerinin nasıl kullanılacağı da dahil olmak üzere API ile nasıl çalışılacağını öğ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 denemenize olanak tanıyan iki Topics API demosu vardır.

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

Konulara erişmek ve bunları gözlemlendiği ş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ıdan, geçerli sayfa ziyaretini arayan kullanıcı için gözlemlenmiş olarak kaydetmesini isteyin. Böylece bu daha sonra kullanıcıyla ilgili (arayan için) konuları hesaplamak için kullanılabilir.
  • Arayanın gözlemlediği, kullanıcıya ait erişim konuları.

Bu yöntem, en son üç dönemin her biri için bir tane olmak üzere rastgele sırayla en fazla üç konu içeren bir diziye dönüşen bir söz döndürür. Dönem, Chrome'un uygulanmasında bir hafta olarak ayarlanan süredir.

document.browsingTopics() tarafından döndürülen dizideki her topic nesnesi şu özelliklere sahiptir:

  • configVersion: Mevcut Topics API yapılandırmasını tanımlayan bir dize, ör. chrome.2
  • modelVersion: Site için konuları tahmin etmek amacıyla kullanılan makine öğrenimi sınıflandırıcısını tanımlayan bir dize, örneğin 4
  • taxonomyVersion: Tarayıcı tarafından kullanılan konu kümesini tanımlayan bir dize, örneğin 2
  • topic: Sınıflandırmada konuyu tanımlayan bir sayı, ör. 309
  • version: configVersion, taxonomyVersion ve modelVersion değerlerini birleştiren bir dize (ör. chrome.2:2:4)

Bu kılavuzda açıklanan parametreler ve API'nin ayrıntıları (ör. sınıflandırma boyutu, haftalık olarak hesaplanan konu sayısı ve çağrı başına döndürülen konu sayısı), ekosistemle ilgili geri bildirimleri dahil ettiğimiz ve API'yi geliştirdiğimiz süreçte değişebilir.

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

API'yi kullanmadan önce, API'nin 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

Aşağıda, geçerli kullanıcının konulara erişmek için olası API kullanımıyla ilgili temel bir örnek verilmiştir.

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.
}

Durumu değiştirmeden konulara erişme

document.browsingTopics(), geçerli kullanıcı için çağrının gözlemlediği konuları döndürür. Varsayılan olarak bu yöntem, tarayıcının geçerli sayfa ziyaretini çağrı tarafından gözlemlendiği şekilde kaydetmesine de neden olur. Böylece, daha sonra konu hesaplamasında kullanılabilir. Chrome 108'den itibaren bu yöntem, sayfa ziyaretinin kaydedilmesini atlayan 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 edilmesine neden olmayacağı anlamına gelir.

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

Konulara erişebilir ve ayrıca request ve yanıt üstbilgileri.

API, kaynaklar arası iframe oluşturulmasını ve bundan bir document.browsingTopics() çağrısı yapılmasını gerektirdiği için başlık yaklaşımının kullanılması JavaScript API'den çok daha etkili olabilir. (API'nin çağrıldığı bağlam, tarayıcının çağrıya uygun konuları döndürmesini sağlamak için kullanıldığından, çağrı için kaynaklar arası iframe kullanılmalıdır.) Konular açıklayıcıda daha ayrıntılı tartışmalara yer verilir: İstek başlığı olarak Getir özelliğini kullanarak konuları göndermenin bir yolu var mı? .

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

İsteğe verilen yanıtta Observe-Browsing-Topics: ?1 başlığı ayarlama tarayıcının, geçerli sayfa ziyaretini çağrı tarafından gözlemlendiği şekilde kaydetmesine neden olur. Böylece daha sonra konu hesaplamasında kullanılabilir.

Konulara HTTP üstbilgileriyle iki şekilde erişebilir ve bunları gözlemleyebilirsiniz:

  • fetch(): fetch() isteğinin options parametresine {browsingTopics: true} ekleyin. Konular 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 iframe.browsingTopics = true mülkü. iframe kaynağının kaydedilebilir alan adı arayanın alan adıdır: örneğin, <iframe src="https://example.com" browsingtopics></iframe>: Arayan example.com.
ziyaret edin.

Başlıklarla ilgili 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özlemlendiği gibi kaydedilmez, dolayısıyla kullanıcının bir sonraki dönem için konu hesaplamasını etkilemez.
  • Yanıt başlığı yalnızca ilgili istekte konu başlığı varsa dikkate alınır.
  • İsteğin URL'si, arayan alan adı olarak kaydedilen kaydedilebilir alan adını sağlar.

API uygulamanızda hata ayıklama

Topics API'yi etkinleştirdiğinizde chrome://topics-internals sayfası, masaüstündeki Chrome'da kullanılabilir. Bu sayfada geçerli kullanıcı konuları, ana makine adları için tahmin edilen konular ve API uygulamasıyla ilgili teknik bilgiler gösterilir. Geliştirici geri bildirimlerine göre sayfanın tasarımını tekrarlayıp iyileştiriyoruz. Geri bildiriminizi bugs.chromium.org adresine ekleyin.

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

Kullanıcılar, chrome://topics-internals sayfasında geçerli 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ı Konu Durumu panelinde konu kimlikleri, rastgele ve gerçek konu atamaları ile sınıflandırma ve model sürümleri gösterilir.

Bu ekran görüntüsünde, son ziyaret edilen siteler arasında topics-demo-cats.glitch.me ve cats-cats-cats-cats.glitch.me yer alıyor. Bu durum, Topics API'nin Pets ve Cats konuları mevcut dönemin en önemli konularından ikisi olarak seçmesine neden olur. Geri kalan üç konu ise beş konu sağlamak için yeterli tarama geçmişi (konuları gözlemleyen sitelerde) olmadığından rastgele seçildi.

Gözlemlenen bağlam alanları (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üle

chrome://topics-internals ürününde 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ı panelinde, seçilen konular, ziyaret edilen ana makineler, model sürümü ve yolu gösterilir.

Topics API'nin mevcut uygulaması, yalnızca ana makine adlarından konuları çıkarır; URL'nin başka herhangi bir kısmından değil.

chrome://topics-internals Sınıflandırıcı'dan tahmin edilen konuları görüntülemek için yalnızca ana makine adlarını kullanın (protokol veya yol olmadan). "/" eklemeye çalışırsanız chrome://topics-internals bir hata gösterir girin.

Topics API bilgilerini görüntüleme

Sınıflandırma sürümü ve dönem süresi gibi Topics API uygulaması ve ayarlarıyla ilgili bilgileri chrome://topics-internals sayfasında bulabilirsiniz. Bu değerler, komut satırından başarıyla ayarlanan API'nin veya parametrelerin varsayılan ayarlarını yansıtır. Bu, komut satırı işaretlerinin beklendiği gibi çalıştığını onaylamak için faydalı olabilir.

Örnekte, time_period_per_epoch 15 saniye (varsayılan, yedi gün) olarak 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ı hesaplamak için 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 ayarlanabilen işaretlere karşılık gelir. Örneğin, topics-fetch-demo.glitch.me adresindeki demoda aşağıdaki işaretlerin kullanılması önerilir:

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

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

Chrome flag'leri

BrowsingTopics
Varsayılan değer: etkin
Topics API'nin etkinleştirilip etkinleştirilmediği

PrivacySandboxAdsAPIsOverride
Varsayılan değer: etkin
Ads API'lerini etkinleştirir: Attribution Reporting, Protected Audience, 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
Bu ayar etkinleştirilirse tarayıcı artık aşağıdaki hesap için temel ayarların etkinleştirilmesini gerektirmez: Özel Korumalı Alan özelliklerini etkinleştirin.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Varsayılan değer: devre dışı
Bu ayar etkinleştirilirse IP adresinin herkese açık şekilde yönlendirilebilir olup olmadığı kontrol edilir bir sayfanın konulara dahil edilmeye uygun olup olmadığı belirlenirken atlanır. hesaplamanız gerekir.

BrowsingTopics:number_of_epochs_to_expose
Varsayılan değer: 3
Bir istekte bulunacak konuların hesaplanacağı dönem sayısı bağlam. Tarayıcı dahili olarak N+1 dönemlerine kadar izlemeye devam eder.

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 saniye olarak 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, rastgele bir zaman diliminde taksonominin tamamı görebilirsiniz. Rastgelelik bir dönem ve siteye bağlı kalır.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
Varsayılan değer: 3
API kullanım verilerinin (ör. konu gözlemleri) kaç döneminin kullanılacağı arama bağlamına göre konuları filtreleyerek.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Varsayılan değer: 1000
Her bir en popüler konu için saklanacak 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: 100.000
Her sorgu için veritabanından alınmasına izin verilen maksimum giriş sayısı bazı örnekler vereceğim. Sorgu, konu hesaplamasında dönem başına bir kez gerçekleşir gerekir. 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 kümesine eşlendi. Yapılandırma parametrelerini config_version güncellemeden güncellemek genellikle yerel test için uygundur, ancak bazı durumlarda tarayıcıyı tutarsız bir durumda olacak ve tarayıcının kilitlenmesine neden olabilir (örneğin, number_of_top_topics_per_epoch.

BrowsingTopics:taxonomy_version
Varsayılan değer: 1
Sınıflandırma sürümünü belirtin.

Sitenizi devre dışı bırakma

Bir sayfaya Permissions-Policy: browsing-topics=() Permissions-Policy başlığını ekleyerek sadece bir sayfadaki tüm kullanıcılar için konu hesaplamasını engellemek üzere sitenizdeki belirli sayfalar için konu hesaplamasını devre dışı bırakabilirsiniz. Sitenizdeki başka sayfalara daha sonra yapılan ziyaretler bu durumdan etkilenmez: Bir sayfada Topics API'yi engelleyen bir politika belirlerseniz diğer sayfalar etkilenmez.

Ayrıca, 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. Üstbilgi parametresi olarak self ifadesini ve API'ye erişmesine izin vermek istediğiniz tüm alanları kullanın. Örneğin, kendi kaynağınız ve https://example.com haricindeki tüm tarama 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