Protected Audience API: geliştirici kılavuzu

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

Protected Audience API'yi kullanmaya yeni 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 iterasyonu için teknik referans olması amacıyla geliştiriciler için hazırlanmıştır. Temel 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, üçüncü tarafların sitelerdeki kullanıcı tarama davranışını izlemek üzere kullanılamaması amacıyla, yeniden pazarlama ve özel kitlelere yönelik kullanım alanları sunmak için 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ırmalar yapılmasını sağlar.

Protected Audience API, Chromium'da TURTLEDOVE teklif ailesi içinde 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 genelinde temel Protected Audience API dağıtımının adım adım açıklamalı kılavuzu sandbox-demo.web.app/ adresinde bulunabilir.

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 için bu uçtan uca dağıtımı izleyin.

Bu API'yi test et

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

iframe'ler veya korumalı çerçeveler içinde reklam oluşturun

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

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

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

Reklamları oluşturmak üzere <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 bayraklarının arkasındaki Protected Audience API, Protected Audience API'nin aşağıdaki özelliklerini test eden ilk denemedir:

  • İlgi alanı grupları: Reklam teklif vermeyi ve oluşturmayı yapılandırmak için ilişkili meta verilerle birlikte tarayıcı tarafından depolanır.
  • Alıcıların (TTP veya reklamveren) cihaz üzerinde teklif verme: Depolanan ilgi alanı gruplarına ve satıcıdan gelen sinyallere dayanır.
  • Satıcı (STP veya yayıncı) tarafından cihaz üzerinde reklam seçimi: açık artırma tekliflerine ve alıcılardan gelen meta verilere dayanır.
  • Kısıtlanmış Çerçeveler'in 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çıklaması bölümünden özellik desteği ve kısıtlamalar hakkında daha fazla bilgi edinebilirsiniz.

İlgi alanı grubu izinleri

Protected Audience API'nin mevcut uygulaması için varsayılan, alanlar arası iframe'ler de dahil olmak üzere bir sayfanın herhangi bir yerinden joinAdInterestGroup() çağrısına izin verilmesidir.

Gelecekte, site sahipleri web alanları arası iframe izin politikalarını güncellediğinde, alanlar arası iframe'lerden gelen çağrılara izin verilmez.

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 amacıyla bir anahtar/değer hizmetine erişebilir. 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 hizmet kodu artık kullanılabilir. Durum güncellemesi için duyuru blog yayınına göz atın.

İlk test için "Kendi Sunucunuzu Getirin" modeli sunuldu. Uzun vadede, reklam teknisyenlerinin güvenilir yürütme ortamlarında çalışan açık kaynaklı Protected Audience API Anahtar/Değer Hizmetleri hizmetlerini kullanması gerekecektir.

Zaman çizelgesi güncellemeleri için Protected Audience API hizmetleri blog yayınına bakın. Bu geçiş gerçekleşmeden önce geliştiricilerin testlere ve uygulamaya başlamaları için önemli bir bildirim göndereceğiz.

Özellik desteğini algıla

API'yi kullanmadan önce, API'nin tarayıcı tarafından desteklenip desteklenmediğini ve belgede bulunup bulunmadığı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, bir kullanıcı özel bir bisiklet üreticisinin web sitesine göz atar, ardından bir haber web sitesini ziyaret eder ve bisiklet üreticisine ait yeni bir bisikletin reklamını gösterir.

Uygulama çalışmaları ilerledikçe Protected Audience API özellikleri zamanla eklenecektir.

1. Kullanıcı bir reklamveren sitesini ziyaret eder

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

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

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

Dizüstü bilgisayarında bir tarayıcı açıp bir siteyi ziyaret eden bir kullanıcı. 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 üyesi olduğu grupların listesine bir ilgi alanı grubu eklemesini istemek için navigator.joinAdInterestGroup() kodunu çağırır.

Bu örnekte, grup custom-bikes, sahibi ise dsp.example olarak adlandırılmıştır. İlgi alanı grubu sahibi (bu durumda TTP), Protected Audience API reklam açık artırmasında alıcı olur. İlgi alanı grubu üyeliği tarayıcı tarafından ve kullanıcının cihazında depolanır ve tarayıcının sağlayıcısıyla ya da başka biriyle paylaşılmaz.

Bir ilgi alanı grubuna ilişkin reklamları belirtme

ads ve adComponents nesneleri, bir reklam öğesi için URL 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?

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

generatedBid() geliştirici belgelerini okuyun.

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

Bir kullanıcı, 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 (bu örnekte bir haber web sitesi) ziyaret eder. Sitede, gerçek zamanlı teklif verme ile programatik olarak sattığı reklam envanteri vardır.

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

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

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ülecektir. Açık artırmanın amacı, geçerli sayfadaki tek bir kullanılabilir reklam alanı için en uygun reklamı seçmektir. Açık artırma, tarayıcının üyesi olduğu ilgi alanı gruplarının yanı sıra Anahtar/Değer hizmetlerinden gelen reklam alanı alıcılarına ve satıcılarına ait verileri de dikkate alır.

5. Satıcı ve katılımcı alıcılar, Key/Value hizmetinden gerçek zamanlı 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 yapılan bir reklam açık artırmasında bir katılımcı Key/Value hizmetinden veri alıyor.

