Protected Audience API: geliştirici kılavuzu

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

Protected Audience API'ye yeni başlayanlar için API'nin genel bir açıklamasını içeren Protected Audience API'ye genel bakış bölümünü okuyun.

Bu gönderi, deneysel Protected Audience API'nin en son iterasyonu için teknik referans olarak geliştiriciler için yazılmıştır. Temel bir Protected Audience API dağıtımının demo'su 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ını sunmak için tasarlanmış bir Özel Korumalı Alan API'sidir. API, üçüncü tarafların siteler genelinde kullanıcı tarama davranışlarını izlemesi için kullanılamayacak şekilde tasarlanmıştır. API, kullanıcının daha önce ziyaret ettiği web siteleriyle alakalı reklamlar seçmek için tarayıcı tarafından cihaz üzerinde açık artırmalar yapılmasını sağlar.

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

Protected Audience API'yi deneyin

Kullanılabilir API referansı

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

Protected Audience API reklam açık artırması gecikmesi ile ilgili en iyi uygulamaları da okuyabilirsiniz.

Protected Audience API demosu

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

Protected Audience API demo kodunun nasıl çalıştığını ve hata ayıklama için Chrome Geliştirici Araçları'nın nasıl kullanılacağını öğrenmek üzere 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 çitle çevrili ç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>'ü kullanmak üzere:

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

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

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

Geçici hata ayıklama kaybı/kazanç 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 etmek için yapılan ilk denemedir:

  • İlgi alanı grupları: Reklam teklifli sistemini ve oluşturmayı 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: Saklanan ilgi alanı gruplarına ve satıcıdan gelen sinyallere dayanır.
  • Satıcı (SSP veya yayıncı) tarafından cihaz üzerinde reklam seçimi: Açık artırma tekliflerine ve alıcılardan gelen meta verilere dayanır.
  • Çitli çerçevelerin geçici olarak gevşetilmiş 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çıklamalı kılavuzunda bulabilirsiniz.

İlgi grubu izinleri

Protected Audience API'nin mevcut uygulamasında varsayılan olarak, joinAdInterestGroup() işlevinin bir sayfanın herhangi bir yerinden (hatta alan adları arası iframe'lerden) çağrılmasına izin verilir.

Gelecekte, site sahipleri alanlar arası iframe izin politikalarını güncelledikten sonra alanlar arası iframe'lerden gelen çağrılara izin verilmemesi 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 anlık 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 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 kullanıma sunuldu. Uzun vadede reklam teknolojilerinin, güvenilir yürütme ortamlarında çalışan açık kaynak Protected Audience API Anahtar/Değer hizmetlerini kullanması gerekecektir.

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ının API'yi destekleyip desteklemediğini ve dokümanda kullanılıp kullanılamayacağı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 bisiklet üreticisinin web sitesine göz atar ve daha sonra bir haber web sitesini ziyaret eder. Bu sırada, bisiklet üreticisinin yeni 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 ü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 bisikletin ürün sayfasında biraz zaman geçirdiğini varsayalım. Bu, bisiklet üreticisine yeniden pazarlama fırsatı sunar.

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

Bir kullanıcı dizüstü bilgisayarında tarayıcı açıp bir siteyi ziyaret eder. Reklam ilgi alanı gruplarını birleştirmeyle ilgili JavaScript kodu tarayıcıda çalışıyor.

Reklamverenin talep tarafı platformu (DSP) (veya reklamverenin kendisi), navigator.joinAdInterestGroup() çağrısı yaparak tarayıcıdan üyesi olduğu gruplar listesine bir ilgi alanı grubu eklemesini ister.

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

İlgi alanı grubu için reklam 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 veriler içerir. Örneğin:

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

Alıcılar nasıl teklif verir?

generateBid(), tarayıcı üyesi olduğu her 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ı 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ı düzenlenir

Bir kişi, dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini görüntülüyor. Mevcut reklam alanı için bir reklam seçmek üzere Protected Audience API reklam açık artırması düzenlenir.

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

5. Satıcı ve katılımcı alıcılar, Anahtar/Değer hizmetinden anlık veri ister.

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

Satıcı, reklam açık artırması sırasında anahtar/değer hizmetine istek göndererek belirli reklam öğeleriyle ilgili anlık veriler isteyebilir. Satıcı, runAdAuction() sırasında trustedScoringSignalsUrl mülkü aracılığıyla bu bilgileri isteyebilir. Bu bilgilere ads içindeki tüm girişlerin renderUrl mülklerindeki anahtarlar ve açık artırmadaki tüm ilgi alanı gruplarının adComponents alanları da dahildir.

Alıcı, navigator.joinAdInterestGroup()'ye iletilen ilgi alanı grubu bağımsız değişkeninin trustedBiddingSignalsUrl ve trustedBiddingSignalsKeys özelliklerini kullanarak Anahtar/Değer hizmetinden 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 öğesinden alınır.

