Protected Audience API ile özel kitle hedeflemeyi destekleme

Son güncellemeler

Protected Audience, Beta sürümündedir ve herkese açık cihazlarda test edilebilir.

Korunan Kitle ile şunları yapabilirsiniz:

  • Özel kitleleri önceki kullanıcı işlemlerine göre yönetin.
  • Tek satıcılı veya şelale uyumlulaştırması desteği ile cihaz üzerinde açık artırmalar başlatın.
  • Reklam seçiminin ardından gösterim raporlamasını kullanın.

Başlamak için Protected Audience geliştirici kılavuzunu okuyun. Sizin geri bildirimlerinize değer veriyoruz.

Zaman çizelgesi

Önümüzdeki aylarda yeni özellikler kullanıma sunacağız. Kesin yayın tarihleri özelliğe bağlı olarak değişiklik gösterebilir. Bu tablo, belge kullanıma sunulur.

Özellik Geliştirici Önizlemesi'nde kullanılabilir Beta sürümünde kullanılabilir
Etkinlik düzeyinde raporlama 2023 1. Çeyrek 2023 3. Çeyrek
Şelale uyumlulaştırması 2023 1. Çeyrek 2023 4. Çeyrek
Uygulama yükleme reklamlarını filtreleme 2023 2. çeyrek 2023 3. Çeyrek
Sıklık sınırı filtreleme 2023 2. çeyrek 2023 3. Çeyrek
Filtreleme için içeriğe dayalı reklamları reklam seçimi iş akışına iletme 2023 2. çeyrek 2023 3. Çeyrek
Etkileşim raporlama 2023 2. çeyrek 2023 3. Çeyrek
Özel kitleye katılma yetkisi 2023 3. Çeyrek 2023 4. Çeyrek
BGBM dışı faturalandırma 2023 3. Çeyrek 2023 4. Çeyrek
Teklifli sistem ve açık artırma hizmetleri entegrasyonu 2023 3. Çeyrek 2023 4. Çeyrek
Hata ayıklama raporları 2023 3. Çeyrek 2023 4. Çeyrek
İlişkilendirme raporlama entegrasyonu Yok 2023 4. Çeyrek
Open Bidding uyumlulaştırma 2023 4. Çeyrek 2023 4. Çeyrek
Para birimi yönetimi 2024 1. Çeyrek 2024'ün 2. çeyreği
K-anon entegrasyonu Yok 2024'ün 2. çeyreği
Toplu raporlama entegrasyonu 2024'ün 3. çeyreği 2024 4. Çeyrek

Genel Bakış

Mobil reklamcılıkta reklamverenlerin, genellikle reklamları potansiyel olarak ilgilenen kullanıcılara, reklamverenin uygulamasıyla daha önce nasıl etkileşime geçtiklerine göre yayınlaması gerekir. Örneğin, SportingGoodsApp'in geliştiricisi, alışveriş sepetinde ürün kalan kullanıcılara reklam göstererek satın alma işlemini tamamlamalarını hatırlatmak isteyebilir. Sektörde bu yaygın bir tanım "yeniden pazarlama" gibi terimler içeren genel fikirler ve "özel kitle hedefleme".

Günümüzde bu kullanım alanları genellikle bağlam bilgisi paylaşarak reklamın nasıl gösterildiği (uygulama adı gibi) ve gizli reklam teknolojisi platformlarına sahip kitle listeleri gibi bilgiler de buna dahildir. Reklamverenler bu bilgileri kullanarak sunucularında alakalı reklamlar seçebilir.

Android'deki Protected Audience API (eski adıyla FLEDGE), reklam teknolojisi platformlarının ve reklamverenlerin, hem tanımlayıcıların uygulamalar arasında paylaşılmasını hem de kullanıcının uygulama etkileşim bilgilerinin üçüncü taraflarla paylaşılmasını sınırlayacak şekilde etkileşime dayalı yaygın kullanım alanlarını desteklemesi için aşağıdaki API'leri kapsar:

  1. Custom Audience API: Bu API, ortak amaçlara sahip reklamveren tarafından atanan bir kitleyi temsil eden "özel kitle" soyutlaması etrafında döner. Kitle bilgileri cihaz üzerinde depolanır ve Kitleyle alakalı ve rastgele aday reklamlarla ilişkilendirilebilir. meta veriler (ör. teklif sinyalleri) Bu bilgiler, şirkette reklamveren teklifleri, reklam filtreleme ve oluşturma.
  2. Reklam Seçimi API'si: Bu, reklam teknolojisi platformlarını düzenler cihaz üzerinde sinyalleri kullanan iş akışları bir "kazanan" sonuç yerel olarak depolanan aday reklamları göz önünde bulundurarak reklam ve bir reklam teknolojisi platformunun aday reklamlarında ek işlem gerçekleştirerek geri yüklenir.
Android'deki Özel Korumalı Alan'da özel kitle yönetimi ve reklam seçimi iş akışını gösteren akış şeması.

Özet olarak entegrasyon aşağıdaki gibi çalışır:

  1. SportingGoodsApp, kullanıcılarına kalan ürünleri satın almalarını hatırlatmak istiyor alışveriş sepetinde bulunabilir. SportingGoodsApp, kullanıcıyı "alışveriş sepetindeki ürünler" kitle listesi. Platform bunu yönetir ve saklar kitle listesi oluşturarak üçüncü taraflarla paylaşımı sınırlandırır. SportingGoodsApp, reklamlarını kitle listesinde yer alan kullanıcılara göstermek için bir reklam teknolojisi platformuyla iş ortaklığı yapar. Reklam teknolojisi platformu, kitle listeleri için meta verileri yönetir ve reklam seçim iş akışında değerlendirilmek üzere reklam adaylarını sağlar. Platform, arka planda güncellenmiş kitle tabanlı reklamları düzenli olarak getirme için yapılandırılabilir. Bu kitleye dayalı aday reklamlarının listesinin güncel ve alakasız kalmasına yardımcı olur. Reklam fırsatı sırasında üçüncü taraf reklam sunucularına gönderilen isteklerle (ör. bağlamsal reklam isteği) için geçerlidir.

  2. Kullanıcı aynı cihazda FrisbeeGame'i oynadığında bir reklam görebilir SportingGoodsApp'in uygulamasında kalan ürünleri satın almalarını tamamlamalarını hatırlatarak anlamına gelir. Bu, FrisbeeGame'in (entegre bir reklam SDK'sı ile) kullanıcı için kazanan reklamı seçmek üzere Reklam Seçimi API'sini çağırarak (bu örnekte SportingGoodsApp tarafından oluşturulan "alışveriş sepeti ürünleri" özel kitlesi) elde edilebilir. Reklam seçimi iş akışı, özel kitlelerle ilişkili cihaz üzerindeki reklamların yanı sıra cihaz üzerindeki diğer sinyallerin yanı sıra reklam teknolojisi platformlarının sunucularından alınan reklamları da dikkate alacak şekilde ayarlanabilir. İş akışı ayrıca reklam teknolojisi platformu ve reklam SDK'sı tarafından özel teklif verme ve özel teklif verme ile özelleştirilmiş puanlama mantığını kullanır. Bu yaklaşım sayesinde Reklam seçimine yön vermek için kullanıcının ilgi alanı veya uygulama etkileşimleri verileri, ve bu verilerin üçüncü taraflarla paylaşılmasını sınırlama.

  3. Reklam sunma uygulaması veya reklam teknolojisi platformunun SDK'sı, seçilen reklamı oluşturur.

  4. Platform, gösterimlerin ve reklam seçimi sonuçlarının raporlanmasını kolaylaştırır. Bu raporlama özelliği, Attribution Reporting API'ye tamamlayıcıdır. Reklam teknolojisi platformları raporlama ihtiyaçlarına göre özelleştirebilirsiniz.

