Topics API'yi uygulama

Bu sayfada, Topics API'yi çağıranların konuları gözlemlemesi ve konulara erişmesi için uygulama ayrıntıları açıklanmaktadır. Çözümünüzü uygulamaya başlamadan önce tarayıcınızın doğru şekilde ayarlandığından emin olun. Arayanların kullanıcıların konularını nasıl gözlemlediği ve bunlara nasıl eriştiği hakkında daha fazla bilgi edinmek için genel bakış bölümüne göz atın.

Topics'i gözlemleme ve erişme

Kullanıcının konularını gözlemlemenin ve bunlara erişmenin iki yolu vardır: HTTP başlıkları ve JavaScript API.

HTTP üstbilgileri

Kullanıcı konularını gözlemlemek ve bunlara erişmek için HTTP üstbilgilerini kullanmanız önerilir. Bu yaklaşım, JavaScript API'yi kullanmaktan çok daha iyi performans gösterebilir. HTTP başlıklarında, isteğin URL'si, arayan alan olarak kaydedilen tescil edilebilir alanı sağlar. Bu, kullanıcının konularını gözlemlediği görülen alan adıdır.

İsteği Başlatma

Başlıklarla konuları kullanmanın iki yolu vardır:

  • browsingTopics: true seçeneğini içeren bir fetch() isteğindeki istek ve yanıt başlıklarına erişerek.
  • browsingtopics özelliği içeren bir iframe öğesinin başlıklarına erişerek.
Getirme işlemiyle istek başlatma

API çağrısı yapan, getirme işlevini kullanarak seçenekler parametresine {browsingTopics: true} ekleyen bir istekte bulunur. Getirme isteğinin URL parametresinin kaynağı, konuları gözlemlediği görülen kaynaktır.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
İframe ile istek başlatma

browsingtopics özelliğini <iframe> öğesine ekleyin. Tarayıcı, iframe'in isteğine Sec-Browsing-Topics üstbilgisini ekler. Bu durumda, iframe'in kaynağı arayan olur.

   <iframe src="https://adtech.example" browsingtopics></iframe>

İstek üstbilgi değerlerini yorumlama

Hem getirme hem de iFrame yaklaşımlarında, bir kullanıcı için gözlemlenen konular sunucuda Sec-Browsing-Topics istek başlığından alınabilir. Topics API, fetch() veya iframe isteğinde kullanıcı konularını otomatik olarak başlığa ekler. API bir veya daha fazla konu döndürürse konuların gözlemlendiği kaynaktan alınan getirme isteği şu gibi bir Sec-Browsing-Topics üst bilgisi içerir:

   (325);v=chrome.1:1:1, ();p=P000000000

API tarafından konu döndürülmezse başlık şu şekilde görünür:

   ();p=P0000000000000000000000000000000

Yönlendirmeler takip edilir ve yönlendirme isteğinde gönderilen konular, yönlendirme URL'sine özel olur. Sec-Browsing-Topics üstbilgi değerleri, saldırganın üstbilgi uzunluğuna göre bir arayanla kapsamı belirlenmiş konu sayısını öğrenme riskini azaltmak için doldurulur.

Sunucu tarafı yanıtını işleme

İsteğe verilen yanıtta Observe-Browsing-Topics: ?1 üstbilgisi varsa bu, tarayıcının eşlik eden isteğin konularını gözlemlenmiş olarak işaretlemesi ve mevcut sayfa ziyaretini kullanıcının bir sonraki dönem konu hesaplamasına dahil etmesi gerektiğini gösterir. Sunucu taraflı kodunuzdaki yanıta Observe-Browsing-Topics: ?1 üstbilgisini ekleyin:

   res.setHeader('Observe-Browsing-Topics', '?1');
Konuları ayarlamak ve almak için istek ve yanıt başlıkları.
iframe ve fetch() için üstbilgiler.

Gözlemlenen konuları iş ortaklarıyla paylaşma

STP'ler yalnızca yayıncı tarafında bulunduğundan TTP'ler, reklamverenin sitelerinde gözlemledikleri konuları iş ortağı STP'leriyle paylaşmak isteyebilir. Bunu, reklamverenin üst düzey bağlamındaki SSP'lere konular başlığıyla fetch() isteği göndererek yapabilirler.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

