Topics API entegrasyon kılavuzu

Reklam teknolojisiyle ilgili belirli kullanım alanlarını karşılamak için Topics API'yi nasıl kullanacağınızı öğrenin.

Başlamadan önce

İlk adım, Topics API ve hizmetleri hakkında bilgi edinmektir.

1. Geliştirici dokümanlarını inceleyin:
   1. Topics API ve özellikleri hakkında bilgi edinmek için ilk olarak genel bakış makalesini okuyun.
   2. Adım adım açıklamalı Topics demo videosunu (video) izleyin.
   3. Topics başlığı ve JavaScript API'si demolarını deneyin.
   4. Demoları çatallayın (her ikisi de kodlarına bağlantı verir) ve bunları kendi sitenizden çalıştırın.
   5. Daha fazla ayrıntı görmek için API açıklamasını okuyun.
2. Topics API'nin uygulama durumunu ve zaman çizelgesini kontrol edin.
3. API'nin çerezsiz bir gelecekte reklam alaka düzeyini desteklemedeki rolünü anlayın.
4. API'deki durum değişikliklerinden haberdar olmak için geliştiricilere yönelik posta listesine katılın ve Topics'teki en son güncellemeleri takip edin.
5. Topics API ile ilgili en son haberleri takip edin.
6. GitHub sorunları veya W3C çağrıları aracılığıyla sohbete katkıda bulunun.
7. Bilmediğiniz terimlerle karşılaşırsanız Özel Korumalı Alan sözlüğünü inceleyin.
8. Chrome işaretleri gibi Chrome kavramları hakkında daha fazla bilgi için goo.gle/cc adresindeki kısa videoları ve makaleleri inceleyin.

Yerel olarak derleyip test edin

Bu bölümde, Topics API'yi bireysel bir geliştirici olarak nasıl deneyebileceğiniz açıklanmaktadır.

1. Yerel test ve dağıtım (Tahmini süre: Yaklaşık 2 gün)
   1. Özellik bayraklarını kullanarak API'yi yerel tarayıcınızla komut satırından etkinleştirin. Topics'in nasıl çalıştığını görmek için başlık ve JavaScript API demolarını test edin (adım adım açıklamalı video).
   2. Topics makine öğrenimi modelini kullanarak konu çıkarımını test etmek için Topics ortak laboratuvarını çalıştırın.

Tarayıcınızda Topics'i etkinleştirin

Kendi Chrome örneğinizde Topics API'yi yerel test için etkinleştirmek üzere iki seçeneğiniz vardır:

1. chrome://settings/adPrivacy altındaki tüm reklam gizliliği API'lerini etkinleştirin.
2. (Önerilir) Gerektiğinde yapılandırmak için Topics API'ye özel parametreleri kullanarak Chrome'u Chromium işaretleriyle komut satırından çalıştırın.

Komut satırından Chrome'u çalıştırarak Topics özellikleri üzerinde daha hassas bir kontrole sahip olursunuz. Örneğin, Topics dönemleri (API'nin kullanıcı ilgi alanlarını hesaplamak için kullandığı zaman aralığı) ayarlamak ve API'nin davranışını ihtiyaçlarınıza göre yapılandırmak mümkündür.

Topics API mekaniklerini önizleyin

chrome://topics-internals araçlarını kullanarak Topics API mekaniklerini yerel olarak görebilirsiniz.

Ziyaret ettiğiniz sitelere göre sınıflandırıcıyı yerel olarak test etmek için Topics API Internals aracını kullanın.

Bu araçla şunları inceleyebilirsiniz:

• Konu Durumu: Geçerli kullanıcı için gözlemlenen konuları görüntüleyin.
• Sınıflandırıcı: Ana makine adları için tahmin edilen konuları önizleyin.
• Özellikler ve Parametreler: Özellik işaretlerinin amaçlandığı gibi çalışıp çalışmadığını kontrol etmek için API parametre değerlerini görüntüleyin.

Dahililer aracıyla konulardaki hataları nasıl ayıklayacağınızı öğrenin.

API konuları nasıl döndürür?

Chrome, bir dönemin (bir hafta) en önemli beş konusunu oluşturmaya yetecek kadar gözlemlenen konu içermiyorsa Topics API ilk beşi tamamlamak için rastgele konular ekler. Gerçek veya Rastgele başlıklı Konu Dahilileri sütunu, belirli bir konunun ilk beşi tamamlamak için gerçek bir gözleme mi yoksa ek rastgele "dolgu"ya mı dayalı olduğunu gösterir. Açıklayıcı bölümünde bu mekanizma hakkında daha fazla bilgi edinebilirsiniz.

