Protected Audience API: geliştirici kılavuzu

Siteler arası üçüncü taraf izleme olmadan yeniden pazarlama ve özel kitleler yayınlamaya yönelik cihaz üzerinde reklam açık artırmaları için geliştirici kılavuzu.

Protected Audience API'yi yeni kullanmaya başlayanlar için API'nin üst düzey açıklaması için Protected Audience API'ye genel bakış makalesini okuyun.

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

Uygulama durumu

API'deki durum değişiklikleriyle ilgili bildirim almak istiyorsanız geliştiricilere yönelik posta listesine katılın.

Protected Audience API nedir?

Protected Audience API, yeniden pazarlama ve özel kitle kullanım alanları sunmak üzere tasarlanmış bir Özel Korumalı Alan API'sidir. API, kullanıcının daha önce ziyaret ettiği web siteleri için alakalı reklamlar seçmek amacıyla, tarayıcı tarafından cihaz üzerinde açık artırmalara olanak tanır.

Protected Audience API, TURTLEDOVE teklif ailesi içinde Chromium'da uygulanacak ilk denemedir.

Protected Audience API'yi deneyin

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ırma gecikmesiyle ilgili en iyi uygulamaları da okuyabilirsiniz.

Protected Audience API demosu

Reklamveren ve yayıncı siteleri genelindeki temel Protected Audience API dağıtımıyla ilgili adım adım açıklamalı kılavuzu protection-audience-demo.web.app/ adresinde bulabilirsiniz.

Protected Audience API demo kodunun işleyiş şeklini ve hata ayıklama için Chrome Geliştirici Araçları'nı nasıl kullanacağınızı öğrenmek amacıyla bu uçtan uca dağıtımı izleyin.

chrome://flags veya özellik işaretleri ile test edin

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:

iframe'lerde veya sınırlanmış çerçevelerde reklam oluşturma

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

Reklamları görüntülemek amacıyla <fencedframe> kullanmak için:

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

Reklamları görüntülemek amacıyla <iframe> kullanmak için:

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

Geçici hata ayıklama kaybı/kazanma raporlama yöntemlerini etkinleştirmek için BiddingAndScoringDebugReportingAPI işaretini ekleyin.

Desteklenen özellikler

Chromium'daki özellik işaretlerinin arkasındaki Protected Audience API, Protected Audience API'nin aşağıdaki özelliklerini test eden ilk bir denemedir:

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

Protected Audience API açıklayıcıdan özellik desteği ve kısıtlamalar hakkında daha fazla bilgi edinin.

İlgi alanı grubu izinleri

Protected Audience API'nin geçerli uygulamasında varsayılan olarak, alanlar arası iframe'ler dahil olmak üzere bir sayfadaki herhangi bir yerden joinAdInterestGroup() çağrılmasına izin verilir.

Gelecekte, site sahipleri web alanları arası iframe izinler politikalarını güncellemeye zamanları olduğunda, alanlar arası iframe'lerden gelen çağrılara izin vermemeyi planlıyorlar.

Anahtar/Değer hizmeti

Tarayıcı, Protected Audience API reklam açık artırmasını desteklemek amacıyla bir anahtar/değer hizmetine erişerek Protected Audience API reklam açık artırmasını destekleyen gerçek zamanlı bilgileri alabilir. Bu bilgiler çeşitli şekillerde kullanılabilir:

  • Alıcılar, bir reklam kampanyasında 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 çifti hizmet kodu kullanıma sunuldu. Durum güncellemesi için duyuru blog yayınına göz atın.

Başlangıç testinde "Bring Your Own Server" (Kendi Sunucunuzu Getirin) modeli kullanıma sunuldu. Uzun vadede reklam teknisyenlerinin, güvenilir yürütme ortamlarında çalışan açık kaynaklı Protected Audience API Anahtar/Değer hizmetlerini kullanması gerekecektir.

Zaman çizelgesi güncellemeleri için Protected Audience API hizmetleri blog yayınına bakın. Geliştiricilere, bu geçiş gerçekleşmeden önce test etmeye ve kullanmaya başlamaları için önemli bir bildirim göndereceğiz.

Özellik desteğini algıla

API'yi kullanmadan önce, tarayıcı tarafından desteklenip desteklenmediğini ve dokümanda mevcut 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 bir bisiklet üreticisinin web sitesine göz atıyor, daha sonra bir haber web sitesini ziyaret ediyor ve bu bisiklet üreticisinin yeni bisikletinin reklamını görüyor.

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

