Protected Audience API: geliştirici kılavuzu

Siteler arası üçüncü taraf izleme olmadan yeniden pazarlama ve özel kitlelere reklam yayınlamak için cihaz üzerinde reklam açık artırmalarıyla ilgili geliştirici kılavuzu.

Protected Audience API'yi yeni kullanmaya başlayanlar, API hakkında genel bir açıklama için Protected Audience API'ye genel bakış başlıklı makaleyi inceleyebilir.

Bu gönderi, deneysel Protected Audience API'nin en son yinelemesi için teknik referans olarak geliştiriciler için yazılmıştır. Temel bir Protected Audience API dağıtımının demosu ile reklam alıcıları ve satıcıları için API referansları mevcuttur.

Uygulama durumu

API'deki durum değişikliklerinden haberdar olmak için geliştiricilere yönelik posta listesine katılın.

Protected Audience API nedir?

Protected Audience API, Özel Korumalı Alan API'sidir. Yeniden pazarlama ve özel kitle kullanım alanlarına hizmet vermek için tasarlanmıştır. Üçüncü tarafların, kullanıcıların sitelerdeki göz atma davranışlarını izlemek için kullanamayacağı şekilde tasarlanmıştır. API, kullanıcının daha önce ziyaret ettiği web siteleri için alakalı reklamları seçmek üzere tarayıcı tarafından cihaz üzerinde açık artırmalar yapılmasını sağlar.

Protected Audience API, TURTLEDOVE teklif ailesinde Chromium'da uygulanan ilk denemedir.

Protected Audience API'yi deneme

Kullanılabilir API referansı

Bu belge, Protected Audience API'ye genel bakış niteliğindedir. Belirli API yöntemlerini ve parametrelerini arıyorsanız:

Protected Audience API reklam açık artırması gecikmesiyle ilgili en iyi uygulamalar başlıklı makaleyi de okuyabilirsiniz.

Protected Audience API tanıtımı

Reklamveren ve yayıncı sitelerinde temel bir Protected Audience API dağıtımının adım adım açıklaması protected-audience-demo.web.app/ adresinde mevcuttur.

Protected Audience API demo kodunun nasıl çalıştığını ve hataları ayıklamak için Chrome Geliştirici Araçları'nı nasıl kullanacağınızı öğrenmek için bu uçtan uca dağıtımı izleyin.

Bu API'yi test etme

Protected Audience API'yi masaüstünde Chrome Beta 101.0.4951.26 ve sonraki sürümlerde tek bir kullanıcı için test edebilirsiniz:

Reklamları iframe'lerde veya sınırlı çerçevelerde oluşturma

Reklamlar, hangi işaretlerin ayarlandığına bağlı olarak <iframe> veya <fencedframe> olarak oluşturulabilir.

Reklamları oluşturmak için <fencedframe> ayarını kullanmak üzere:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Reklamları oluşturmak için <iframe> ayarını kullanmak üzere:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

BiddingAndScoringDebugReportingAPI işaretini ekleyerek geçici hata ayıklama kaybı/kazanma raporlama yöntemlerini etkinleştirin.

Desteklenen özellikler

Chromium'daki özellik işaretlerinin arkasında bulunan Protected Audience API, Protected Audience API'nin aşağıdaki özelliklerini test etmek için yapılan ilk denemedir:

  • İlgi alanı grupları: Reklam teklifi ve oluşturma işlemlerini yapılandırmak için ilişkili meta verilerle birlikte tarayıcı tarafından depolanır.
  • Alıcılar (TTP veya reklamveren) tarafından cihaz üzerinde teklif verme: Satıcıdan gelen sinyaller ve depolanmış ilgi alanları gruplarına göre.
  • Satıcı (STP veya yayıncı) tarafından cihaz üzerinde reklam seçimi: Alıcılardan gelen açık artırma tekliflerine ve meta verilere dayalıdır.
  • Sınırlı çerçevelerin geçici olarak rahatlatılmış bir sürümünde reklam oluşturma: Reklam oluşturma için ağ erişimine ve günlük kaydına izin verilir.