Her bir dönem için kullanıcının söz konusu dönemde en çok ilgi gösterdiği beş konu arasından bir tanesi rastgele seçilir. Dönem içinde yeterli sayıda konu gözlemlenmediyse toplam beş konuyu oluşturmak için rastgele ek konular seçilir. Rastgele seçilen bu konular filtrelemeye tabidir.

Gizliliği daha da artırmak ve tüm konuların temsil edilmesini sağlamak amacıyla, belirli bir dönem için seçilen konunun, gözlemlenen konular yerine rastgele seçilme olasılığı% 5'tir. Çok az sayıda konunun gözlemlendiği yukarıdaki örnekte olduğu gibi, rastgele seçilen bu konular filtrelemeye tabi değildir.

Konuların nasıl seçildiği hakkında daha fazla bilgiye Konu sınıflandırması bölümünden ulaşabilirsiniz.

Temel öneriler

1. İşaretleri kullanarak yeni işlemi başlatmadan önce tüm Chrome işlemlerini kapattığınızdan (ve durdurduğunuzdan) emin olun.
2. chrome://settings/adPrivacy altında tüm reklam gizliliği API'lerinin etkinleştirildiğinden emin olun.
3. Topics'in yerel olarak nasıl çalıştığını anlamak için hata ayıklama sayfasını kullanın.
4. Sorularınız varsa Açıklayıcı için GitHub Sorunları sayfasına göz atın.
5. API beklendiği gibi çalışmıyorsa sorun giderme ipuçlarımızı deneyin.

MVP dağıtımınızı planlayın

Topics API, kullanıcının ziyaret ettiği siteleri izlemeye veya gezinme geçmişlerini göstermeye gerek kalmadan kullanıcının gözlemlenen ilgi alanına dayalı konulara erişim sağlar.

Topics API arayan, document.browsingTopics() JavaScript yöntemini çağıran veya HTTP istek başlıklarını kullanarak konuları gözlemleyip bunlara erişen varlıktır. Bu örnekte kodunuz ve çağrılandığı eTLD+1 arayan kişidir. Topics API'yi çağırdığınızda kullanıcının tarayıcısına, bir web sitesini ziyaret eden ilgili konuları gözlemlemesi için talimat vermiş olursunuz. Daha sonra bu ziyaret, bir sonraki dönemin konu hesaplamasına dahil edilir.

Topics API, arama bağlamının arayana veya eTLD+1'ine göre sonuçları filtrelemek için tasarlanmıştır. Başka bir deyişle, iframe'in kaynağı (JavaScript API'si kullanılırken) veya getirme isteğinin URL'si (başlıklar kullanılırken) çağrı yapan olarak kabul edilir ve konular o çağrıya göre hesaplanır.

Aşağıdaki şemada bu yaklaşım gösterilmektedir:

Bu şemada:

1. Bir kullanıcı Chrome'u açar ve reklam teknolojinizin iframe'ini (source: iframe.adtech.example) veya getirme çağrısı iletme başlıklarını içeren birden çok web sitesini (customerA.example, customerB.example.br vb.) ziyaret eder.
   • Chrome bu kullanıcının ilgi alanlarını kaydedecek.
2. Topics API'nin ilgi alanlarını dikkate alarak yedi gün boyunca gezinmesinin ardından aynı cihazdaki aynı kullanıcı bir hedef web sitesini (publisher-e.example) ziyaret eder. Topics API, konuların listesini döndürür ve bu örnekte, bu kullanıcının önceki haftaki gözlemlerine dayanarak hesaplanan bir konu döndürülür.
   • Yalnızca adtech.example'in 1. Adım'da gözlemlediği siteleri ziyaret eden kullanıcıların tarayıcıları 2. Adımdaki konu sonuçlarını döndürür (bu gözlem filtresi olarak adlandırılır; daha önce hiç görmediğiniz kullanıcı konularını göremezsiniz).
3. Şu an için tek bir konudan oluşan bu listeyle, konu verilerini içerik veri kümenizin bir parçası olarak kullanmak için arka uç API'nizi (ads.adtech.example/topics-backend) çağırabilirsiniz.
4. Artık kullanım alanınıza bağlı olarak, son haftalarda gözlemlediğiniz ilgi alanlarına erişerek bu kullanıcı için daha kişiselleştirilmiş bir deneyim oluşturabilirsiniz.

Topics API'yi çağırma

Kullanıcıların konularını gözlemlemenin ve bu konulara erişmenin iki yolu vardır. Tekliflerinizi otomatikleştirmek ve optimize etmek için

• Bir iframe içinden JavaScript API'si:
  • document.browsingTopics() kullanarak Topics API'yi çağıran JavaScript kodu içeren hedef web sitelerine (yayıncı web siteleri) bir iframe ekleme.
• Başlık seçeneği:
  • Getirme (önerilir) veya XHR (önerilmez ve yalnızca tamamlanan kaynak denemesi sırasında kullanılabilir):
    • Reklam teknolojisi arka ucuna yapılan isteklerde Sec-Browsing-Topics başlığından konulara erişebilirsiniz. Bu en etkili seçenektir (belirli bir kullanıcının konularını gözlemlemek için düşük gecikme süresi).
  • browsingtopics özelliğiyle bir iFrame etiketi kullanma:
    • browsingtopics özelliğine sahip bir iframe ekleyebilirsiniz. Bu durumda Chrome, iframe isteğinin Sec-Browsing-Topics başlığına konuları (iframe'in eTLD+1'i için gözlemlenen) dahil eder.

JavaScript ve iframe'lerle uygulayın

Topics JavaScript API demosunu veya başlık demosunu çatallamanızı ve bunlardan birini kodunuz için başlangıç noktası olarak kullanmanızı öneririz.

HTML'ye bir <iframe> öğesi dahil edebilir veya JavaScript ile dinamik bir şekilde iframe ekleyebilirsiniz. Dinamik olarak iframe oluşturmanın bir yolu aşağıdaki JavaScript'i kullanmaktır:

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

Özellik algılama aracılığıyla Topics API'nin bu cihazda desteklenip desteklenmediğini 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');