Reklam açık artırması sırasında satıcı, Anahtar/Değer Hizmeti'ne istek göndererek belirli reklam öğeleri hakkında gerçek zamanlı veriler isteyebilir. Satıcı, açık artırmadaki tüm ilgi alanı gruplarının ads ve adComponents alanlarındaki tüm girişlerin renderUrl mülklerindeki anahtarlarla birlikte, trustedScoringSignalsUrl mülkü runAdAuction() içinde bu bilgileri isteyebilir.

Alıcı, navigator.joinAdInterestGroup() öğesine iletilen 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 bir istek gönderir. İsteğin URL'si şu şekilde görünebilir:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • Temel URL, trustedBiddingSignalsUrl kaynağından gelir.
  • hostname, tarayıcı tarafından sağlanır.
  • keys değeri, trustedBiddingSignalsKeys parametresinden 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österilir

Dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini görüntüleyen bir kişi. Güvenli bir çitle çevrili çerçevede, 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 söz, özel çerçeve yapılandırma nesnesine (FencedFrameConfig) çö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 çerçeve yerleştirmeci, reklamın URL'sini göremez.

Çitli çerçeve yapılandırma nesnesi, M114'ten itibaren kullanılabilir. FencedFrameConfig nesnesi hakkında daha fazla bilgi için Chrome blog makalesini inceleyin.

7. Açık artırma sonucu raporlanır

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ı bildirmesine izin vermektir.

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

8. Bir reklam tıklaması raporlanır

Bir kullanıcı, bir haber web sitesinde, çitle çevrili çerçeveye 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. Bunun nasıl olabileceği hakkında daha fazla bilgi edinmek için Kısıtlanmış Çerçevelerle Reklam Raporu'na bakın.

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, Chromium'da TURTLEDOVE teklif ailesi içinde uygulanan ilk denemedir.

Protected Audience API, TURTLEDOVE'un üst düzey ilkelerine uyar. Bazı çevrimiçi reklamcılık faaliyetlerinde, bir reklamın, daha önce reklamverenle veya reklam ağıyla etkileşimde bulunmuş, potansiyel olarak ilgili bir kişiye gösterilmesi temel alınmıştır. Geçmişte bu özellik, günümüzün web dünyasının temel gizlilik sorunu olan web sitelerinde gezinen belirli bir kişiyi tanıyarak reklamveren tarafından işe yaramıştır.

TURTLEDOVE'un çalışmaları, bu kullanım alanına yönelik yeni bir API ve gizlilikle ilgili bazı önemli ilerlemeleri sunmakla ilgili:

  • Reklamverenin, kullanıcının ilgilendiğini düşündüğü şeylerle ilgili bilgiler reklamveren değil, tarayıcı tarafından tutulur.
  • Reklamverenler bir ilgi alanına dayalı reklamlar yayınlayabilir, ancak bu ilgi alanını bir kullanıcı hakkındaki diğer bilgilerle, özellikle de o kişinin kim olduğu veya hangi sayfayı ziyaret ettiğiyle birleştiremez.

Protected Audience API, TURTLEDOVE'tan ve API'yi kullanacak geliştiricilere daha iyi hizmet verebilmek için bir dizi ilgili değişiklik teklifinden geliştirildi:

  • 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 kullanımını içerir.
  • NextRoll'un TERN ve Magnite'ın PARRROT teklifleri, alıcıların ve satıcıların cihaz üzerinde açık artırmadaki farklı rollerini açıkladı. Protected Audience API'nin reklam teklif verme/puanlama akışı bu çalışmaya dayalıdır.
  • RTB House Sonuca dayalı ve Ürün düzeyinde TURTLEDOVE değişiklikleri, anonimlik modelini ve cihaz üzerinde açık artırmanın kişiselleştirme özelliklerini iyileştirdi
  • PARAKEET, reklam isteklerini anonimleştirmek ve gizlilik özelliklerini uygulamak için Microsoft'un, tarayıcı ve reklam teknolojisi sağlayıcılar arasında bir TEE'de çalışan proxy sunucusuna dayanan TURTLEDOVE benzeri bir reklam hizmetine yönelik teklifidir. Protected Audience API bu proxy modelini benimsemedi. PARAKEET için JavaScript API'lerini ve Protected Audience API'yi uyumlu hâle getiriyoruz. Böylece, her iki teklifin en iyi özelliklerini daha da birleştirmeye yönelik gelecekte yapılacak çalışmaları destekliyoruz.

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

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

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

  • auctionSignals, navigator.runAdAuction() hedefine iletilen açık artırma yapılandırma nesnesinin bir mülkü
  • userBiddingSignals, navigator.joinAdInterestGroup() hedefine iletilen ilgi alanı 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 Chrome'daki Özel Korumalı Alan denemelerine katılımlarını ayarlayabilirler.

İlk test sırasında kullanıcılar, Protected Audience API'nin kapsamı dışında kalmak 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 planlamaktadır. Özel Korumalı Alan teknolojilerinin kendisinde olduğu gibi, kullanıcı ayarları da kullanıcılardan, düzenleyici kurumlardan ve diğer kişilerden gelen geri bildirimlerle değişebilir.

Testlere ve geri bildirimlere dayanarak Chrome'da kullanılabilen ayarları 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.

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

Protected Audience iş programları tarayıcı tarafından önbelleğe alınıyor mu?

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

Etkileşimde bulunun ve geri bildirim paylaşın

Destek alın

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

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

Geri bildiriminizi 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