1. Bir kullanıcı bir reklamverenin sitesini ziyaret eder

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

Bu örnekte, bir kullanıcının özel bir bisiklet üreticisinin (reklamveren) web sitesini ziyaret ettiğini ve el yapımı çelik bisikletin ürün sayfasında biraz zaman geçirdiğini düşünün. Bu durum, bisiklet üreticisine yeniden pazarlama fırsatı sunar.

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

Bir kullanıcı dizüstü bilgisayarında bir tarayıcı açar ve 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 reklamverenin kendisi), tarayıcının üye olduğu gruplar listesine bir ilgi alanı grubu eklemesini istemek için navigator.joinAdInterestGroup() yöntemini çağırır.

Bu örnekte, grubun adı custom-bikes, sahibi ise dsp.example'dir. İlgi alanı grubu sahibi (bu örnekte TTP), Protected Audience API reklam açık artırmasında bir alıcı olacaktır. İlgi grubu üyeliği tarayıcı tarafından, kullanıcının cihazında depolanır ve tarayıcının satıcısıyla veya başka biriyle paylaşılmaz.

Bir ilgi alanı grubu için reklam belirtme

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

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

Alıcılar nasıl teklif verir?

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

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ı vardır.

Daha sonra, kullanıcı reklam alanı satan bir siteyi ziyaret eder (bu örnekte bir haber web sitesi). Sitenin gerçek zamanlı teklif verme ile programatik olarak sattığı reklam envanteri bulunuyor.

4. Tarayıcıda bir reklam açık artırması yapılır.

Bir kişi, dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini görüntüler. Kullanılabilir reklam alanı için reklam seçmek üzere bir Protected Audience API reklam açık artırması gerçekleştirilir.

Reklam açık artırması muhtemelen yayıncının arz tarafı sağlayıcısı (STP) veya yayıncının kendisi tarafından yapı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 alanı gruplarının yanı sıra Anahtar/Değer Hizmetlerindeki reklam alanı alıcılarından ve satıcılarından alınan veriler de dikkate alınır.

5. Satıcı ve katılımcı alıcılar, Anahtar/Değer hizmetinden gerçek zamanlı veriler ister

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

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

Alıcı, navigator.joinAdInterestGroup() öğesine geçirilen ilgi alanı grubu bağımsız değişkeninin trustedBiddingSignalsUrl ve trustedBiddingSignalsKeys özelliklerini kullanarak Anahtar/Değer hizmetinden gerçek zamanlı veriler isteyebilir.

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

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

Bu isteğin yanıtı, anahtarların her biri için değer sağlayan bir JSON nesnesidir.

6. Kazanan reklam görüntülenir

Bir kişi, dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini görüntüler. Güvenli bir çitle çevrili çerçeve içinde, bisiklette% 20 indirim reklamı gösterilir.

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

Kısıtlanmış çerçeve yapılandırma nesnesi M114'ten itibaren kullanılabilir. FencedFrameConfig nesnesi hakkında daha fazla bilgi için Chrome blog makalesine bakın.

7. Açık artırma sonucu bildirildi

Uzun vadeli plan, tarayıcının Özel Toplama API'lerini kullanarak satıcı ve alıcılar için açık artırma sonuçlarını raporlamasına izin vermektir.

Etkinlik düzeyinde geçici bir raporlama mekanizması olarak, satıcı için reportResult() ve kazanan teklif veren için reportWin() uygulayan kod, sendReportTo() işlevini çağırabilir. Bu işlem için tek bir bağımsız değişken alını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ı bildirildi

Bir kullanıcı, haber web sitesinde çitle çevrili bir çerçeveye yerleştirilmiş bir bisiklet reklamını tıklar. Rapor verileri, satıcıya ve alıcılara gönderilir.

Kısıtlanmış çerçeve içinde oluşturulan bir reklamın tıklanması bildirilir. Bunun işleyiş şekli hakkında daha fazla bilgi edinmek için Fenced Frames Ads Reporting'i (Özel Çerçevelerle İlgili Reklam Raporları) inceleyin.

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

Protected Audience API ile TURTLEDOVE arasındaki fark nedir?

Protected Audience API, Chromium'da TURTLEDOVE teklif ailesi içinde uygulanacak ilk denemedir.

