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 yeni kullanmaya başlayanlar için Protected Audience API'ye genel bakış makalesini okuyun 'ni inceleyin.

Bu yayın, geliştiriciler için teknik referans olması amacıyla hazırlanmıştır. deneysel Protected Audience API'nin son yinelemesi. Bir temel demo Protected Audience API dağıtımı da Reklam alıcıları ve satıcıları için API referansları.

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, kullanıcılara en iyi deneyimi sunmak için tasarlanmış bir Özel Korumalı Alan API'sidir. yeniden pazarlama ve özel kitle kullanımı kullanıcı takibi için üçüncü taraflarca kullanılamayacak şekilde tasarlanmış ve web sitelerinde gezinme davranışını gösterir. API, cihaz üzerinde açık artırmaları kullanıcının daha önce ziyaret ettiği web siteleri için alakalı reklamları seçmek amacıyla tarayıcı.

Protected Audience API, TURTLEDOVE teklif ailesi.

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ı genelinde temel Protected Audience API dağıtımının adım adım açıklamalı kılavuzu sitelerini protected-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 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 Chrome Beta 101.0.4951.26 ve sonraki sürümlerde test edebilirsiniz. masaüstü:

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

Reklamlar <iframe> veya <fencedframe>, bağlı olarak emin olmanız gerekir.

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

Etkinleştirmek için BiddingAndScoringDebugReportingAPI işaretini ekleyin geçici hata ayıklama kaybı/kazanma raporlama yöntemleri.

Desteklenen özellikler

Chromium'daki özellik bayraklarının arkasındaki Protected Audience API, Protected Audience API'nin aşağıdaki özellikleri:

  • İlgi alanı grupları: Tarayıcı tarafından depolanır ve ilişkili meta verilerle birlikte Reklam teklifi ve oluşturmayı yapılandırın.
  • Alıcılar (TTP veya reklamveren) tarafından cihaz üzerinde teklif verme: Depolanan bilgilere göre Satıcıdan gelen ilgi alanı grupları ve sinyaller.
  • Satıcı (STP veya yayıncı) tarafından cihaz üzerinde reklam seçimi: açık artırma teklifleri ve meta veriler için geçerlidir.
  • Birleştirilmiş Çerçeveler'in geçici olarak rahatlatılmış bir sürümünde reklam oluşturma: Reklam oluşturmak için ağ erişimine ve günlük kaydına izin verildi.

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

İlgi alanı grubu izinleri

Protected Audience API'nin mevcut uygulaması için varsayılan, çağrıya joinAdInterestGroup() herhangi bir yerden, hatta alanlar arası iframe'lerden bile.

Gelecekte, site sahipleri web alanları arası ölçümlerini güncellemeye vakit iframe izin politikaları kullanıyorsanız, , alanlar arası iframe'lerden gelen çağrılara izin vermemektir.

Key/Value hizmeti

Tarayıcı, Protected Audience API reklam açık artırmasını desteklemek için anahtar/değer hizmeti Protected Audience API reklam açık artırmasını destekleyen gerçek zamanlı bilgileri almak için. Bu ç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 kullanıma hazır. Durum güncellemesi için duyuru blog yayınına göz atın.

İlk test için "Kendi Sunucunuzu Getirin" kullanıma sunuldu. Uzun vadede, reklam teknisyenlerinin güvenilir yürütmede çalışan açık kaynaklı Protected Audience API Anahtar/Değer Hizmetleri ortam olarak da bilinir.

Protected Audience API hizmetleri blog yayınını inceleyin takip edin. Geliştiricilerin uygulama içi işlem yapmaya başlamasına test edilmesi ve benimsenmesi gerekir.

Özellik desteğini algıla

API'yı kullanmadan önce, API'nin tarayıcı tarafından desteklenip desteklenmediğini kontrol edin. kullanın:

'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 atıyor ve ardından bir haber web sitesini ziyaret ettiğinde bisiklet üreticisine ait yeni bir bisikletin reklamını görür.

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 özel bir bisiklet üreticisinin (reklamveren) web sitesini ziyaret ettiğini düşünün ve el yapımı çelik bir ürün için ürün sayfasında biraz zaman geçiriyor. bisiklete biniyor. Bu, bisiklet üreticisine bir yeniden pazarlama fırsatı sunar.

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ı. JavaScript Reklam ilgi alanı gruplarına katılma kodu tarayıcıda çalışıyor.