Özellik desteği ve kısıtlamalar hakkında daha fazla bilgiyi Protected Audience API açıklayıcısında bulabilirsiniz.

İlgi grubu izinleri

Protected Audience API'nin mevcut uygulamasında varsayılan olarak, bir sayfadaki herhangi bir yerden, hatta alanlar arası iframe'lerden joinAdInterestGroup() çağrılmasına izin verilir.

Gelecekte, site sahiplerinin alanlar arası iframe izin politikalarını güncellemesi için yeterli zaman verildikten sonra, alanlar arası iframe'lerden gelen çağrıların engellenmesi planlanmaktadır.

Key/Value hizmeti

Tarayıcı, Protected Audience API reklam açık artırmasını desteklemek için Protected Audience API reklam açık artırmasını destekleyen gerçek zamanlı bilgileri almak üzere bir anahtar/değer hizmetine erişebilir. Bu bilgiler çeşitli şekillerde kullanılabilir:

  • Alıcılar, bir reklam kampanyasındaki kalan bütçeyi hesaplamak isteyebilir.
  • Satıcıların, reklam öğelerini yayıncı politikalarına göre kontrol etmesi gerekebilir.

Protected Audience API anahtar/değer hizmeti kodu artık kullanılabilir. Durum güncellemesi için duyuru blog yayınına göz atın.

İlk test için "Kendi Sunucunu Getir" modeli kullanıma sunuldu. Uzun vadede reklam teknolojisi sağlayıcıların, güvenilir yürütme ortamlarında çalışan açık kaynaklı Protected Audience API Anahtarı/Değer hizmetlerini kullanması gerekecek.

Zaman çizelgesi güncellemeleri için Protected Audience API hizmetleri blog yayınını inceleyin. Bu geçiş gerçekleşmeden önce geliştiricilerin test etmeye ve kullanmaya başlaması için önemli bir bildirimde bulunacağız.

Özellik desteğini algılama

API'yi kullanmadan önce tarayıcı tarafından desteklenip desteklenmediğini ve dokümanda kullanılabilir olup olmadığını kontrol edin:

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Protected Audience API nasıl çalışır?

Bu örnekte, kullanıcı özel bisiklet üreticisinin web sitesine göz atar, daha sonra bir haber web sitesini ziyaret eder ve bisiklet üreticisinin yeni bir bisikletinin reklamı gösterilir.

Protected Audience API'nin özellikleri, uygulama çalışmaları ilerledikçe zaman içinde eklenecektir.

1. Bir kullanıcı, reklamveren sitesini ziyaret eder.

Dizüstü bilgisayarındaki tarayıcıda özel bisiklet üreticisi sitesini ziyaret eden bir kişi.

Örneğin, bir kullanıcının özel bisiklet üreticisinin (bu örnekte reklamveren) web sitesini ziyaret ettiğini ve el yapımı çelik bisikletin ürün sayfasında biraz zaman geçirdiğini düşünelim. Bu sayede bisiklet üreticisi, yeniden pazarlama fırsatı elde eder.

2. Kullanıcının tarayıcısından bir ilgi grubu eklemesi istenir.

Bir kullanıcı dizüstü bilgisayarında tarayıcı açıp bir siteyi ziyaret eder. Reklam ilgi alanı gruplarına katılmak için kullanılan JavaScript kodu tarayıcıda çalışıyor.

Reklamverenin talep tarafı platformu (TTP) (veya reklamveren kendisi), tarayıcıdan tarayıcının üyesi olduğu gruplar listesine bir ilgi alanı grubu eklemesini istemek için navigator.joinAdInterestGroup() çağrısı yapar.

Bu örnekte, grubun adı custom-bikes, sahibi ise dsp.example'dir. İlgi alanı grubu sahibi (bu durumda DSP), Protected Audience API reklam açık artırmasında alıcı olur. İlgi grubu üyeliği, tarayıcı tarafından kullanıcının cihazında saklanır ve tarayıcı tedarikçisiyle ya da başka biriyle paylaşılmaz.