Android API'lerinde Protected Audience'a erişim elde etme

Reklam teknolojisi platformlarının Protected Audience API'ye erişmek için kaydolması gerekir. Daha fazla bilgi için Privacy Sandbox hesabına kaydolma başlıklı makaleyi inceleyin.

Özel kitle yönetimi

Özel kitle

Özel kitle, reklamveren tarafından belirlenen ve ortak amaçları veya ilgi alanları olan bir kullanıcı grubunu temsil eder. Bir uygulama veya SDK, "alışveriş sepetinde ürün bırakan" veya bir oyunun "başlangıç seviyelerini tamamlayan" kullanıcılar gibi belirli bir kitleyi belirtmek için özel kitle kullanabilir. Platform kitle bilgilerini cihazda yerel olarak tutar ve depolar, Kullanıcının hangi özel kitlelerde olduğunu gösterir. Özel kitleler Chrome'un Protected Audience ilgi alanı grupları ve bunlar paylaşılamaz en iyi uygulamaları paylaşacağız. Bu, kullanıcı bilgilerinin paylaşımının sınırlanmasına yardımcı olur.

Reklamveren uygulaması veya entegre SDK, örneğin bir uygulamadaki kullanıcı etkileşimini temel alarak özel bir kitleye katılabilir veya kitleden ayrılabilir.

Özel kitle meta verileri

Her özel kitle aşağıdaki meta verileri içerir:

  • Sahip: Sahip uygulamanın paket adı. Bu ayar dolaylı olarak paket adı:
  • Alıcı: Bu özel kitle için reklamları yöneten alıcı reklam ağı. Alıcı, özel kitleye erişip alakalı reklam bilgilerini alabilen tarafı da temsil eder. Alıcı, eTLD+1 biçimiyle belirtilir.
  • Ad: Özel kitle için rastgele bir ad veya tanımlayıcı ("alışveriş sepetini terk edenler" özelliğine sahip bir kullanıcı gibi). Bu özellik, örneğin reklamverenin reklam kampanyalarındaki hedefleme ölçütlerinden biri veya teklif kodunu almak için URL'deki bir sorgu dizesi olarak kullanılabilir.
  • Etkinleşme zamanı ve geçerlilik bitiş zamanı: Bu alanlar, bu özel kitlenin etkin olacağı zaman aralığını tanımlar. Platform bunu kullanır bilgileri ve bilgileri toplamanızı sağlar. Özel kitlenin ömrünü sınırlamak için süre sonu, maksimum süre aralığını aşamaz.
  • Günlük güncelleme URL'si: Platformun, "Kullanıcı teklifli sistem sinyalleri" ve "Güvenilir teklifli sistem sinyalleri" alanlarında tanımlanan aday reklamları ve diğer meta verileri tekrar tekrar almak için kullandığı URL. Daha fazla bilgi için özel kitleler için aday reklamları getirme bölümüne bakın.
  • Kullanıcı teklif sinyalleri: Yeniden pazarlama reklamlarının teklifi için reklam teknolojisi platformuna özgü sinyaller. Sinyallere örnek olarak şunlar verilebilir: kullanıcının yaklaşık konumu, tercih ettiği yerel ayar vb.
  • Güvenilir teklif verileri: Reklam teknolojisi platformları gerçek zamanlı verilere dayanır özelliğini kullanın. Örneğin bir reklamın bütçesi tükenebilir ve reklam sunumunun hemen durdurulması gerekiyor. Reklam teknolojisi, bu gerçek zamanlı verilerin alınabileceği bir URL uç noktası ve gerçek zamanlı aramanın yapılması gereken anahtar grubunu tanımlayabilir. Bunu işleyen sunucu güvenilir olacaktır tarafından yönetilen bir sunucu reklam teknolojileri platformu.
  • Teklif verme mantığı URL'si: Platformun teklifi getirmek için kullandığı URL kodu alır. Platform, reklam açık artırması başlatıldığında bu adımı gerçekleştirir.
  • Reklamlar: Özel kitle için aday reklamların listesi. Reklam teknolojisi platformuna özgü reklam meta verileri ve reklamın oluşturulacağı URL bu kapsamdadır. Bir özel kitle için açık artırma başlatılırsa, bu reklam meta verileri listesi dikkate alınır. Bu reklam listesi, mümkün olduğunda günlük güncelleme URL uç noktası kullanılarak yenilenir. Mobil cihazlardaki kaynak kısıtlamaları nedeniyle, özel bir kitlede depolanabilecek reklam sayısı sınırlıdır.

Özel kitle yetkilendirmesi

Geleneksel özel kitle tanımı ve yapılandırması genellikle iş ortaklığı ile ortak çalışarak reklam teknolojilerinin desteklediği sunucu tarafı teknolojiler ajans, reklamveren müşterileri ve iş ortakları. Protected Audience API, Ayrıca kullanıcı gizliliğini korurken özel kitle tanımı ve yapılandırması Alıcı: özel bir kitleye katılın, uygulamalarda SDK varlığı olmayan alıcı reklam teknolojileri mobil cihaz gibi cihazlarda varlık gösteren reklam teknisyenleriyle ortak çalışma yapması ölçüm iş ortakları (MMP'ler) ve arz tarafı platformları (STP'ler) Protected Audience API, cihaz üzerinde arayanların alıcılar adına özel kitle oluşturma işlemini tetiklemesine olanak tanıyarak özel kitle yönetimi için esnek çözümler sunarak bu SDK'ları desteklemeyi amaçlar. Bu sürece özel kitle yetkilendirme denir. Özel kitle yetkilendirmesini yapılandırmak için:

Özel bir kitleye katılma

Özel kitlelere katılmanın iki yolu vardır:

joinCustomAudience()

Bir uygulama veya SDK, CustomAudience nesnesini beklenen parametrelerle örnekledikten sonra joinCustomAudience()'ü çağırarak özel bir kitleye katılma isteğinde bulunabilir. Aşağıda, açıklayıcı bir kod snippet'i örneği verilmiştir:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

Bir uygulama veya SDK, aşağıdaki örnekte gösterildiği gibi beklenen parametrelerle fetchAndJoinCustomAudience() çağrısını yaparak cihaz üzerinde varlığı olmayan bir reklam teknolojisi adına özel bir kitleye katılma isteğinde bulunabilir:

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