Reklamverenin talep tarafı platformu (TTP) (veya reklamverenin kendisi) Tarayıcıdan bir ilgi alanı grubu eklemesini istemek için navigator.joinAdInterestGroup() adresini de ekler.

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

ziyaret edin.

Bir ilgi alanı grubuna ilişkin reklamları belirtme

ads ve adComponents nesneleri bir reklam öğesinin URL'sini içerir ve isteğe bağlı olarak, teklif verme sırasında kullanılabilecek rastgele meta veriler. Ö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 ilgi alanı grubu için çağrılır ilgi alanı grubunun sahibi teklif vermeye davet edilir.

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. Site boş bir reklam alanına sahip.

Daha sonra kullanıcı, reklam alanı satan bir siteyi ziyaret eder. Bu örnekte, haber amaçlı bir site web sitesi. Sitede, programatik olarak satılan reklam envanteri var. gerçek zamanlı teklif verme.

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ının, yayıncının arz tarafı sağlayıcısı tarafından gerçekleştirilmesi olasıdır. (STP) veya yayıncının kendisi. Açık artırmanın amacı, bahsi geçen geçerli sayfada tek bir reklam alanı için en uygun reklamı gösterir. İlgili içeriği oluşturmak için kullanılan açık artırma, tarayıcının üyesi olduğu ilgi alanı gruplarını ve ve son 30 gün içinde reklam alanı alıcılarından ve satıcılarından Anahtar/Değer hizmetleri.

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. Reklam Protected Audience API kullanılarak açık artırma gerçekleşiyor ve bir katılımcı, Key/Value hizmetinden veri alıyor.

Reklam açık artırması sırasında satıcı, belirli bir reklamla ilgili gerçek zamanlı veriler isteyebilir Anahtar/Değer hizmetine bir istekte bulunarak reklam öğelerini kullanabilir. Satıcı bu bilgileri trustedScoringSignalsUrl mülkü tarafından runAdAuction(), ads içindeki tüm girişlerin renderUrl özelliklerine ait anahtarlarla birlikte ve açık artırmadaki tüm ilgi alanı gruplarına ait adComponents alanları içerir.

Alıcı, aşağıdakileri kullanarak Anahtar/Değer Hizmeti'nden gerçek zamanlı veriler isteyebilir: trustedBiddingSignalsUrl ve trustedBiddingSignalsKeys özellikleri navigator.joinAdInterestGroup() öğesine iletilen ilgi grubu bağımsız değişkeni.

runAdAuction() çağrıldığında, tarayıcı her bir reklama istek gönderir güvenilir sunucusudur. İ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ı, her bir tuşlarını kullanın.

ziyaret edin.

6. Kazanan reklam gösterilir

Dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini görüntüleyen bir kişi. Reklam güvenli bir çerçevede 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 açık artırma sonuçlarını rapor etmesine izin vermektir. Özel Toplama API'lerini kullanan satıcılar ve alıcılar.

Etkinlik düzeyinde geçici bir bildirme mekanizması olarak, Satıcı için reportResult() ve kazanan teklif veren için reportWin() sendReportTo() işlevini çağırın. Bu işlem tek bir bağımsız değişken alır: açık artırma tamamlandıktan sonra getirilen bir URL'yi temsil eder. Bu URL, raporlanacak etkinlik düzeyindeki bilgiler.

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. Şu konu hakkında daha fazla bilgi edinmek için: Fenceed Frames Reklam Raporu bölümüne 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, TURTLEDOVE teklif ailesi.

Protected Audience API, TURTLEDOVE'un üst düzey ilkelerine uyar. Bazı çevrimiçi reklamcılık faaliyetlerinin potansiyel olarak ilgi gösteren bir kişiye reklam gösterilmesine dayalı olarak, Reklamveren veya reklam ağıyla daha önce etkileşimde bulunmuş olması gerekir. Geçmişte bu reklamverenin, arama yaptığı sırada belirli bir kişiyi tanıdığını günümüzdeki web'in gizlilikle ilgili temel endişelerinden biridir.