Bir ilgi alanı grubu için reklam belirtme

ads ve adComponents nesneleri, bir reklam öğesinin URL'sini ve isteğe bağlı olarak teklif verme sırasında kullanılabilecek rastgele meta verileri içerir. Örneğin:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

Alıcılar nasıl teklif verir?

Tarayıcının üyesi olduğu her ilgi alanı grubu için generateBid() çağrılır (ilgi alanı grubunun sahibi teklif vermeye davet edildiyse).

generatedBid() geliştirici belgelerini okuyun.

3. Kullanıcı, reklam alanı satan bir siteyi ziyaret eder.

Bir kişi, dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini ziyaret ediyor. Sitede boş bir reklam alanı var.

Daha sonra kullanıcı, reklam alanı satan bir siteyi (bu örnekte bir haber web sitesi) ziyaret eder. Sitede, gerçek zamanlı teklif verme ile programatik olarak satılan reklam envanteri vardır.

4. Tarayıcıda bir reklam açık artırması çalıştırılır.

Dizüstü bilgisayarının tarayıcısında bir haber web sitesini görüntüleyen kişi. Mevcut reklam alanı için bir reklam seçmek üzere Protected Audience API reklam açık artırması yapılır.

Reklam açık artırması büyük olasılıkla yayıncının arz tarafı sağlayıcısı (SSP) veya yayıncının kendisi tarafından yürütülür. Açık artırmanın amacı, mevcut sayfadaki tek bir kullanılabilir reklam alanı için en uygun reklamı seçmektir. Açık artırmada, tarayıcının üyesi olduğu ilgi alanları gruplarının yanı sıra reklam alanı alıcılarından ve anahtar/değer hizmetlerindeki satıcılardan gelen veriler dikkate alınır.

5. Satıcı ve katılan alıcılar, anahtar/değer hizmetinden anlık veriler ister.

Kullanıcı, dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini görüntülüyor. Protected Audience API kullanılarak bir reklam açık artırması gerçekleştiriliyor ve bir katılımcı, anahtar/değer hizmetinden veri alıyor.

Reklam açık artırması sırasında satıcı, anahtar/değer hizmetine istek göndererek belirli reklam öğeleri hakkında gerçek zamanlı veriler isteyebilir. Satıcı, runAdAuction() sırasında trustedScoringSignalsUrl mülkü tarafından bu bilgileri, açık artırmadaki tüm ilgi alanı gruplarının ads ve adComponents alanlarındaki tüm girişlerin renderUrl mülklerinden alınan anahtarlarla birlikte isteyebilir.

Bir alıcı, trustedBiddingSignalsUrl ve trustedBiddingSignalsKeys özelliklerini kullanarak navigator.joinAdInterestGroup()'ye iletilen ilgi alanı grubu bağımsız değişkeninden gerçek zamanlı veri isteyebilir.

runAdAuction() çağrıldığında tarayıcı, her reklam alıcının güvenilir sunucusuna bir istek gönderir. İsteğin URL'si aşağıdaki gibi görünebilir:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • Temel URL, trustedBiddingSignalsUrl kaynağından alınır.
  • hostname, tarayıcı tarafından sağlanır.
  • keys değeri trustedBiddingSignalsKeys kaynağından alınır.

Bu isteğe verilen yanıt, her anahtarın değerlerini sağlayan bir JSON nesnesidir.

6. Kazanan reklam gösterilir.

Dizüstü bilgisayarının tarayıcısında bir haber web sitesini görüntüleyen kişi. Bisiklette% 20 indirim reklamı güvenli bir sınırlı alanda gösteriliyor.

runAdAuction() tarafından döndürülen söz, açık artırma yapılandırmasında resolveToConfig işareti true olarak ayarlandığında bir sınırlanmış çerçeve yapılandırma nesnesi (FencedFrameConfig) olarak çözümlenir. Çerçeve yapılandırması, çerçeveyi kazanan reklama yönlendirmek için sınırlı çerçeve tarafından kullanılır ancak reklamın URL'si çerçeve yerleştirici tarafından görülemez.