Alıcıya ait URL uç noktası bir CustomAudience JSON ile yanıt verir nesnesini ifade eder. Özel kitlenin alıcı ve sahip alanları yoksayılır (ve API tarafından otomatik olarak doldurulur). API ayrıca, günlük güncelleme URL'si de alıcının eTLD+1'iyle eşleşir.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

fetchAndJoinCustomAudience() API, fetchUri'in eTLD+1 alanından alıcının kimliğini belirler. CustomAudience alıcı kimliği, joinCustomAudience() tarafından yapılan aynı kayıt ve uygulama yetkilendirme kontrollerini gerçekleştirmek için kullanılır ve getirme yanıtı tarafından değiştirilemez. CustomAudience adlı kullanıcının sahibi: çağrı yapan uygulamanın paket adıdır. fetchUri için eTLD+1 denetimi dışında başka bir doğrulama yoktur ve özellikle k-anon denetimi yoktur. fetchAndJoinCustomAudience() API, fetchUri ve özel kitleyi temsil eden bir JSON nesnesi bekliyor. Yanıta, özel kitle nesnesi alanları için zorunlu, isteğe bağlı kısıtlamalar ve varsayılan değerler uygulanır. Mevcut içerikler hakkında bilgi edinin gereksinimler ve kısıtlamalara göz atın.

Alıcıdan gelen herhangi bir HTTP hatası yanıtı, fetchAndJoinCustomAudience ürününün başarısız olur. Özellikle 429 (Çok Fazla İstek) HTTP durum yanıtı, geçerli uygulamadan gelen istekleri tanımlanacak bir süre boyunca engeller. API çağrısı ve alıcının yanıtı bozuksa da başarısız olur. Geçici hatalar (ör. sunucunun yanıt vermemesi) veya kalıcı hataları (ör. veri doğrulama hataları veya sunucuyla iletişimle ilgili geçici olmayan diğer hatalar) nedeniyle yeniden denemekten sorumlu API çağırıcıya bildirilir.

CustomAudienceFetchRequest nesnesi, API çağıranın yukarıdaki örnekte gösterilen isteğe bağlı özellikleri kullanarak Özel Kitle için bazı bilgileri tanımlamasına olanak tanır. İstekte ayarlanırsa bu değerlerin üzerine platformun aldığı alıcı yanıtını; Protected Audience API, alanları yazmalısınız. Özel kitle oluşturmak için bu alanların gerekli olması nedeniyle, istekte ayarlanmamışlarsa yanıtta ayarlanmaları gerekir. CustomAudience içeriğinin JSON gösterimi API çağrısı tarafından kısmen tanımlanan fetchUri, GET isteğine dahil edilir özellikle X-CUSTOM-AUDIENCE-DATA üstbilgisinde yer alır. Serileştirilmiş formun boyutu Özel Kitle için belirtilen veriler 8 KB ile sınırlıdır. Boyut fetchAndJoinCustomAudience API çağrısı başarısız oldu.

k-anon kontrolü olmaması, alıcı doğrulaması için fetchUri kullanmanıza ve alıcı ile SDK arasında bilgi paylaşımını etkinleştirmenize olanak tanır. Özel kitle doğrulamasını kolaylaştırmak için alıcının bir doğrulama jetonu sağlaması mümkündür. Cihaz üzerinde SDK, bu jetonu fetchUri içine dahil etmelidir. Böylece, alıcı tarafından barındırılan uç nokta, özel kitlenin içeriğini getirebilir ve fetchAndJoinCustomAudience() işleminin alıcıya karşılık geldiğini ve güvenilir bir cihaz üzerinde iş ortağı tarafından başlatıldığını doğrulamak için doğrulama jetonunu kullanabilir. Alıcı, bilgi paylaşmak için cihaz üzerinde arayanla anlaşabilir. özel kitleyi oluşturmak için kullanılacak bazı bilgilerin fetchUri öğesine sorgu parametreleri olarak eklendi. Bu sayede alıcı, çağrıları denetleyebilir ve kötü amaçlı bir reklam teknolojisi tarafından çeşitli farklı özel kitleler oluşturmak için bir doğrulama jetonunun kullanılıp kullanılmadığını algılayabilir.

Doğrulama jetonu tanımı ve depolama hakkında not

  • Doğrulama jetonu, Protected Audience tarafından herhangi bir amaçla kullanılmaz API'dir ve isteğe bağlıdır.

    • Doğrulama jetonu, oluşturulan kitlelerin kendi adına oluşturulduğunu doğrulamak için alıcı tarafından kullanılabilir.
    • Protected Audience API teklifinde, doğrulama jetonu için bir biçim veya alıcının doğrulama jetonunu arayan tarafa nasıl aktardığı belirtilmiyor. Örneğin, doğrulama jetonu, sahibin SDK'sına veya arka ucuna önceden yüklenebilir ya da sahibin SDK'sı tarafından alıcının sunucusundan anlık olarak alınabilir.

Özel kitleden ayrılma

Özel kitlenin sahibi, aşağıdaki açıklayıcı kod snippet'inde gösterildiği gibi leaveCustomAudience() çağrısı yaparak ayrılmayı seçebilir:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

Depolama alanının ve diğer cihaz kaynaklarının kullanımını korumaya yardımcı olmak için özel kitlelerin süresi önceden belirlenmiş bir süre sonra dolar ve cihaz üzerindeki mağazadan kaldırılır. Varsayılan değer belirlenecektir. Sahip bu varsayılan değeri geçersiz kılabilir.

Kullanıcı denetimi

  • Teklifin amacı, kullanıcılara yüklü uygulamalar listesini göstermek En az bir özel kitle oluşturanlar
  • Kullanıcılar bu listeden uygulama kaldırabilir. Kaldırma işlemi, tüm özel uygulamalarla ilişkilendirilen kitleleri izler ve uygulamaların yeni özel kitlelerdir.
  • Kullanıcılar Protected Audience API'yi tamamen sıfırlayabilir. Zaman Cihazdaki mevcut özel kitleler temizlenir.
  • Kullanıcılar, Protected Audience API'yi de içeren Android'de Özel Korumalı Alan'ı tamamen devre dışı bırakabilir. Kullanıcı Özel Korumalı Alan'ı devre dışı bıraktıysa Protected Audience API sessizce başarısız olur.

Bu yeteneğin tasarımı devam eden bir çalışmadır ve ayrıntılar bir güncelleme daha var.

Planlanan Güncellemeler

Daha önce açıklanan çözümler, uygulama veya reklam teknolojisi SDK'sının, uygulama ön plandayken API'leri çağırmasını ve özel kitlenin tüm özelliklerini doğrudan veya yetkilendirme kullanarak sağlamasını gerektirir. Ancak her zaman Böylece, reklamverenler ve reklam teknolojisi sağlayıcılar bir kullanıcının hangi kitleleri gerçek zamanlı olarak yer alır.