Söz konusu iFrame içinden Topics API'yi çağırın:

const topics = await document.browsingTopics();

Bu kullanıcı için son üç hafta içinde gözlemlenen konuların bir listesini alacaksınız. Bu listenin boş olabileceğini veya son üç haftaya kadar 1, 2 ya da 3 konu içerebileceğini unutmayın.

Aşağıda, API'nin döndürdüğü verilere bir örnek verilmiştir:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]

• configVersion: Geçerli yapılandırmayı 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ılmakta olan konu grubunu tanımlayan bir dize.
• topic: Sınıflandırmada konuyu tanımlayan bir sayı.
• version: configVersion ile modelVersion değerlerini birleştiren bir dize.

Bu uygulama hakkında daha fazla bilgi

HTTP başlıklarıyla uygulayın

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

İsteğin yanıtına bir Observe-Browsing-Topics: ?1 başlığı ayarlayarak istek başlıklarında sağlanan konuları gözlemlendi olarak işaretleyebilirsiniz. Ardından tarayıcı, bu konuları kullanarak kullanıcının ilgi alanlarını hesaplar.

API bir veya daha fazla konu döndürürse konuların gözlemlendiği eTLD+1'e yapılan bir getirme isteği, şuna benzer bir Sec-Browsing-Topics başlığı içerir:

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

API herhangi bir konu döndürmezse başlık şu şekilde görünür:

();p=P0000000000000000000000000000000

Saldırganın, üstbilgi uzunluğuna göre bir çağrı kapsamındaki konuların sayısını öğrenme riskini azaltmak için Sec-Browsing-Topics üst bilgi değerleri doldurulur.

fetch() ile uygulayın

Yayıncı sayfasında, {browsingTopics: true} öğesini de ekleyerek getirme isteği için kodunuzu ekleyin.

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

API'yi destekleyen tarayıcılarda fetch() isteği, istek URL'si ana makine adı için gözlemlenen konuları listeleyen bir Sec-Browsing-Topics başlığı içerir.

iFrame ile uygulama

fetch() isteğine benzer şekilde, iframe'de browsingtopics özelliği kullanılırken Sec-Browsing-Topics başlığı gönderilir.

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

Bu durumda , getirme çağrısına benzer şekilde arayan olacaktır.

Sunucu tarafı - tüm durumlarda aynı

Sec-Browsing-Topics istek başlığındaki konuların tarayıcı tarafından gözlemlendi olarak işaretlenmesi için ve aynı zamanda geçerli sayfa ziyaretinin kullanıcının bir sonraki dönemin en önemli konu hesaplamasına dahil edilmesi için sunucunun yanıtının Observe-Browsing-Topics: ?1 içermesi gerekir.

Aşağıda, setHeader() kullanan bir JavaScript örneği verilmiştir:

res.setHeader('Observe-Browsing-Topics', '?1');

Topics arka uç uygulaması

Topics için arka uç eklemek isteğe bağlıdır. Seçiminiz, cihazda hesaplanan konuları nasıl ve nerede kullanmak istediğinize bağlıdır (tarayıcıda).

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

Konuları içerik verileri olarak kullanma