Fenced frame yapılandırma nesnesi, M114 sürümünden itibaren kullanılabilir. FencedFrameConfig nesnesi hakkında daha fazla bilgi için Chrome blog makalesine bakın.

7. Açık artırma sonucu bildirilir.

Uzun vadeli plan, tarayıcının Private Aggregation API'lerini kullanarak satıcı ve alıcılar için açık artırma sonuçlarını bildirmesine izin vermektir.

Geçici bir etkinlik düzeyinde raporlama mekanizması olarak, satıcı için reportResult() ve kazanan teklif sahibi için reportWin() uygulayan kod, sendReportTo() işlevini çağırabilir. Bu işlev tek bir bağımsız değişken alır: açık artırma tamamlandıktan sonra getirilen ve raporlanacak etkinlik düzeyindeki bilgileri kodlayan bir URL'yi temsil eden dize.

8. Bir reklam tıklaması bildirilir

Bir kullanıcı, haber web sitesinde çitli çerçeveyle yerleştirilmiş bir bisiklet reklamını tıklıyor. Rapor verileri satıcıya ve alıcılara gönderilir.

Çitli çerçevede oluşturulan bir reklamın tıklanması raporlanır. Bu özelliğin işleyiş şekli hakkında daha fazla bilgi edinmek için Fenced Frames Ads Reporting başlıklı makaleyi inceleyin.

Protected Audience API reklam açık artırmasının her aşamasına genel bakış
Bu şemada, Protected Audience API açık artırmasının her aşaması özetlenmektedir.

Protected Audience API ile TURTLEDOVE arasındaki fark nedir?

Protected Audience API, TURTLEDOVE teklif ailesinde Chromium'da uygulanan ilk denemedir.

Protected Audience API, TURTLEDOVE'un üst düzey ilkelerini izler. Bazı online reklamcılık, daha önce reklamveren veya reklam ağıyla etkileşimde bulunmuş ve potansiyel olarak ilgilenebilecek bir kişiye reklam göstermeye dayanır. Geçmişte bu, reklamverenin web sitelerinde gezinirken belirli bir kişiyi tanımasıyla çalışıyordu. Bu durum, günümüz web'inde temel bir gizlilik sorunudur.

TURTLEDOVE, bu kullanım alanını ele almak için yeni bir API sunmayı ve aynı zamanda gizlilikle ilgili bazı önemli gelişmeler sağlamayı amaçlar:

  • Reklamverenin, kullanıcının ilgilendiğini düşündüğü konularla ilgili bilgiler reklamverende değil, tarayıcıda bulunur.
  • Reklamverenler, bir ilgi alanına dayalı olarak reklam yayınlayabilir ancak bu ilgi alanını bir kişiyle ilgili diğer bilgilerle (özellikle kim olduğu veya hangi sayfayı ziyaret ettiği) birleştiremez.

Protected Audience API, TURTLEDOVE ve API'yi kullanacak geliştiricilere daha iyi hizmet vermek için yapılan değişikliklerle ilgili bir dizi tekliften doğmuştur:

  • SPARROW'da: Criteo, güvenilir yürütme ortamında (TEE) çalışan bir ("Gatekeeper") hizmet modeli eklenmesini önerdi. Protected Audience API, gerçek zamanlı veri araması ve toplu raporlama için TEE'lerin daha sınırlı bir kullanımını içerir.
  • NextRoll'un TERN ve Magnite'ın PARRROT teklifleri, cihaz üzerinde açık artırmada alıcıların ve satıcıların farklı rollerini tanımlıyordu. Protected Audience API'nin reklam teklifi/puanlama akışı bu çalışmaya dayanmaktadır.
  • RTB House'un sonuca dayalı ve ürün düzeyinde TURTLEDOVE değişiklikleri, cihaz üzerinde açık artırmanın anonimlik modelini ve kişiselleştirme özelliklerini iyileştirdi.
  • PARAKEET, reklam isteklerini anonimleştirmek ve gizlilik özelliklerini zorunlu kılmak için tarayıcı ile reklam teknolojisi sağlayıcılar arasında TEE'de çalışan bir proxy sunucusuna dayanan, TURTLEDOVE benzeri bir reklam hizmeti için Microsoft'un önerisidir. Protected Audience API bu proxy oluşturma modelini benimsememiştir. PARAKEET ve Protected Audience API'nin JavaScript API'lerini, her iki teklifin en iyi özelliklerini daha da birleştirmek için gelecekte yapılacak çalışmaları desteklemek amacıyla uyumlu hale getiriyoruz.