Bunu kolaylaştırmak için reklam teknolojisi, scheduleCustomAudienceUpdate() API. Bu API, arayanın API çağrısının ne zaman yapılması gerektiğine dair bir gecikme belirtmesine olanak tanır. Böylece, yanıt veren reklam teknolojisinin uygulama düzeyindeki etkinlikleri işlemesine ve kullanıcının hangi Korunan Kitlelere katılması veya hangilerinden kaldırılması gerektiğini belirlemesine ek süre tanınır.

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

ScheduleCustomAudienceUpdateRequest, gecikmiş bir işi platformla çalışmak üzere kaydettirmek. Belirtilen gecikmenin ardından düzenli olarak bir arka plan işi çalışır ve istekleri gönderir. ScheduleCustomAudienceUpdateRequest aşağıdaki bilgileri içerebilir:

  • UpdateUri: Güncellemeyi almak için GET çağrısı gönderilecek URI uç noktası. Alıcı kimliği, eTLD+1'den doğal olarak anlaşılır ve açıkça sağlanmasına gerek yoktur. Ayrıca güncelleme yanıtı tarafından değiştirilemez. GET isteği, döndürülen customAudience nesnelerinin listesini içeren bir JSON nesnesi bekler.
  • DelayTime: Güncellemeyi planlamak için scheduleCustomAudienceUpdate() API çağrısının yapıldığı andan itibaren geçen gecikmeyi gösteren süre.

  • PartialCustomAudience: API, cihaz üzerinde SDK'nın kısmen oluşturulmuş özel kitlelerin listesini göndermesine de olanak tanır. Böylece, uygulama içi SDK'lar özel kitle yönetimi üzerinde tam kontrolden kısmi kontrole kadar iş ortaklıkları üzerine kurulu.

    • Bu işlem, API'nin fetchAndJoinCustomAudience() ile uyumlu olmasını da sağlar. Benzer bilgi paylaşımına olanak tanıyan API.

  • ShouldReplacePendingUpdates: Beklemede olan planlanmış güncellemelerin iptal edilip edilmeyeceğini ve mevcut ScheduleCustomAudienceUpdateRequest içinde ayrıntılı olarak açıklanan güncellemeyle değiştirilip değiştirilmeyeceğini belirleyen Boole değeri. Bu değer false ve Aynı alıcı için daha önce gönderilen ve halen beklemede olan aynı uygulamada, scheduleCustomAudienceUpdate için çağrı ScheduleCustomAudienceUpdateRequest başarısız. Varsayılan olarak false değerine ayarlanır.

Uygulama izinleri ve kontrolü

Teklif, uygulamalara özel kitleleri üzerinde kontrol sağlamaya yöneliktir:

  • Uygulamalar, özel kitlelerle ilişkilendirmelerini yönetebilir.
  • Bir uygulama, üçüncü taraf reklam teknolojisi platformlarına özel reklamları yönetmek için izinler verebilir kitleleri temsil eder.

Bu özelliğin tasarımı üzerinde çalışmalarımız devam ediyor. Ayrıntılar daha sonraki bir güncellemede paylaşılacak.

Reklam teknolojisi platform denetimi

Bu teklifte, reklam teknisyenlerinin özel kitlelerini kontrol etmek için kullanabileceği yöntemler özetlenmektedir:

  • Reklam teknolojileri, Özel Korumalı Alan'a kaydolur ve özel bir kitlenin tüm URL'leriyle eşleşen bir eTLD+1 alanı sağlar.
  • Reklam teknolojileri, aşağıdaki özelliklere sahip doğrulama jetonları sağlamak için uygulamalarla veya SDK'larla iş ortaklığı yapabilir: Özel kitle oluşturulduğunu doğrulamak için kullanılır. Bu süreç bir iş ortağına devredildiğinde, özel kitle oluşturma işlemi reklam teknolojisinin onayını gerektirecek şekilde yapılandırılabilir.
  • Bir reklam teknolojisi, kendi adına joinCustomAudience aramalarını devre dışı bırakmayı seçebilir ve yalnızca fetchAndJoinCustomAudience API'nin tüm özel çağrıları etkinleştirmesine izin ver kitleler. Kontrol, Özel Korumalı Alan kaydı sırasında güncellenebilir. Kontrolün tüm reklam teknolojilerine veya hiçbirine izin verdiğini unutmayın. Platform kısıtlamaları nedeniyle, yetki izinleri reklam teknolojisi bazında olamaz.

Aday reklamları ve meta veri yanıtı

Alıcı tarafı platformundan döndürülen aday reklamları ve meta veriler, şu alanları kullanın:

  • Meta veriler: Satın alma tarafı, reklam teknolojisine özgü reklam meta verileri. Örneğin bu, reklam kampanyasıyla ilgili bilgileri ve konum ve dil.
  • Oluşturma URL'si: Reklam öğesini oluşturmak için uç nokta.
  • Filtre: Protected Audience API'nin reklamları cihaz üzerindeki verilere göre filtrelemesi için gereken isteğe bağlı bilgiler. Daha fazla bilgi için alıcı tarafı filtreleme mantığı ile ilgili bölümü okuyun.

Reklam seçimi iş akışı

Bu teklif, reklam teknolojisi platformları için açık artırma yürütmeyi koordine eden Reklam Seçimi API'sini tanıtarak gizliliği iyileştirmeyi amaçlamaktadır.

Günümüzde reklam teknolojisi platformları genellikle yalnızca teklif verme ve reklam seçimi işlemlerini yapar. kontrol eder. Bu teklifle, özel kitlelere ve yüklü paket bilgileri gibi diğer hassas kullanıcı sinyallerine yalnızca Reklam Seçimi API'si aracılığıyla erişilebilir. Ayrıca, yeniden pazarlama kullanım alanına Aday reklamlar, bant dışına çıkarılacaktır (yani, reklamların gösterilir). Reklam teknolojisi platformlarının, mevcut açık artırma ve reklam seçim mantıklarının bazı bölümlerinin cihazda dağıtılıp yürütülmesine hazırlanması gerekecek. Reklam teknolojisi platformları, reklamlarında aşağıdaki değişiklikleri yapabilir seçim iş akışı:

  • Sunucuda yüklü paket bilgileri olmadan, reklam teknolojisi platformlar cihaza birden fazla bağlamsal reklam göndermek isteyebilir uygulama yükleme tabanlı filtrelemeyi etkinleştirmek için reklam seçimi iş akışını alakalı bir reklam gösterme olasılığını en üst düzeye çıkarmak için kullanılır.
  • Yeniden pazarlama reklamları bant dışı olduğundan mevcut teklif modellerinin güncellenmesi gerekebilir. Reklam teknolojisi platformları teklif alt modelleri oluşturmak isteyebilir (bu işlem, iki kuleli model) reklam özellikleri ve içerik sinyalleri üzerinde ayrı ayrı çalışabilen ve teklifleri tahmin etmek üzere cihaza alt model çıkışları ekleyebilir. Bu, hem sunucu tarafı açık artırmalardan hem de belirli bir reklam fırsatı için açık artırmalardan yararlanabilir.