TURTLEDOVE girişimi, bu kullanım alanına yönelik yeni bir API sunmaktır. bazı önemli ilerlemeler de sunuyor:

  • Reklamverenin değil, tarayıcının ne hakkında bilgi içerdiği ilgilendiğini düşündüğü bir reklamverendir.
  • Reklamverenler bir ilgi alanına göre reklam yayınlayabilir ancak bunu bir arada kullanamaz bir kişi hakkındaki diğer bilgilere, özellikle de kullanıcının kime ait olduğunu bir kitle listesidir.

Protected Audience API, TURTLEDOVE'tan geliştirilmiştir ve geliştiricilere daha iyi hizmet verebilmek için yapılan en önemli değişiklikler:

  • SPARROW içinde: Criteo şunları önerdi: ("Gatekeeper") hizmet modelinin güvenilir yürütme ortamında (TEE) çalıştırılmasını sağlar. 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 albümü tekliflerde, alıcıların ve satıcıların satın alma sürecindeki cihaz üzerinde açık artırmadır. 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 kişiselleştirmeyi iyileştirdi cihaz üzerinde açık artırmanın özellikleri
  • PARAKEET: Microsoft'un proxy kullanan TURTLEDOVE benzeri bir reklam hizmeti teklifi web sunucusu ile reklam teknolojisi sağlayıcılar arasında bir TEE'de çalışan sunucu, reklam isteklerini anonimleştir ve gizliliği zorunlu kıl özellikler. Protected Audience API bu proxy modelini benimsemedi. Bugüne, PARAKEET için JavaScript API'lerini ve Protected Audience API'yi uyumlu hale getirmek amacıyla her iki teklifin en iyi özelliklerini daha da birleştirmek için gelecekte çalışmalar yapacaktır.

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 bir konu şu şekilde kullanılabilir: bağlamsal bilgiler sağlar. Bir konu, aşağıdaki özellikleri kullanın:

  • auctionSignals, navigator.runAdAuction() hedefine iletilen açık artırma yapılandırma nesnesinin bir mülkü
  • userBiddingSignals, ilgi alanı grubu yapılandırmasının bir mülkü nesne navigator.joinAdInterestGroup() hücresine geçirildi

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

Kullanıcılar, Chrome'da Özel Korumalı Alan denemelerine katılımlarını şu şekilde ayarlayabilir: üst düzey ayarı etkinleştirmek veya devre dışı bırakmak chrome://settings/adPrivacy

İlk test sırasında, kullanıcılar bu üst düzey gizliliği kullanabilecekler. Protected Audience API'yi devre dışı bırakmak için korumalı alan ayarı. Chrome, kullanıcıların Web'de eklendikleri ilgi alanı gruplarının listesini yönetme daha fazla bilgi edineceksiniz. Özel Korumalı Alan teknolojilerinin kendisinde olduğu gibi, Kullanıcılar, düzenleyici kurumlar ve diğer kullanıcılardan gelen geri bildirimler doğrultusunda kullanıcı ayarları değişebilir.

Testlere ve geri bildirimlere dayanarak Chrome'da kullanılabilen ayarları güncellemeye devam edeceğiz. Gelecekte Protected Audience API ve ilişkili verilerdir.

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

Soru sormak ve uygulamanız, demo veya dokümanlar:

Protected Audience API ile ihtiyaçlarınızı karşılama hakkında daha genel sorular için: API deposunda sorun bildirin. Ayrıca, W3C’nin Web Reklamcılığı İşletme Grubunu İyileştirme.

Özel Korumalı Alan geri bildirim formunu kullanın özelliğini kullanarak geri bildiriminizi herkese açık forumlar dışında Chrome ekibiyle gizli olarak paylaşabilirsiniz.

Devre dışı bırakma

Protected Audience API'yi devre dışı bırakmak mı istiyorsunuz? Nasıl yapıldığını öğrenin Protected Audience API'ye erişimi engelleyin. kabul edersiniz.

Güncellemeleri al