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.
- JavaScript API demosu: topics-demo.glitch.me.
- Başlık demosu: topics-fetch-demo.glitch.me
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ğin4
taxonomyVersion
: Tarayıcı tarafından kullanılan konu kümesini tanımlayan bir dize, örneğin2
topic
: Sınıflandırmada konuyu tanımlayan bir sayı, ör.309
version
:configVersion
,taxonomyVersion
vemodelVersion
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 JavaScriptiframe.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>
: Arayanexample.com
.
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ı.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-0a0a54332c409.png?authuser=8&hl=tr)
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ı.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-680196727dbe8.png?authuser=8&hl=tr)
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ı.](https://developers.google.cn/static/privacy-sandbox/assets/images/chrometopics-internals-a56a143c41aa1.png?authuser=8&hl=tr)
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
- Konular ve işleyiş şekilleri 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.