Bu yaklaşım, kullanıcının uygulama ile etkileşim verilerinin reklam seçiminde bilgilendirilmesini sağlar. hem de bu verilerin üçüncü taraflarla paylaşımını sınırlar.

Reklam seçimi iş akışının başlatılmasını gösteren akış şeması.

Bu reklam seçimi iş akışı, reklam öğesinin cihaz üzerinde yürütülmesini düzenler reklam teknolojisi tarafından sağlanan JavaScript kodu şu sırayı izleyin:

  1. Alıcı tarafı teklif verme mantığını yürütme
  2. Alıcı tarafı reklam filtreleme ve işleme
  3. Satıcı tarafı karar mantığı yürütme

Özel kitleler içeren reklam seçimlerinde platform, tarafından tanımlanan herkese açık URL uç noktasına dayalı olarak taraftan sağlanan JavaScript kodunu satın al özel kitlenin "Teklif verme mantığı URL'si" meta verilerdir. Şu sayfanın URL uç noktası: satıcı tarafı karar kodu da geri dönelim.

Özel kitleler içermeyen reklam seçimlerinin tasarımı etkin tasarım.

Reklam seçimi iş akışını başlatma

Bir uygulamanın reklam göstermesi gerektiğinde reklam teknolojisi platformu SDK'sı, AdSelectionConfig nesnesini beklenen parametrelerle örnekledikten sonra selectAds() yöntemini çağırarak reklam seçimi iş akışını başlatabilir:

  • Satıcı: eTLD+1 biçimini izleyen satış tarafı reklam platformunun tanımlayıcısı
  • Karar mantığı URL'si: Reklam açık artırması başlatıldığında platform, bu URL'yi kullanarak satıcı tarafı platformundan JavaScript kodunu getirirsiniz: kazanan reklamdır.
  • Özel kitle alıcıları: Özel kitlesine sahip alıcı tarafı platformlarının listesi bu açık artırma için eTLD+1 biçimi kullanılarak yapılan kitleye dayalı talep.
  • Reklam seçimi sinyalleri: Açık artırmayla ilgili bilgiler (reklam boyutu, reklam biçimi) vb.) bakın.
  • Satıcı sinyalleri: Arz tarafı platformuna özel sinyaller.
  • Güvenilir Puanlama Sinyalleri URL'si: Reklam öğesine özel gerçek zamanlı bilgilerin alınabileceği, satıcı tarafı güvenilir sinyalin URL uç noktası.
  • Alıcı başına sinyaller: Katılımcı talep tarafları, açık artırma için giriş sağlamak amacıyla bu parametreyi kullanabilir. Örneğin, bu parametre Teklifleri belirlemek için faydalı, kapsamlı bağlamsal bilgiler.

Aşağıdaki açıklayıcı kod snippet'inde, başlatılan bir reklam teknolojisi platformu SDK'sı gösterilmektedir önce AdSelectionConfig ve ardından tanımlayarak reklam seçimi iş akışını Kazanan Reklamı almak için selectAds çağrılıyor:

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

Alıcı tarafı teklif verme mantığı

Teklif verme mantığı genellikle alıcı tarafı platformlar tarafından sağlanır. Amacı kod, aday reklamlar için teklifleri belirlemektir. Bu durumda, iş mantığını ve iş mantığını temel alır.

Platform, özel kitlenin "Teklif verme mantığı URL'si" meta verilerini kullanarak aşağıdaki işlev imzasını içermesi gereken JavaScript kodunu getirir:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

generateBid() yöntemi, hesaplanan teklif tutarını döndürür. Platform, bu işlevi tüm reklamlar (içeriğe dayalı veya yeniden pazarlama) için sırayla çağırın. Birden fazla teklif verme mantığı sağlayıcısı varsa sistem, sağlayıcılar arasındaki yürütme sırasını garanti etmez.

İşlev aşağıdaki parametrelerin olmasını bekler:

  • Reklam: Alıcı tarafı teklif verme kodu tarafından değerlendirilen reklam. Bu, Uygun bir özel kitleden reklam
  • Açık artırma sinyalleri: Satıcı tarafına ait, platforma özgü sinyaller.
  • Alıcıya göre sinyaller: Katılımcı talep tarafları bu parametreyi kullanarak açık artırma için girdi sağlar. Örneğin, bu parametre Teklifleri belirlemek için faydalı, kapsamlı bağlamsal bilgiler.
  • Güvenilir teklif verme sinyalleri: Reklam teknolojisi platformları, reklam alma ve puanlama işlemlerini bilgilendirmek için gerçek zamanlı verilerden yararlanır. Örneğin bir reklam kampanyası bitebilir ve reklam yayınının hemen durdurulması gerekiyor. Reklam teknolojisi, bu gerçek zamanlı verilerin alınabileceği bir URL uç noktası ve gerçek zamanlı aramanın yapılması gereken anahtar grubunu tanımlayabilir. Reklam teknolojisi platformunun bu isteği yayınlayan yönetilen sunucusu, reklam teknolojisi platformu tarafından yönetilen güvenilir bir sunucu olacaktır.
  • Bağlam sinyalleri: Kaba zaman damgası veya yaklaşık konum bilgileri ya da reklamın tıklama başına maliyeti bu kapsamdadır.
  • Kullanıcı sinyalleri: Yüklü paket bilgileri gibi bilgiler bu kapsamda yer alabilir.

Reklam maliyeti

Alıcı tarafı platformlar, teklife ek olarak generateBid() kapsamında tıklama başına maliyeti döndürme seçeneğine sahiptir. Örneğin:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

Kazanan bu reklamsa adCost, şu değer için stokastik olarak 8 bite yuvarlanır: gizlilik. Ardından, gösterim raporlaması sırasında adCost değerinin yuvarlanmış değeri reportWin içindeki contextual_signals parametresine iletilir.

Alıcı tarafı filtreleme mantığı

Alıcı tarafı platformlar, diğer cihazlara göre reklamları filtreleyebilecek sinyallerine geçiş yapacaktır. Örneğin, reklam teknolojisi platformları sıklık sınırı özelliklerini burada uygulayabilirsiniz. Birden fazla filtreleme sağlayıcı varsa sistem, sağlayıcılar arasındaki yürütme sırasını garanti etmez.

Alıcı tarafı filtreleme mantığı, teklif mantığını uygulayarak 0 teklif değeri döndürerek başlayın. belirleyicidir.

Buna ek olarak, alıcı tarafı platformları belirli bir reklamın Protected tarafından kullanılabilen cihaz üzerindeki ek sinyallere göre filtrelenmelidir kitle ve cihazdan dışarı çıkmaz. Tasarımlarını sağlamlaştırdıkça ek filtreleme mantığı, alıcı tarafı platformları için de aynı yapıyı izler. filtrelemenin yapılması gerektiğini belirtmek için kullanılır.

Satıcı tarafı puanlama mantığı