Konu verileri, kitlenizle ilgili ek bir sinyal olarak URL'ler, anahtar kelimeler, hatta etiketler gibi diğer sinyallerin yanında dikkate alınabilir.

Üçüncü taraf çerezlerinden sonra reklam alaka düzeyini en üst düzeye çıkarma bölümünde açıklandığı gibi, alakalı reklamlar yayınlamak için Topics'ten yararlanma konusunda çeşitli yaklaşımlar vardır. Bu yöntemlerden bazıları kitle oluşturmak için konuların kullanılmasını içerirken bazıları da kitlenin ek ilgi alanlarını belirlemek veya teklif mantığını optimize etmek için kullanılacak makine öğrenimi modellerini eğitmek amacıyla diğer sinyallerden biri olarak Topics'i kullanmayı önerir.

Derleme ve dağıtma

1. Üretimde kullanıcıları gözlemleyerek konuları toplayın (henüz ölçeklenmemiştir (Tahmini süre: Yaklaşık 1 hafta))
   1. Seçeneklerinizi anlayın: iframe ve JavaScript veya HTTP üstbilgileri
   2. iframe'in alanını tanımlayın.
   3. Kod referansı olarak demo uygulamasını kullanarak JavaScript kodunu oluşturun veya başlıklar seçeneğini uygulayın.
   4. Topics'i denetlenen ortamınıza (bazı üretim siteleri) dağıtın.
   5. Bazı hedef sitelere (şu anda en fazla beş site) Topics uygulamasını ekleyin.
   6. İşlevsel test ve doğrulama.