JavaScript ile konuları gözlemleme ve erişme

Topics JavaScript API yöntemi document.browsingTopics(), tarayıcı ortamında kullanıcının ilgi alanlarını hem gözlemlemenin hem de almanın bir yolunu sunar: - Gözlemi Kaydet: Tarayıcıya, arayanın kullanıcının mevcut sayfayı ziyaret ettiğini gözlemlediğini bildirir. Bu gözlem, gelecekteki dönemlerde arayan kişi için kullanıcının konu hesaplamasına katkıda bulunur. - Access Topics: Arayanın, kullanıcı için daha önce gözlemlediği konuları alır. Yöntem, en son dönemlerin her biri için bir tane olmak üzere en fazla üç konu nesnesinden oluşan bir diziyi rastgele sırada döndürür.

Topics JavaScript API demosunu çatallayıp kodunuz için başlangıç noktası olarak kullanmanızı öneririz.

API kullanılabilirliği

API'yi kullanmadan önce desteklendiğinden ve kullanıma sunulduğundan emin olun:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

iFrame yerleştirme

API'nin çağrıldığı bağlam, tarayıcının arayan için uygun konuları döndürmesini sağlamak üzere kullanıldığından çağrı için kaynaklar arası bir iFrame kullanılmalıdır. HTML'nize bir <iframe> öğesi ekleyin:

<iframe src="https://example.com" browsingtopics></iframe>

JavaScript kullanarak dinamik olarak bir iFrame de oluşturabilirsiniz:

 const iframe = document.createElement('iframe');
 iframe.setAttribute('src', 'https://adtech.example/');
 document.body.appendChild(iframe);

API'yi iFrame'den çağırma

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

Varsayılan olarak, document.browsingTopics() yöntemi, tarayıcının arayan tarafından gözlemlenen mevcut sayfa ziyaretini kaydetmesine de neden olur. Böylece, daha sonra konuların hesaplanmasında kullanılabilir. Sayfa ziyaretinin kaydedilmesini atlamak için yönteme isteğe bağlı bir bağımsız değişken ({skipObservation:true}) iletilebilir.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

Yanıtı anlama

En fazla üç konu döndürülür: Konular gözlemlenip gözlemlenmediğine bağlı olarak, son üç haftanın her biri için bir veya sıfır. Yalnızca arayan tarafından mevcut kullanıcı için gözlemlenen konular döndürülür. API'nin döndürdüğü yanıtın bir örneğini aşağıda bulabilirsiniz:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: Tarayıcının konular algoritması yapılandırma sürümünü tanımlayan bir dize.
  • modelVersion: Konuları tahmin etmek için kullanılan makine öğrenimi sınıflandırıcısını tanımlayan bir dize.
  • taxonomyVersion: Tarayıcı tarafından kullanılan konu grubunu tanımlayan bir dize.
  • topic: Taksonomideki konuyu tanımlayan bir sayı.
  • version: configVersion, taxonomyVersion ve modelVersion değerlerini birleştiren bir dize. Bu kılavuzda açıklanan parametreler ve API'nin ayrıntıları (ör. sınıflandırma boyutu, haftada hesaplanan konu sayısı ve çağrı başına döndürülen konu sayısı), ekosistem geri bildirimlerini dahil edip API'yi yinelemeli olarak geliştirdikçe değişebilir.

Hangi yanıtı bekleyeceğinizi ve daha alakalı reklamlar için Konular'ı ek bir sinyal olarak nasıl kullanacağınızı öğrenmek için Test etme ve yayına alma sayfasına bakın.

Sonraki adımlar

Topics tabanlı çözümleri nasıl dağıtacağınızı, test edeceğinizi ve ölçeklendireceğinizi öğrenin.
Topics API bilgilerini görüntülemek, konuların nasıl atandığını anlamak ve uygulamanızda hata ayıklama yapmak için Chrome'da kullanılabilen araçlar hakkında bilgi edinin.

Aşağıdaki kaynakları da incelemenizi öneririz:

Web'de Topics API'yi daha iyi anlamak için kaynaklarımıza göz atın.