Puanlama mantığı genellikle satıcı tarafı platform tarafından sağlanır. Amacı kodu, teklif verme mantığı çıkışlarına göre kazanan reklamı belirlemektir. Bu ek iş mantığı uygulamak için kullanılır. Birden fazla karar mantığı sağlayıcı varsa sistem, sağlayıcılar arasındaki yürütme sırasını garanti etmez. Platform, aşağıdaki işlev imzasını içermesi gereken JavaScript kodunu almak için selectAds() API'nin "Karar mantığı URL'si" giriş parametresini kullanır:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

İşlev aşağıdaki parametreleri bekler:

  • Reklam: Değerlendirilen reklam; generateBid() işlevinden çıkış yapalım.
  • Teklif: generateBid() işlevinden elde edilen teklif tutarı.
  • Açık artırma yapılandırması: selectAds() yöntemine parametre girin.
  • Güvenilir Puanlama Sinyalleri: Reklam teknolojisi platformları, reklam filtreleme ve puanlama için gerçek zamanlı verilerden yararlanır. Örneğin, bir uygulama yayıncısı bir reklam kampanyasının uygulamada reklam göstermesini engelleyebilir. Bu veriler, açık artırma yapılandırmasının güvenilir puanlama sinyalleri URL parametresinden alınır. Bu isteği sunan sunucu, reklam teknolojisi tarafından yönetilen güvenilir bir sunucu olmalıdır.
  • Bağlamsal sinyal: Bu, yaklaşık zaman damgası veya yaklaşık zaman damgası içerebilir. konum bilgisi.
  • Kullanıcı sinyali: Uygulamanın yüklenmesini başlatan uygulama mağazası gibi bilgiler içerebilir.
  • Özel kitle sinyali: Puanlanan reklam cihaz üzerindeki bir reklamdan geliyorsa Bu kitle, okuyucusu ve adı gibi bilgileri içerir. özel kitle.

Reklam seçim kodu çalışma zamanı

Teklifte sistem, reklam teknolojisi platformu tarafından sağlanan açık artırma kodunu yapılandırılabilir URL uç noktalarından alır ve cihazda yürütür. Edindiğiniz kaynağa kısıtlanıyorsa, açık artırma kodu aşağıdakilere uygun olmalıdır: kurallar:

  • Kodun yürütülmesi önceden tanımlanmış bir sürede bitmelidir. Bu sınır, tüm alıcı reklam ağları için tek tip şekilde geçerli olacaktır. Bu sınırın ayrıntıları daha sonraki bir güncellemede paylaşılacaktır.
  • Kod bağımsız olmalı ve harici bağımlılıkları olmamalıdır.

Teklif verme mantığı gibi açık artırma kodunun, uygulama yükleme kaynakları gibi özel kullanıcı verilerine erişmesi gerekebileceğinden çalışma zamanı, ağ veya depolama erişimi sağlamaz.

Programlama dili

Reklam teknolojisi platformu tarafından sağlanan açık artırma kodu JavaScript'te yazılmalıdır. Böylece reklam teknolojisi platformları, İYS'lerden 16'sını değerlendirdik.

Kazanan reklam oluşturma

En yüksek puana sahip reklam, açık artırmanın kazananı olarak kabul edilir. Bu ilk teklifte, kazanan reklam oluşturulmak üzere SDK'ya iletilir.

Plan, çözümü geliştirerek kullanıcının özel kitle üyeliği veya uygulama etkileşim geçmişi, kazanan reklamla ilgili bilgilerle uygulamanın veya SDK'nın (Chrome'un çerçeveli çerçeveler teklifi) ekleyin.

Gösterim ve etkinlik raporlama

Reklam oluşturulduktan sonra, kazanan gösterim hem katılımcı hem de satış tarafı platformları için geçerlidir. Bu sayede alıcılar ve satıcılar, açık artırmadan elde edilen bilgileri (ör. teklif veya özel kitle adı) kazanan gösterim raporuna dahil edebilir. Ayrıca, satıcı tarafı ve kazanan alıcı tarafı platformu, kazanan reklamla ilgili etkinlik düzeyinde ek raporlar almaya uygundur. Bu, belirli bir ürünle ilgili tıklama, görüntüleme sayısı ve diğer verileri içeren açık artırma hakkında (teklif, özel kitle adı vb.) reklam etkinlikleri. Platform, raporlama mantığını şu sırayla çağırır:

  1. Satıcı tarafı raporları.
  2. Alıcı tarafı raporlama.

Bu, alıcı tarafı ve satış tarafı platformlarına cihaz üzerindeki önemli verileri gönderme olanağı sunar. Bu bilgileri sunuculara geri göndererek anlık bütçe oluşturma, bütçe oluşturma, teklif modeli güncellemeleri ve doğru faturalandırma iş akışları. Bu gösterim raporlaması desteği, Attribution Reporting API'yi tamamlayıcı niteliktedir.

Etkinlik raporlamasını desteklemek için iki adım gereklidir: Satıcı tarafı ve alıcı tarafı JavaScript'in, etkinlik raporları alması gereken etkinliği kaydetmesi gerekir ve etkinlik düzeyindeki bilgileri bildirmekten satıcı tarafı sorumludur.

Protected Audience, aşağıdaki konularla ilgili gelecekteki etkinliklere abone olmak için bir mekanizma sağlar: yaparak başarılı bir açık artırmayı ifade eder. Satıcının reportResult()JavaScript işlevinde, satıcı tarafı platformlar platformun registerAdBeacon() işlevini kullanarak işaretçileri kaydedebilir. Benzer şekilde, alıcı tarafı platformlar reportWin() JavaScript işlevinden registerAdBeacon() yöntemini kullanır.

registerAdBeacon(beacons)

Giriş:

  • event_key: Hangi etkileşim türüne kaydedileceğini belirten bir dize. Bu, platformun pinglediği uç noktayı aramak için bir anahtar olarak kullanılır açık artırmanın sonuçlarını raporlayarak.
  • reporting_url: Etkinliği yönetmek için reklam teknolojisi platformunun sahip olduğu URL.

Etkinlik anahtarları, açık artırma sonuçlarını bildirmekten sorumlu olan alıcı tarafı SDK'nın sahip olduğu dize tanımlayıcılardır. Geri çağırma yapılması için reklam teknolojisi uzmanları, etkinlikleri raporlarken satıcı tarafının kullandığı anahtarlarla eşleşen anahtarlarla işaretçiler kaydeder. Bunların k-anonim olması gerekmez ancak Bir alan adı için kaydedilebilecek anahtarların miktarı ve uzunluğuyla ilgili sınırlamalara elde edebilirsiniz. reportEvent() çağrılırsa satış tarafı platformları (reportEvent()) her zaman bu etkinlik raporlarını alabilir. Yalnızca kazanan alıcı tarafı platform bu raporları almaya uygundur.

Satıcı tarafı raporları

Platform, selectAds() API için satıcının Karar mantığı URL parametresinden indirilen, tedarik tarafı tarafından sağlanan kodda reportResult() JavaScript işlevini çağırır:

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