Protected Audience API, TURTLEDOVE'un üst düzey ilkelerine uyar. Bazı dijital reklamcılık etkinlikleri, daha önce reklamverenle veya reklam ağıyla etkileşime geçmiş, potansiyel olarak ilgi gösteren bir kişiye reklam göstermeye dayanmaktadır. Geçmişte bu, reklamverenlerin, günümüzün web'deki temel gizlilik sorunlarından biri olan ve web sitelerinde gezinirken belirli bir kişiyi tanıması şeklinde işe yaradı.

TURTLEDOVE, bu kullanım alanını ele almak için yeni bir API sunmanın yanı sıra gizlilikle ilgili bazı önemli ilerlemeler sunmayı amaçlıyor:

  • Reklamverenin bir kişinin ilgilendiğini düşündüğü şeylerle ilgili bilgileri reklamveren değil, tarayıcı içerir.
  • Reklamverenler bir ilgi alanına göre reklam yayınlayabilir, ancak bu ilgi alanını, bir kişi hakkındaki diğer bilgilerle, özellikle de bu kişinin kim olduğu veya hangi sayfayı ziyaret ettiğiyle birleştiremez.

Protected Audience API, TURTLEDOVE'dan ve API'yi kullanacak geliştiricilere daha iyi hizmet vermek için ilgili değişiklik tekliflerinden oluşan bir koleksiyondan oluşur:

  • SPARROW'da: Criteo, güvenilir yürütme ortamında (TEE) çalışan bir ("Gatekeeper") hizmet modelinin eklenmesini önerdi. Protected Audience API, gerçek zamanlı veri araması ve toplu raporlama için TEE'lerin daha sınırlı bir şekilde kullanılmasını sağlar.
  • NextRoll'un TERN ve Magnite'ın PARRROT teklifleri, cihaz üzerinde açık artırmada alıcıların ve satıcıların sahip olduğu farklı rolleri açıklıyordu. Protected Audience API'nin reklam teklif/puanlama akışı bu çalışmaya dayanı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 uygulamak için tarayıcı ile reklam teknolojisi sağlayıcılar arasındaki TEE'de çalışan bir proxy sunucusundan yararlanan TURTLEDOVE benzeri bir reklam hizmeti için Microsoft'un teklifidir. Protected Audience API bu proxy kullanma modelini kullanmadı. İlerideki çalışmaları desteklemek amacıyla, PARAKEET ve Protected Audience API için JavaScript API'lerini uyumlu hale getiriyoruz.

Protected Audience API, web sitelerinin reklam ağının kullanıcıların hangi reklamları gördüğünü henüz öğrenmesini engellemez. API'yi zaman içinde daha gizli hale gelecek şekilde değiştirmeyi umuyoruz.

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

Evet. Mevcut kullanıcı için Topics API tarafından sağlanan gözlemlenen bir konu, bir satıcı veya teklif veren tarafından içeriğe dayalı bilgi olarak kullanılabilir. Bir konu aşağıdaki özelliklerde eklenebilir:

  • auctionSignals, navigator.runAdAuction() adlı alıcıya iletilen açık artırma yapılandırma nesnesinin bir özelliği
  • userBiddingSignals, navigator.joinAdInterestGroup() işlevine geçirilen ilgi grubu yapılandırma nesnesinin bir özelliği

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

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

İlk test 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ı kullanabilir. Chrome, kullanıcıların ziyaret ettikleri web sitelerinde, eklendikleri ilgi alanı gruplarının listesini görmelerine ve yönetmelerine olanak tanımayı planlamaktadır. Özel Korumalı Alan teknolojilerinde olduğu gibi, kullanıcı ayarları da kullanıcılardan, düzenleyici kurumlardan ve diğer kuruluşlardan gelen geri bildirimlere göre değişebilir.

Chrome'daki mevcut ayarları testlere ve geri bildirimlere göre güncellemeye devam edeceğiz. Gelecekte 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 arayanları grup üyeliğine erişemez ve kullanıcılar site verilerini temizlediğinde üyelik kaldırılır.

Korunan Kitle iş akışları tarayıcı tarafından önbelleğe alınır mı?

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

Etkileşimde bulunun ve geri bildirim paylaşın

Destek alma

Uygulama, demo veya belgelerle ilgili soru sormak ve destek almak için:

Protected Audience API ile ihtiyaçlarınızı karşılama hakkında daha genel sorular 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.

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

Devre dışı bırakma

Protected Audience API'yi devre dışı bırakmak mı istiyorsunuz? Site sahibi veya bireysel kullanıcı olarak Protected Audience API'ye erişimi nasıl engelleyeceğinizi öğrenin.

Güncellemeleri al