Protected Audience API, bir web sitesinin reklam ağının, bir kişinin hangi reklamları gördüğünü öğrenmesini henüz engellememektedir. API'yi zaman içinde daha gizli olacak şekilde değiştirmeyi planlıyoruz.

Topics API, Protected Audience API ile kullanılabilir mi?

Evet. Topics API tarafından sağlanan, mevcut kullanıcı için gözlemlenen bir konu, satıcı veya teklif veren tarafından bağlamsal bilgi olarak kullanılabilir. Bir konu aşağıdaki özelliklere dahil edilebilir:

  • auctionSignals, navigator.runAdAuction() yöntemine iletilen açık artırma yapılandırma nesnesinin bir özelliği
  • userBiddingSignals, navigator.joinAdInterestGroup()'ye iletilen ilgi alanı grubu yapılandırma nesnesinin bir özelliği

Kullanılabilir tarayıcı yapılandırması

Kullanıcılar, Chrome'daki Özel Korumalı Alan denemelerine katılımlarını chrome://settings/adPrivacy üst düzey ayarını etkinleştirerek veya devre dışı bırakarak düzenleyebilir.

İlk testler sırasında kullanıcılar, Protected Audience API'yi devre dışı bırakmak için bu üst düzey Özel Korumalı Alan ayarını kullanabilecek. Chrome, kullanıcıların ziyaret ettikleri web sitelerinde eklendikleri ilgi alanı gruplarının listesini görmesine ve yönetmesine izin vermeyi planlıyor. Özel Korumalı Alan teknolojilerinde olduğu gibi, kullanıcı ayarları da kullanıcılardan, düzenleyicilerden ve diğer taraflardan gelen geri bildirimlerle gelişebilir.

Chrome'daki mevcut ayarları testlere ve geri bildirimlere göre güncellemeye devam edeceğiz. İleride Protected Audience API'yi ve ilişkili verileri yönetmek için daha ayrıntılı ayarlar sunmayı planlıyoruz.

Kullanıcılar Gizli modda gezinirken API çağıranlar grup üyeliğine erişemez ve kullanıcılar site verilerini temizlediğinde üyelik kaldırılır.

Protected Audience iş parçacıkları tarayıcı tarafından önbelleğe alınır mı?

Protected Audience işlevletlerini içeren kaynaklar (alıcının teklif oluşturma ve raporlama işlevletleri ile satıcının reklam puanlama ve raporlama işlevletleri) tarayıcı tarafından önbelleğe alınır. Önbelleğe alma davranışını kontrol etmek için Cache-Control başlığını kullanabilirsiniz.

Etkileşim kurma ve geri bildirim paylaşma

Destek alın

Uygulamanız, demo veya dokümanlarla ilgili soru sormak ve destek almak için:

Protected Audience API ile ihtiyaçlarınızı karşılama hakkında daha genel sorularınız için API deposunda sorun bildirin. Sektördeki kullanım alanlarını W3C'nin Web Reklamcılığını Geliştirme İş Grubu'nda da tartışabilirsiniz.

Herkese açık forumlar dışında Chrome ekibiyle gizli geri bildirim paylaşmak için Özel Korumalı Alan geri bildirim formunu kullanın.

Devre dışı bırakma

Protected Audience API'nin kapsamı dışında kalmak mı istiyorsunuz? Site sahibi veya bireysel kullanıcı olarak Protected Audience API'ye erişimi engellemeyi öğrenin.

Güncellemeleri al