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
- Protected Audience API teklifi genel kullanılabilirliğe taşınıyor. Sorular sorun ve tartışmaları takip edin.
- Bekleyen özelliklerin Protected Audience API durumu sayfasında Protected Audience API ve özelliklerinde yapılan değişiklikler ile geliştirmeler ayrıntılı olarak açıklanır.
- Yanıp sönme durumu
- Protected Audience API Chrome platform durumu: Chrome'daki Protected Audience API'ye özeldir.
- Ads API Chrome platform durumu: Reklamcılığı kolaylaştırmak için API'lerden oluşan bir koleksiyon: Protected Audience API, Topics, Fenced Frames ve Attribution Reporting.
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:
joinAdInterestGroup()
vegenerateBid()
için alıcı kılavuzu.- Protected Audience API için satıcı kılavuzu
runAdAuction()
- Alıcı kılavuzu
reportWin()
ve satıcı kılavuzu:reportResult()
- Protected Audience API ile ilgili sorunları giderme
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.
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:
chrome://settings/adPrivacy
altındaki tüm reklam gizliliği API'lerini etkinleştirin.- Komut satırından işaretleri ayarlayın. Kullanılabilen Protected Audience API işaretlerinin tam listesini Chromium Code Search'te bulabilirsiniz.
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
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
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.
- Protected Audience API açıklamasını okuyun: Tarayıcılar İlgi Alanı Gruplarını Kayıt.
- Alıcılar ve TTP'ler için API kılavuzunu okuyun:
joinAdInterestGroup()
ve teklif oluşturmayı öğrenin.
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
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
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.
- Protected Audience API açıklamasını okuyun: Cihaz üzerinde açık artırma yapan satıcılar
- API kılavuzunu okuyun: Satıcılar
runAdAuction()
ve reklam açık artırma gecikmesiyle ilgili en iyi uygulamalar hakkında daha fazla bilgi edinebilir.
5. Satıcı ve katılımcı alıcılar, Key/Value hizmetinden gerçek zamanlı veriler ister
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.
- Protected Audience API açıklayıcısını okuyun: Protected Audience API Anahtar/Değer Hizmetinden Gerçek Zamanlı Veriler Alma.
- Protected Audience API Anahtar/Değer Hizmeti için açık kaynak sağlama konusunu okuyun.
6. Kazanan 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.
- Protected Audience API açıklayıcısını okuyun: Kazanan reklamı tarayıcılar oluşturur
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.
- API kılavuzunu okuyun: Satıcı ve alıcı raporları hakkında bilgi edinin.
8. Bir reklam tıklaması raporlanır
Ç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 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:
- GitHub: Açıklamayı okuyun, soruları sorun ve tartışmayı takip edin.
- Demo: Demo kodu deposunda bir sorunu bildirin.
- Geliştirici desteği: Özel Korumalı Alan Geliştirici Destek deposunda sorular sorun ve tartışmalara katılın. Protected Audience API için sorun şablonunu seçin.
- Chrome uygulaması: Chrome'un Protected Audience API uygulamasındaki hatalar veya sorunlar için mevcut sorunları görüntüleyebilir veya yeni bir sorun ortaya çıkarabilirsiniz.
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
- API durumu değişiklikleriyle ilgili bildirimler için geliştiricilere yönelik posta listesine katılın.
- API ile ilgili devam eden tüm tartışmaları yakından takip etmek için GitHub'daki API sayfasında İzle düğmesini tıklayın. Bunun için bir GitHub hesabınızın olması veya bir GitHub hesabı oluşturmanız gerekir.
- Özel Korumalı Alan ile ilgili genel güncellemeleri almak için RSS özet akışına abone olun [Privacy Sandbox'ta ilerleme durumu].
- Protected Audience API için planlanmış çağrılara katılın (her iki haftada bir). Herkes katılabilir. Önce WICG'ye katıldığınızdan emin olun. Etkinliğe aktif bir şekilde katılabilir veya yalnızca dinleyebilirsiniz.