Bu isteğinin yanıtı, anahtarların her biri için değerler sağlayan bir JSON nesnesi olacaktır.

6. Kazanan reklam gösterilir

Bir kişi, dizüstü bilgisayarındaki tarayıcıda bir haber web sitesini görüntülüyor. Bir bisikletin% 20 indirimli fiyatını gösteren reklam, güvenli bir çerçeve içinde gösterilir.

Açık artırma yapılandırmasındaresolveToConfig işaretçisi true olarak ayarlandığında runAdAuction() tarafından döndürülen söz, çitle çevrili bir çerçeve yapılandırması nesnesine (FencedFrameConfig) çözünür. Çerçeve yapılandırması, çerçeveyi kazanan reklama yönlendirmek için çitle çevrili bir çerçeve tarafından kullanılır ancak reklamın URL'si, çerçeveyi yerleştiren kullanıcı tarafından görülemez.

Ç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 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 veren 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 bir URL'yi temsil eden ve raporlanacak etkinlik düzeyindeki bilgileri kodlayan bir dize.

8. Bir reklam tıklaması bildirilir

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

Çitli bir çerçevede oluşturulan bir reklamın tıklaması raporlanır. Bunun nasıl işleyebileceği hakkında daha fazla bilgi edinmek için Çitli çerçeve reklam raporları başlıklı makaleyi 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ı özetler.

Protected Audience API ile TURTLEDOVE arasındaki fark nedir?

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

Protected Audience API, TURTLEDOVE'un üst düzey ilkelerine uyar. Bazı online reklamcılık, daha önce reklamveren veya reklam ağı ile etkileşime geçmiş, ilgilenme olasılığı olan bir kullanıcıya reklam göstermeye dayanıyordu. Geçmişte bu, reklamverenin web sitelerinde gezinen belirli bir kişiyi tanımasıyla işe yaramıştır. Bu da günümüz web'indeki temel gizlilik sorunlarından biridir.

TURTLEDOVE çalışması, bu kullanım alanını ele alırken bazı önemli gizlilik geliştirmeleri sunan yeni bir API sunmaktır:

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

Protected Audience API, TURTLEDOVE'dan ve API'yi kullanacak geliştiricilere daha iyi hizmet vermek için yapılacak değişikliklerle ilgili bir dizi ilgili öneriden doğdu:

  • SPARROW'da: Criteo, güvenilir yürütme ortamında çalışan ("Güvenlik görevlisi") bir hizmet modelinin eklenmesini önerdi. Protected Audience API, gerçek zamanlı veri arama ve toplu raporlama için TEE'lerin daha sınırlı bir kullanımını içerir.
  • NextRoll'un TERN ve Magnite'nin PARRROT teklifleri, alıcıların ve satıcıların cihaz üzerinde açık artırmada sahip olduğu farklı rolleri tanımladı. Protected Audience API'nin reklam teklifli sistemi/puanlama akışı bu çalışmaya dayanır.
  • RTB House'un Sonuça 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, Microsoft'un reklam isteklerini anonimleştirmek ve gizlilik özelliklerini zorunlu kılmak için tarayıcı ile reklam teknolojisi sağlayıcılar arasında bir TEE'de çalışan bir proxy sunucuya dayanan TURTLEDOVE benzeri bir reklam hizmeti önerisidir. Protected Audience API bu proxy modelini benimsemedi. PARAKEET ve Protected Audience API için JavaScript API'lerini uyumlu hale getiriyoruz. Bu sayede, her iki teklifin en iyi özelliklerini daha da birleştirmek için gelecekteki çalışmaları destekliyoruz.

Protected Audience API, bir web sitesinin reklam ağının kullanıcının hangi reklamları gördüğünü öğrenmesini henüz engellemiyor. 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 içeriğe dayalı bilgi olarak kullanılabilir. Bir konu aşağıdaki özelliklere dahil edilebilir:

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

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

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

İlk test sırasında kullanıcılar, Protected Audience API'yi devre dışı bırakmak için bu üst düzey Gizlilik 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üzenleyicilerden ve diğerlerinden gelen geri bildirimlerle gelişebilir.

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

API çağırıcıları, 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ş parçacıkları tarayıcı tarafından önbelleğe alınıyor mu?

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

Etkileşim kurma ve geri bildirim paylaşma

Destek alın

Uygulamanız, demo veya dokümanlar ile 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 varsa API deposunda sorun kaydı oluşturun. Sektör kullanım alanlarını W3C'nin Web Reklamcılığını Geliştirme İş Grubu'nda da tartışabilirsiniz.

Herkese açık forumlar dışında Chrome Ekibi ile geri bildiriminizi özel 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