2. [İsteğe bağlı] Topics verilerini, bağlamsal bir sinyal olarak kullanın (URL'ler, etiketler vb. ile) (Tahmini süre: Yaklaşık 3 gün).
   1. Konuların listesini aldıktan sonra, bu listeyi diğer içerik sinyalleriyle birlikte arka ucunuza gönderebilirsiniz.

Bazı hedef sitelere dağıtın

Artık kodu edindiğinize göre ilk test için bazı hedef sitelere ekleyip API'nin kararlı olduğundan ve bu kontrollü ortamda çalıştığından emin olalım.

Şu özelliklere sahip web sitelerini seçmeniz önerilir:

• Az sayıda aylık ziyaret alın (ayda yaklaşık 1 milyondan az ziyaret): API'yi önce küçük bir kitleye dağıtarak başlamanız gerekir.
• Sahibi olduğunuz ve denetlediğiniz: Gerekirse uygulamayı karmaşık onaylar olmadan hızlı bir şekilde devre dışı bırakabilirsiniz.
• İş açısından kritik değil: Bu uygulama, kullanıcı deneyimini olumsuz etkileyebileceğinden, düşük riskli hedef sitelerle başlayın.
• Toplamda beş siteden fazla site yoktur: Şimdilik bu kadar trafik veya gösterim almanıza gerek yoktur.
• Farklı temaları temsil edin: Farklı kategorileri temsil eden web siteleri seçin (örneğin, spor, haberler, yeme-içme vb. ile ilgili bir başka web sitesi). Alanları ve Topics makine öğrenimi sınıflandırıcısı tarafından nasıl sınıflandırıldıklarını doğrulamak için Chrome'daki dahili konular aracını kullanabilirsiniz. Topics API geliştirici kılavuzunda hata ayıklama hakkında daha fazla bilgi edinin.

İşlevsel test ve doğrulama

Bu sınırlı ortamda Topics API'yi çağırırken aşağıdakilerle karşılaşabilirsiniz:

• Bu cihazın ilk aramasıysa, son yedi gün içinde bu site ve arayan için boş bir konu dizisi [].
• Bu kullanıcının ilgi alanlarını temsil eden sıfır ila üç konudan oluşan bir liste.
• Yedi günlük gözlemden sonra şunları alırsınız:
  • İlgili haftanın gezinme geçmişinden hesaplanan, kullanıcının ilgisini gösteren bir konu.
    • Önemli bir ayrıntıdır: Bir kullanıcının Topics API'nin haftanın en önemli beş konusunu hesaplaması için yeterli sayıda konu gözlemlediyseniz Topics, toplam beş konuya ulaşmak için gereken sayıda rastgele konu ekler. API hakkında daha fazla bilgi edinin.
• Dört haftalık gözlemden sonra çağrıyorsanız üç başlıktan birinin yerine geçecek yeni bir konu girişi.
  • Bunun nedeni, Topics API'nin sonraki haftalar boyunca kararlı kalması ve kullanıcıların birçok ilgi alanını göz önünde bulundurmayacak olmasıdır. Daha fazla bilgiyi GitHub'da bulabilirsiniz.
• Kullanıcı için konuları üç haftadan uzun süredir gözlemlemezseniz Topics API tekrar boş bir [] dizisi döndürür.

Kullanıcı deneyiminizin performansını ve metriklerini ölçün.

• Kaynaklar arası iframe içinden Topics API'ye yapılan JavaScript çağrılarının çalışma süresi, gelecekteki performans analizinde kullanılmak üzere ölçülmelidir. Telemetri verilerini arka ucunuzda düzgün bir şekilde toplayıp depoladığınızdan emin olun.
  • Konular alındıktan sonra, iframe ve postMessage() konuları oluşturmak için harcanan süre de hesaplanabilecek diğer bir metriktir.

Sorun giderme

Topics API'yi çağırıyorum ancak sonuç olarak null (null) mesajı alıyorum. Ne yapabilirim?

Topics API'yi bir kullanıcıyı gözlemlemenizin ardından ilk hafta içinde çağırıyorsanız bu beklenen bir durumdur.

Temel öneriler

1. JavaScript'inizin beklendiği gibi çalıştığından emin olmak için kullanıcı arabirimi kodunuzu test edin.

2. Konu sonuçlarını almak için arka ucunuzu test edin.

   1. Veri türlerinin ve arka uç API parametrelerinin doğru şekilde yapılandırıldığından emin olun.
   2. Arka ucunuzun uygun şekilde ölçeklendirilecek şekilde yapılandırıldığından emin olun.

3. Deneyimlerimize göre, daha alakalı konularla ilgili sonuçlar almaya başlamak için en az üç hafta beklemelisiniz.

4. Konular tüm kullanıcılarda etkin olmayacaktır:

   1. Kullanıcılar Topics API'yi açıkça devre dışı bırakabilir.
   2. Yayıncının sayfaları, izin politikasını kontrol edebilir. Topics API geliştirici kılavuzundaki (kapsam dışında kalma) konusuna bakın.
   3. Daha ayrıntılı bilgi için chromestatus.com adresini kontrol edin.

5. Bu ortama metrikler ve gözlemlenebilirlik ekleyin: İlk sonuçları analiz etmek için bunlara ihtiyacınız olacaktır. Örnek metrikler şunlardır:

   1. Aramaların gecikmesi;
   2. Topic çağrılarındaki HTTP hataları;

6. İlk üç hafta boyunca uygulamanızda yapılacak değişiklikleri sınırlamaya çalışın.

Üretime göre ölçeklendir

Üretime nasıl ölçeklendirme yapabileceğinizle ilgili adım adım açıklamaları burada bulabilirsiniz. İlgili adımlar aşağıda açıklanmıştır.

1. Uygulamayı (üretim) ölçeklendirin Bu işlem aşağıda açıklanmıştır.
   1. iframe'i birden fazla yayıncının web sitesine ekleyin.
2. Konu verilerini işleme ve kullanma (Tahmini süre: Yaklaşık 4 hafta).
   1. Konu verilerini, diğer verilerle birlikte ek bir sinyal olarak dahil edin.
   2. Gerçek zamanlı teklif verme test iş ortakları kaynak.
   3. Diğer verilerinize ek sinyal olarak konular içeren yardımcı program testi çalıştırın.

Uygulamanızı ölçeklendirme

Bu noktada, bazı sitelerden kontrollü bir ortamda konu verileri toplanıyor ve çözümün tamamına daha yüksek bir güven düzeyi sunuluyor.

Şimdi sıra, aynı kodu daha fazla hedef web sitesine dağıtarak bu uygulamayı ölçeklendirmeye geldi. Bu sayede daha fazla kullanıcıyı gözlemleyebilir, daha fazla konu verisi toplayabilir ve kitlelerinizi daha iyi anlayabilirsiniz.

Aşağıdakileri yapmanızı öneririz:

1. Özellikle büyük hacimde trafiğiniz varsa sitelerinize kademeli olarak dağıtın.
2. Beklenen trafiğinize göre konu verileriniz için yük testi yapın.
   1. Arka ucunuzun çok sayıda aramayla başa çıkabildiğinden emin olun.
   2. Analiz için metrik toplamayı ve günlükleri ayarlayın.
3. Topics API'yi dağıttıktan hemen sonra son kullanıcı sorunlarını tespit etmek için metriklerinizi kontrol edin. Metriklerinizi düzenli olarak kontrol etmeye devam edin.
4. Kesinti veya beklenmeyen bir davranış durumunda, sorunu anlayıp düzeltmek için dağıtımı geri alın ve günlüklerinizi analiz edin.

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.