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.
- JavaScript API demosu: topics-demo.glitch.me.
- Başlık demosu: topics-fetch-demo.glitch.me
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ğinchrome.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
vemodelVersion
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.
API, çapraz kaynak iframe oluşturmayı ve bundan document.browsingTopics()
çağrısı yapmayı gerektirdiğinden başlık yaklaşımını kullanmak, JavaScript API'sini kullanmaktan çok daha etkili olabilir. (Tarayıcının arayana uygun konuları döndürmesini sağlamak için API'nin çağrıldığı bağlam kullanıldığından, çağrıda çapraz kaynak iframe kullanılmalıdır.) Konular açıklayıcısında daha ayrıntılı bilgi bulunmaktadır: İstek başlığı olarak Getir aracını kullanarak konu 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
ü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ğiniiframe.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.
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.
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.
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
- Konuların ne olduğu ve nasıl işlediği hakkında daha fazla bilgi edinin.
- Demoyu deneyin.
Daha fazla bilgi
Etkileşimde bulunun ve geri bildirim paylaşın
- GitHub: Topics API açıklamasını okuyun ve API deposundaki soruları sorun ve tartışmaları takip edin.
- W3C: Web Reklamcılığı İş Grubunu İyileştirme bölümünde sektördeki kullanım alanlarını tartışın.
- Duyurular: Posta listesine katılın veya listeyi görüntüleyin.
- Özel Korumalı Alan geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği deposunda sorular sorun ve tartışmalara katılın.
- Chromium: Chrome'da şu anda test edilmek üzere kullanılabilen uygulama hakkında soru sormak için Chromium hatası bildiriminde bulunun.