Çıktı: Şunu içeren bir JSON nesnesi:

  • Durum: Başarı için 0, başarısızlık için başka bir değer.
  • Raporlama URL'si: Platform, işlevden döndürülen bu URL'yi çağırır.
  • Alıcı için sinyaller: Alıcının reportWin öğesine iletilecek bir JSON nesnesi işlevini kullanın.

Tedarik tarafı, açık artırma ve kazanan reklam hakkında daha fazla analiz elde etmek için raporlama URL'sine alakalı sinyaller kodlayabilir. Örneğin, aşağıdaki sinyalleri içerebilir:

  • Reklam oluşturma URL'si
  • Kazanan teklif tutarı
  • Uygulama adı
  • Sorgu tanımlayıcıları
  • Alıcı sinyalleri: Arz tarafı ve talep arasında veri paylaşımını desteklemek için tarafından, platform bu döndürülen değerini talep tarafı raporlama kodu.

Alıcı tarafı raporlama

Platform, talepteki reportWin() JavaScript işlevini çağırıyor Teklif mantığı URL'si meta verisinden indirilmiş olan, açık artırmayla ilişkili özel kitle oluşturun.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

Giriş:

  • auction_signals ve per_buyer_signals şuradan alındı: AuctionConfig. Alıcı tarafı platformunun iletmesi gereken tüm bilgiler raporlama URL'si bu veriden geliyor olabilir.
  • signals_for_buyer, satıcı tarafı reportResult'ın çıktısıdır. Bu sayede satış tarafı platformu, raporlama amacıyla alıcı tarafı platformla veri paylaşabilir.
  • contextual_signals, uygulama adı ve custom_audience_signals, özel kitle bilgilerini içeriyor. Diğer bilgi eklenebilir.

Çıkış:

  • Durum: Başarılı için 0, diğer tüm başarısızlık değerleri.
  • Raporlama URL'si: Platform, işlevden döndürülen bu URL'yi çağırır.

Etkinlikleri Bildirme

Etkinlikleri raporlamak yalnızca açık artırma için gösterim raporlaması tamamlandıktan sonra mümkündür. Tüm etkinliklerin raporlanmasından satıcı tarafı SDK sorumludur. Platform, kısa süre önce çalıştırılan açık artırmayı, raporlanan etkinlik anahtarını, bu anahtarla ilişkili verileri, raporun alıcıya mı satıcıya mı (veya her ikisine birden) gönderileceğini ve reklam etkinlikleri için isteğe bağlı bir giriş etkinliğini belirten bir ReportEventRequest alan bir API sağlar. İstemci, etkinlik anahtarını ve raporlanacak veri koleksiyonunu tanımlar.

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

Giriş:

  • ad_selection_id, yakın zamanda yapılan bir açık artırmanın AdSelectionId değeri olmalıdır AdSelectionOutcome kaynağından alındı.
  • event_key, etkileşimi açıklayan, satıcı tarafı tanımlı bir dizedir. unutmayın.
  • event_data, event_key
  • reporting_destinations, platform tarafından sağlanan işaretler kullanılarak ayarlanan bir bit maskesidir. Şunlardan biri olabilir: FLAG_REPORTING_DESTINATION_SELLER veya FLAG_REPORTING_DESTINATION_BUYER veya her ikisi.
  • input_event (isteğe bağlı), Attribution Reporting ile entegrasyon için kullanılır. API'ye gidin. Bu bir InputEvent nesnesi (tıklama etkinliği için) veya null (görüntüleme etkinliği için). Daha fazla bilgi için Attribution Reporting API Entegrasyonu bu parametrenin ayrıntılarını görebilirsiniz.

Satıcı tarafı SDK'sı reportEvent yöntemini çağırdıktan sonra ve reporting_destinations işareti, platform, event_key işaretini alıcı ve satıcıların reportWin ve reportResult JavaScript işlevi. Eşleşme varsa platform, event_data öğesini ilişkili reporting_url öğesine POST eder. İsteğin içerik türü düz metindir ve gövde event_data olur. Bu istek en iyi şekilde gönderildi bağlantı hatası, sunucu hatası veya olası bir hata durumunda veya eşleşen anahtar bulunamadı.

Attribution Reporting API entegrasyonu

Protected Audience açık artırmasına katılan alıcıları desteklemek için Protected Audience ve İlişkilendirme Raporlama API'leri (ARA) genelinde API'ler arası işlevsellik sağlıyoruz. Bu işlev, reklam teknisyenlerinin çeşitli yeniden pazarlama taktiklerinde ilişkilendirme performansını Hangi kitle türlerinin en yüksek YG'yi sağladığını anlayabilirsiniz.

API'ler arası bu entegrasyon sayesinde reklam teknolojileri şunları yapabilir:

  • Her ikisi için de kullanılacak URI'ların anahtar/değer eşlemesini oluşturun 1) reklam etkileşimi raporlaması ve 2) kaynak kaydı.
  • Protected Audience açık artırmasındaki açık artırma verilerini kaynak tarafına dahil et toplu özet raporlama için anahtar eşleme (İlişkilendirme Raporları API) Daha fazla bilgi için ARA tasarım teklifine bakın.

Kullanıcı bir reklamı gördüğünde veya tıkladığında:

  • Protected Audience'ı kullanarak bu etkinlik etkileşimlerini bildirmek için kullanılan URL Alıcıya bir görüntüleme veya tıklama kaydetmek için kullanılacak gerekli verileri sağlama Attribution Reporting API ile uygun bir kaynak olarak işaretleyin.
  • Reklam teknolojisi, bu URL'yi kullanarak CustomAudience'yi (veya reklamla ilgili diğer alakalı bağlamsal bilgileri (ör. reklam yerleşimi veya görüntüleme süresi)) iletmeyi seçebilir. Böylece, reklam teknolojisi toplu kampanya performansını incelerken bu meta veriler özet raporlara iletilebilir.

Kaynak kaydını etkinleştirme

reportEvent(), isteğe bağlı yeni InputEvent parametresini kabul edecek. Galibiyet Reklam işaretçilerini kaydeden alıcılar, kayıtlı kaynak olarak Attribution Reporting API'lere kayıtlı olmalıdır. İstek Tüm etkinlik raporlarına Attribution-Reporting-Uygun başlığı eklenecek istek reportEvent() tarafından gönderildi. Uygun ARA üstbilgilerine sahip tüm yanıtlar, diğer normal ARA kaynak kaydı yanıtlarıyla aynı şekilde ayrıştırılır. Nasıl yapıldığını öğrenmek için Attribution Reporting API açıklayıcısına göz atın. bir kaynak URL kaydedin.

Android'de ARA, görüntüleme ve tıklama etkinliklerini desteklediğinden InputEvents özellikleri, iki türü birbirinden ayırt etmek için kullanılır. ARA kaynağında olduğu gibi reportEvent() API, platform tarafından doğrulanmış bir çeviriyi Bir tıklama etkinliği olarak InputEvent. InputEvent eksik, null veya geçersizse kaynak kayıt bir görüntüleme olarak kabul edilir.

Açık artırma sonrası eventData içeriğinin hassas bilgiler içerebileceğini unutmayın. platform, yönlendirilen kaynak kaydı isteklerinde eventData öğesini bırakır.

Etkileşim ve dönüşüm raporlama örneği

Bu örnekte, ürün satın almakla ilgilenen ve satın alma uzmanının gözünden açık artırma, oluşturulan reklam ve dönüşüm uygulamasından elde edilen verileri ilişkilendirmede birlikte.

Bu iş akışında alıcı, açık artırmaya benzersiz bir kimlik göndermek için satıcıyla koordinasyon sağlar. Açık artırma sırasında, alıcı bu benzersiz kimliği açık artırma verilerini içerebilir. Oluşturma ve dönüşüm sırasında, oluşturulan reklamdaki veriler de aynı benzersiz kimlikle gönderilir. Benzersiz kimlik daha sonra bu raporları birbirine bağlamak için kullanılabilir.

İş akışı: Açık artırma başlamadan önce, alıcı bunun parçası olarak satıcıya benzersiz bir kimlik gönderir: Programatik gerçek zamanlı teklif verme ("GZT") teklif yanıtı. Kimlik, auctionId gibi bir değişken olarak ayarlanır. Kimlik şurada perBuyerSignals olarak aktarılır: auctionConfig ve alıcının teklif mantığında kullanılabilir hale gelir.

  1. reportWin işlevinin yürütülmesi sırasında alıcı, Reklam oluşturma zamanında ve belirli etkileşim etkinlikleri için tetiklenir (registerAdBeacon()). Bir reklam etkinliği için açık artırma sinyallerini ilişkilendirmek üzere İşaretçi URL'sinin sorgu parametresi olarak auctionId.
  2. Reklam oluşturma süresinde, açık artırma sırasında kaydettiğiniz işaretçiler etkinlik düzeyindeki verilerle tetiklendi veya geliştirildi. Satıcı tetiklemelidir reportEvent() ve etkinlik düzeyindeki verileri iletin. Platform, tetiklenen reportEvent() ile ilişkili olarak alıcının kayıtlı reklam işaretçisi URL'sini pingler.
  3. Alıcı, reklamı Attribution Reporting API'ye şu tarihe kadar kaydeder: reklam işaretçisi isteklerine Attribution-Reporting-Register-Source üstbilgisi. Açık artırma sinyallerini ilişkilendirmek için bir dönüşüm etkinliği için Kayıt kaynak URL'sinde auctionId değerini ayarlayın.

Yukarıdaki işlemin ardından alıcının bir açık artırma raporu vardır. ve dönüşüm raporunu oluşturmak için de Bunlar birbiriyle ilişkilendirmek için kullanılabilecek benzersiz bir kimliktir.

İlişkilendirme verilerine erişmesi gereken satıcılar için benzer bir iş akışı geçerlidir. Satıcı, registerAdBeacon() ile göndermek için benzersiz bir kimlik de kullanabilir. reportEvent() çağrısı, raporu hem alıcıya hem de satıcıya göndermek için kullanılabilecek bir hedef mülkü içerir.

Reklam teknolojisi platformu yönetilen güvenilir sunucu

Günümüzde reklam seçim mantığı, bütçenin tükenmesi gibi anlık bilgiler gerektirir. reklam adaylarının açık artırma için seçilip seçilmeyeceğini belirlemek üzere kullanılır. Her ikisi hem alış hem de satış tarafı platformları bu bilgileri daha iyi olacaktır. Bu sunucular aracılığıyla hassas bilgilerin sızmasını en aza indirmek için öneride aşağıdaki kısıtlamalar yer almaktadır:

  • Bu bölümde daha sonra açıklanan bu sunucuların davranışları, kullanıcı bilgilerini sızdırmaz.
  • Sunucular, gördüğü verilere dayalı anonimleştirilmiş profiller oluşturmaz. yani "güvenilir" olması gerekir.

Alıcı tarafı: Alıcı tarafı, alıcı tarafı teklif verme mantığını başlattığında platform, güvenilir sunucudan güvenilir teklif verme verilerini HTTP getirmesi gerçekleştirir. URL Güvenilir Teklif Verme programında bulunan URL'nin ve anahtarların eklenmesiyle oluşturulur. Oluşturulan özel kitlenin sinyal meta verileri işlendi. Bu getirme, yalnızca cihaz üzerinde özeldeki reklamlar işlenirken yapılır kitleler. Bu aşamada alıcı tarafı bütçeleri uygulayabilir, kampanyanın duraklatma/devre dışı bırakma durumunu kontrol edebilir, hedefleme yapabilir vb.

Aşağıda, özel kitledeki güvenilir teklif verme sinyali meta verilerine dayalı olarak güvenilir teklif verme verilerini almak için kullanabileceğiniz örnek bir URL verilmiştir:

https://www.kv-server.example/getvalues?keys=key1,key2

Sunucudan gelen yanıt; anahtarları anahtar1, anahtar2, vb. ve değerleri alıcının teklif verme işlevleri tarafından kullanılabilir.

Satıcı tarafı: Yukarıdaki alıcı tarafı akışına benzer şekilde, satıcı tarafı getiri açık artırmada dikkate alınan reklam öğeleri hakkındaki bilgiler. Örneğin, bir yayıncı marka güvenliğiyle ilgili endişeler nedeniyle belirli reklam öğelerinin uygulamasında gösterilmemesini zorunlu kılmak isteyebilir. Bu bilgiler getirilebilir ve satıcı tarafı açık artırma mantığına sunulabilir. Alıcı tarafı güvenilir sunucu aramasına benzer şekilde, güvenilir sunucu araması, HTTP getirme kullanılarak da yapılır. URL, Güvenilir Puanlama Sinyalleri URL'sinin, verilerin getirilmesi gereken reklam öğelerinin oluşturma URL'lerine eklenmesi ile oluşturulur.

Aşağıda, reklam öğesi oluşturma URL'lerine göre açık artırmada değerlendirilen reklam öğeleriyle ilgili bilgileri almak için kullanılacak örnek bir URL verilmiştir:

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

Sunucudan gelen yanıt, anahtarları oluşturma URL'leri olan bir JSON nesnesi olmalıdır gönderilir.

Bu sunucular, güvenilir bir şekilde çalışarak çeşitli güvenlik ve gizliliğin avantajları:

  • Sunucunun her anahtar için döndürdüğü değer, yalnızca o tuşa basın.
  • Sunucu, etkinlik düzeyinde günlük kaydı oluşturmaz.
  • Sunucunun bu isteklere dayalı başka yan etkisi yok.

Geçici bir mekanizma olarak, alıcı ve satıcı bu teklifleri alıp kendi çalıştırdıkları sunucu da dahil olmak üzere herhangi bir sunucudan gelen sinyallerden yararlanır. Ancak yayın sürümünde istek yalnızca güvenilir bir anahtar/değer türü sunucuya gönderilir.

Alıcılar ve satıcılar, Android'de Özel Korumalı Alan ile uyumlu platformlar ve web için ortak bir güvenilir anahtar/değer türü sunucu kullanabilir.