Protected Audience API ile özel kitle hedeflemeyi destekleme

Geri bildirim gönderin

Son güncellemeler

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

Protected Audience ile:

  • Ö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çiminden sonra gösterim raporlama uygulayın.

Başlamak için Protected Audience geliştirici kılavuzunu okuyun. Protected Audience'ı geliştirme çalışmalarımız devam ederken geri bildirimleriniz bizim için çok değerlidir.

Zaman Çizelgesi

Önümüzdeki aylarda yeni özellikler kullanıma sunacağız. Kesin yayın tarihleri özelliğe bağlı olarak değişir ve bu tablo, belge bağlantıları kullanıma sunuldukça güncellenecektir.

Öne Çıkarın 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ırması 2023 4. Çeyrek 2023 4. Çeyrek
Para birimi yönetimi 2024 1. Çeyrek 2024 2. Çeyrek
K-anon entegrasyonu Yok 2024 2. Çeyrek
Toplu raporlama entegrasyonu 2024 3. Çeyrek 2024 4. Çeyrek

Genel bakış

Mobil reklamcılıkta reklamverenlerin genellikle, daha önce reklamverenin uygulamasıyla nasıl etkileşime geçtiklerine dayalı olarak ilgi potansiyeli olan kullanıcılara reklam yayınlaması gerekir. Örneğin, SportingGoodsApp uygulamasının geliştiricisi, kullanıcılara satın alma işlemini tamamlamalarını hatırlatacak reklamlar göstererek, alışveriş sepetinde ürünleri kalan kullanıcılara reklam göstermek isteyebilir. Sektörde bu genel fikir genellikle "yeniden pazarlama" ve "özel kitle hedefleme" gibi terimlerle tanımlanmaktadır.

Günümüzde bu kullanım alanları genellikle reklamın nasıl gösterildiğiyle ilgili bağlamsal bilgilerin (uygulama adı gibi) ve özel bilgilerin (ör. kitle listeleri) reklam teknolojisi platformlarıyla paylaşılmasıyla gerçekleştirilmektedir. Reklamverenler bu bilgileri kullanarak sunucularındaki alakalı reklamları seçebilir.

Android'deki Protected Audience API (eski adıyla FLEDGE), reklam teknolojisi platformları ve reklamverenlere yönelik aşağıdaki API'leri kapsar. Bu API'ler, uygulamalar arasında hem tanımlayıcıların hem de kullanıcının uygulama etkileşimi bilgilerinin üçüncü taraflarla paylaşımını sınırlayacak şekilde yaygın etkileşim tabanlı kullanım alanlarını desteklemek için kullanılır:

  1. Custom Audience API: Bu, reklamveren tarafından ortak amaçlara sahip olan bir kitleyi temsil eden "özel kitle" soyutlamasına odaklanır. Kitle bilgileri cihaz üzerinde depolanır, kitlenin alakalı aday reklamlarıyla ve teklif sinyalleri gibi rastgele meta verilerle ilişkilendirilebilir. Bu bilgiler reklamveren teklifleri, reklam filtreleme ve oluşturma hakkında bilgi sağlamak için kullanılabilir.
  2. Reklam Seçimi API'si: Bu, yerel olarak depolanan aday reklamları dikkate alarak ve bir reklam teknolojisi platformunun cihaza döndürdüğü aday reklamlarda ek işlemler gerçekleştirerek "kazanan" bir reklamı belirlemek için cihaz üzerindeki sinyallerden yararlanan reklam teknolojisi platformlarının iş akışlarını düzenleyen bir çerçeve sunar.
Android'deki Özel Korumalı Alan'daki özel kitle yönetimi ve reklam seçimi iş akışını gösteren akış grafiği.

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

  1. SportingGoodsApp, satın alma işlemini 2 gün içinde tamamlamayan kullanıcılarına, alışveriş sepetlerinde kalan ürünleri satın almalarını hatırlatmak istiyor. SportingGoodsApp, kullanıcıyı "alışveriş sepetindeki ürünler" kitle listesine eklemek için Custom Audience API'yi kullanıyor. Platform, bu kitle listesini cihazda yönetip depolayarak üçüncü taraflarla paylaşımı sınırlandırır. SportingGoodsApp, reklamlarını kitle listesindeki kullanıcılara göstermek için bir reklam teknolojisi platformuyla iş ortaklığı yapıyor. Reklam teknolojisi platformu, kitle listelerinin meta verilerini yönetir ve değerlendirilmek üzere reklam seçimi iş akışına sunulan aday reklamları sağlar. Platform, arka planda güncellenmiş kitleye dayalı reklamları düzenli olarak getirecek şekilde yapılandırılabilir. Bu, kitleye dayalı aday reklamların listesinin, reklam fırsatı sırasında (ör. içeriğe dayalı reklam isteği) üçüncü taraf reklam sunucularına gönderilen isteklerle güncel ve ilişkili olmamasına yardımcı olur.

  2. Kullanıcı aynı cihazda FrisbeeGame'i oynadığında, SportingGoodsApp'in alışveriş sepetinde kalan ürünleri satın almalarını hatırlatan bir reklam görebilir. Bu, FrisbeeGame (Entegre reklam SDK'sı ile) ile Reklam Seçimi API'sini çağırarak kullanıcının üyesi olabileceği herhangi bir kitle listesine (bu örnekte SportingGoodsApp tarafından oluşturulan "alışveriş sepetindeki ürünler" özel kitlesi) göre kazanan bir reklam seçmesi ile sağlanabilir. Reklam seçimi iş akışı, reklam teknolojisi platformlarının sunucularından alınan reklamların yanı sıra özel kitlelerle ilişkili cihaz üzerindeki reklamları ve diğer cihaz sinyallerini dikkate alacak şekilde ayarlanabilir. İş akışı, uygun reklamcılık hedeflerine ulaşmak için reklam teknolojisi platformu ve reklam SDK'sı tarafından özel teklif verme ve puanlama mantığıyla da özelleştirilebilir. Bu yaklaşım, kullanıcının ilgi alanı veya uygulama etkileşimi verilerinin reklam seçiminde bilgi sağlamasına olanak tanırken bu verilerin üçüncü taraflarla paylaşımını sınırlandırır.

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

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

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 Özel Korumalı Alan hesabına kaydolma bölümüne bakın.

Özel kitle yönetimi

Özel kitle

Özel kitle, reklamveren tarafından ortak amaçlara veya ilgi alanlarına sahip olan bir kullanıcı grubunu temsil eder. Uygulamalar veya SDK'lar, "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 bir kitle kullanabilir. Platform, kitle bilgilerini cihazda yerel olarak tutar ve depolar ve kullanıcının hangi özel kitlelerde olduğunu göstermez. Özel kitleler, Chrome'un Protected Audience ilgi alanı gruplarından farklıdır ve web ile uygulamalar arasında paylaşılamaz. Bu, kullanıcı bilgilerinin paylaşımının sınırlanmasına yardımcı olur.

Bir reklamveren uygulaması veya entegre SDK, örneğin bir uygulamadaki kullanıcı etkileşimine bağlı olarak özel bir kitleye join 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 ad, arayan uygulamanın paket adına dolaylı olarak ayarlanır.
  • Alıcı: Bu özel kitle için reklamları yöneten alıcı reklam ağı. Alıcı ayrıca, özel kitleye erişebilecek ve alakalı reklam bilgilerini alabilecek tarafı temsil eder. Alıcı, eTLD+1 biçimiyle belirtilir.
  • Ad: Özel kitle için rastgele bir ad veya tanımlayıcı (örneğin, "alışveriş sepetini terk edenler" içeren bir kullanıcı). Bu özellik, örneğin, reklamverenin reklam kampanyalarındaki hedefleme ölçütlerinden biri veya teklif kodunu getirmek için URL'deki bir sorgu dizesi olarak kullanılabilir.
  • Etkinleştirme zamanı ve geçerlilik bitiş zamanı: Bu alanlar, özel kitlenin etkili olacağı zaman aralığını tanımlar. Platform, bu bilgileri özel bir kitleden üyelik iptali için kullanır. Geçerlilik süresi, özel bir kitlenin ömrünü sınırlamak için bir maksimum süre aralığını aşamaz.
  • Günlük güncelleme URL'si: Platformun, aday reklamları ve "Kullanıcı teklif verme sinyalleri" ve "Güvenilir teklif sinyalleri" alanlarında tanımlanan diğer meta verileri düzenli olarak getirmek 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 verme sinyalleri:Yeniden pazarlama reklamlarının tüm teklifleri için reklam teknolojisi platformuna özgü sinyaller. Sinyallere örnek olarak kullanıcının yaklaşık konumu, tercih ettiği yerel ayar vb. verilebilir.
  • Güvenilir teklif verileri: Reklam teknolojisi platformları, reklam alma ve puanlama bilgileri için gerçek zamanlı verilerden yararlanır. Örneğin, bir Reklam'ın bütçesi tükenebilir ve reklam yayınının hemen durdurulması gerekir. Bir reklam teknolojisi, bu gerçek zamanlı verilerin getirilebileceği bir URL uç noktası ve gerçek zamanlı aramanın gerçekleştirilmesi gereken anahtar kümesini tanımlayabilir. Bu isteği işleyen sunucu, reklam teknolojisi platformu tarafından yönetilen güvenilir bir sunucu olacaktır.
  • Teklif verme mantığı URL'si: Platformun talep tarafı platformundan teklif kodunu getirmek için kullandığı URL. Platform, bu adımı bir reklam açık artırması başlatıldığında gerçekleştirir.
  • Reklamlar: Özel kitle için aday reklamların listesi. Buna reklam teknolojisi platformuna özel reklam meta verileri ve reklamı oluşturacak bir URL dahildir. Özel kitle için bir açık artırma başlatıldığında bu reklam meta verileri listesi dikkate alınır. Bu reklam listesi, uygun durumlarda günlük güncelleme URL'si uç noktası kullanılarak yenilenecektir. Mobil cihazlardaki kaynak kısıtlamaları nedeniyle, özel bir kitlede depolanabilecek reklam sayısı sınırlıdır.

Özel kitle yetkisi

Geleneksel özel kitle tanımı ve yapılandırması genellikle ajans, reklamveren müşterileri ve iş ortaklarıyla reklam teknolojileri tarafından geliştirilen sunucu tarafı teknolojilere ve entegrasyonlara dayanır. Protected Audience API, kullanıcı gizliliğini korurken özel kitle tanımı ve yapılandırması sağlar. Özel bir kitleye katılmak için uygulamalarda SDK varlığı olmayan alıcı reklam teknolojilerinin, mobil ölçüm iş ortakları (MMP'ler) ve arz tarafı platformları (SSP'ler) gibi cihaz üzerinde varlığı olan reklam teknolojileriyle iş birliği yapması gerekir. Protected Audience API, cihazda arayanların alıcılar adına özel kitle oluşturmayı çağırmasını sağlayarak özel kitle yönetimi için esnek çözümler sunarak bu SDK'ları desteklemeyi amaçlar. Bu sürece özel kitle yetkisi denir. Özel kitle yetkilendirmesini yapılandırmak için:

Özel kitleye katılın

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

joinCustomAudience()

Bir uygulama veya SDK, beklenen parametrelerle CustomAudience nesnesini örnekledikten sonra joinCustomAudience() yöntemini çağırarak özel 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 olduğu gibi beklenen parametrelerle fetchAndJoinCustomAudience() çağırarak cihazda 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ı, yanıt gövdesinde bir CustomAudience JSON nesnesiyle yanıt verir. Özel kitlenin alıcı ve sahip alanları yoksayılır (ve API tarafından otomatik olarak doldurulur). API, günlük güncelleme URL'sinin de alıcının eTLD+1'iyle eşleşmesini de zorunlu kılar.

{
 "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, alıcının kimliğini fetchUri eTLD+1'inden belirler. CustomAudience alıcısının 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 sahibi, çağrı uygulamasının paket adıdır. fetchUri için eTLD+1 kontrolü dışında başka bir doğrulama yoktur ve özellikle k-anon kontrolü yoktur. fetchAndJoinCustomAudience() API, fetchUri adresine bir HTTP GET isteği gönderir ve özel kitleyi temsil eden bir JSON nesnesini bekler. Özel kitle nesnesi alanları için aynı zorunlu, isteğe bağlı kısıtlamalar ve varsayılan değerler yanıta uygulanır. Mevcut koşullar ve sınırlamalar hakkında bilgi edinmek için Geliştirici Kılavuzumuzu inceleyin.

Alıcıdan gelen herhangi bir HTTP hatası yanıtı fetchAndJoinCustomAudience ürününün başarısız olmasına neden olur. Özellikle 429 (Çok Fazla İstek) HTTP durum yanıtı, tanımlanacak süre boyunca mevcut uygulamadan gelen istekleri engeller. Alıcıdan gelen yanıt hatalıysa API çağrısı da başarısız olur. Geçici hatalar (sunucunun yanıt vermemesi gibi) nedeniyle veya kalıcı hataları (ör. veri doğrulama hataları ya da sunucuyla iletişimle ilgili geçici olmayan diğer hatalar) ele almaktan sorumlu API çağrısına hata bildiriminde bulunur.

CustomAudienceFetchRequest nesnesi, API çağrısını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 platformun aldığı alıcı yanıtını bu değerlerin üzerine yazamaz. Protected Audience API, yanıttaki alanları yok sayar. Özel bir kitle oluşturmak için bu alanlar gerekli olduğundan, istekte ayarlanmamışsa bunların yanıtta ayarlanması gerekir. API çağrısı tarafından kısmen tanımlanan CustomAudience içeriğinin JSON gösterimi, fetchUri özel üstbilgisindeki GET isteğine X-CUSTOM-AUDIENCE-DATA dahil edilir. Özel Kitle için belirtilen verilerin serileştirilmiş biçiminin boyutu 8 KB ile sınırlıdır. Boyut aşılırsa fetchAndJoinCustomAudience API çağrısı başarısız olur.

K-anon kontrolünün 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ı bir doğrulama jetonu sağlayabilir. Alıcı tarafından barındırılan uç noktanın, özel kitlenin içeriğini getirebilmesi ve fetchAndJoinCustomAudience() işleminin alıcıya karşılık geldiğini ve cihaz üzerindeki güvenilir bir iş ortağından kaynaklandığını doğrulamak için doğrulama jetonunu kullanabilmesi için cihaz üzerinde SDK'nın fetchUri bölümünde bu jetonu içermesi gerekir. Alıcı, bilgi paylaşmak amacıyla cihaz üzerinde arayanla, özel kitleyi oluşturmak için kullanılacak bazı bilgilerin fetchUri öğesine sorgu parametreleri olarak ekleneceği konusunda anlaşabilir. Bu, alıcının çağrıları denetlemesine ve kötü amaçlı bir reklam teknolojisinin birkaç farklı özel kitle oluşturmak için doğrulama jetonunun kullanılıp kullanılmadığını tespit etmesine olanak tanır.

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

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

    • Doğrulama jetonu, alıcı tarafından, oluşturulan kitlelerin kendisi adına gerçekleştirildiğini doğrulamak amacıyla kullanılabilir.
    • Protected Audience API teklifi, doğrulama jetonu için bir biçim veya alıcının doğrulama jetonunu arayana nasıl aktardığını belirtmez. Örneğin, doğrulama jetonu sahibinin SDK'sı veya arka ucunda önceden yüklenmiş olabilir ya da alıcının sunucusundan sahibin SDK'sı tarafından gerçek zamanlı olarak alınabilir.

Özel kitleden ayrılma

Özel bir kitlenin sahibi, aşağıdaki açıklayıcı kod snippet'inde gösterildiği gibi leaveCustomAudience() öğesini çağırarak ayrılmayı tercih edebilir:

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

Depolama alanı ve diğer cihaz kaynaklarının kullanımını korumak için özel kitlelerin süresi dolar ve önceden belirlenmiş bir süre sonra 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

  • Teklif, kullanıcılara en az bir özel kitle oluşturmuş yüklü uygulamaların listesini göstermeyi amaçlar.
  • Kullanıcılar bu listeden uygulama kaldırabilir. Kaldırma işlemi, uygulamalarla ilişkili tüm özel kitleleri temizler ve uygulamaların yeni özel kitlelere katılmasını engeller.
  • Kullanıcılar, Protected Audience API'yi tamamen sıfırlayabilir. Bu durumda cihazdaki mevcut özel kitleler temizlenir.
  • Kullanıcılar, Android'de, Protected Audience API'yi içeren Ö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 özelliğin tasarımı hâlâ devam etmektedir ve ayrıntılar daha sonraki bir güncellemeye eklenecektir.

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 doğrudan veya yetkiyi kullanarak özel kitlenin tüm özelliklerini sunmasını gerektirir. Ancak reklamverenlerin ve reklam teknolojisi sağlayıcıların, bir kullanıcının hangi kitleleri uygulama kullanırken gerçek zamanlı olarak ait olduğunu tanımlamaları her zaman mümkün değildir.

Bunu kolaylaştırmak için reklam teknolojisi scheduleCustomAudienceUpdate() API'yi çağırabilir. Bu API, çağrıyı yapanı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şlemesi ve kullanıcının hangi Korumalı Kitlelere katılması veya kaldırılması gerektiğini belirlemesi için ek süre sağlanır.

/**
* API To schedule delayed update events for Custom Audience
*
* @param delayedCustomUpdates List of Delayed Update events that trigger a
* call to DSP endpoint provided inside the DelayedCustomUpdate object
*/

public void scheduleCustomAudienceUpdates(
    @NonNull DelayedCustomUpdate delayedCustomAudienceUpdate,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

DelayedCustomAudienceUpdate

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

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

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

DelayedCustomAudienceUpdate, gecikmeli bir işin platformda çalışması için gerekli kaydı içerir. Belirtilen gecikmenin ardından arka plan işi düzenli olarak çalışır ve istekleri gönderir. DelayedCustomAudienceUpdate aşağıdaki bilgileri içerebilir:

  • UpdateUri: Güncellemeyi getirmek için GET çağrısı gönderilecek URI uç noktası. Alıcı kimliği, doğal olarak eTLD+1'den tahmin edilir, açık bir şekilde sağlanması gerekmez ve güncelleme yanıtı tarafından değiştirilemez. GET isteği, karşılığında 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 yaşanan gecikmeyi belirten zaman.

  • PartialCustomAudience: API, cihaz üzerindeki SDK'nın kısmen oluşturulmuş Özel Kitleler'in bir listesini göndermesine de olanak tanır. Bu, uygulama içi SDK'ların TTP'lerle iş ortaklıklarına dayalı olarak Özel Kitle yönetimi üzerinde tam kontrolden kısmi kontrole kadar iki rolü üstlenir.

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

Uygulama izinleri ve denetim

Bu teklif, uygulamaların kendi özel kitleleri üzerinde kontrol sahibi olmasını sağlamayı amaçlar:

  • Uygulamalar, özel kitlelerle ilişkilendirmelerini yönetebilir.
  • Bir uygulama, üçüncü taraf reklam teknolojisi platformlarına kendi adına özel kitleleri yönetme izni verebilir.

Bu özelliğin tasarımı hâlâ devam etmektedir ve ayrıntılar daha sonraki bir güncellemeye eklenecektir.

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 kitle için tüm URL'lerle eşleşen bir eTLD+1 alanı sağlar.
  • Reklam teknolojileri, özel bir kitle oluşturmayı doğrulamak için kullanılan doğrulama jetonları sağlamak için uygulamalarla veya SDK'larla iş ortaklığı yapabilir. Bu işlem bir iş ortağına yetki verildiğinde, özel kitle oluşturma işlemi reklam teknolojisinin onayını gerektirecek şekilde yapılandırılabilir.
  • Bir reklam teknolojisi, joinCustomAudience çağrılarını kendi adına devre dışı bırakmayı ve yalnızca fetchAndJoinCustomAudience API'nin tüm çağrı özel kitlelerini etkinleştirmesine izin vermeyi seçebilir. Kontrol, Özel Korumalı Alan kaydı sırasında güncellenebilir. Bu kontrolün tüm reklam teknolojilerine izin verdiğini veya hiçbirine izin vermediğini unutmayın. Platform sınırlamaları 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 aşağıdaki alanları içermelidir:

  • Meta veriler: Alıcı tarafı, reklam teknolojisine özel reklam meta verileri. Örneğin, bu bilgiler reklam kampanyasıyla ilgili bilgileri ve konum ile dil gibi hedefleme ölçütlerini içerebilir.
  • Oluşturma URL'si: Reklam öğesini oluşturmak için uç nokta.
  • Filtreleme: Protected Audience API'nin reklamları cihaz üzerindeki verilere göre filtrelemesi için gereken isteğe bağlı bilgiler. Daha ayrıntılı 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 düzenleyen Reklam Seçimi API'sini kullanıma sunarak gizliliği artırmayı amaçlar.

Günümüzde reklam teknolojisi platformları, teklif verme ve reklam seçimini genellikle yalnızca kendi sunucularında gerçekleştirir. Bu teklifle, özel kitlelere ve diğer hassas kullanıcı sinyallerine (ör. mevcut yüklü paket bilgileri) yalnızca Reklam Seçimi API'si üzerinden erişilebilecektir. Buna ek olarak, yeniden pazarlama kullanım alanında aday reklamlar bant dışına getirilir (yani reklamların gösterileceği bağlamda gösterilmez). Reklam teknolojisi platformlarının, mevcut açık artırma ve reklam seçimi mantığının bazı bölümlerinin cihazda dağıtılması ve yürütülmesi için hazırlanmaları gerekir. Reklam teknolojisi platformları, reklam seçimi iş akışlarında aşağıdaki değişiklikleri dikkate alabilir:

  • Sunucuda yüklü paket bilgileri olmadan, reklam teknolojisi platformları cihaza birden fazla bağlamsal reklam göndermek ve alakalı bir reklam gösterme olasılığını en üst düzeye çıkarmak için uygulama yüklemeye dayalı filtrelemeyi etkinleştirmek üzere reklam seçimi iş akışını çağırmak isteyebilir.
  • Yeniden pazarlama reklamları bant dışından getirildiğinden mevcut teklif verme modellerinin güncellenmesi gerekebilir. Reklam teknolojisi platformları, reklam özellikleri ve içerik sinyalleri üzerinde ayrı ayrı çalışabilen ve teklifleri tahmin etmek için cihazdaki alt model çıkışlarını birleştirebilen teklif alt modelleri (iki kule modeli adı verilen bir kalıpa dayalı olabilir) oluşturmak isteyebilir. Bu, herhangi bir reklam fırsatı için hem sunucu tarafı açık artırmalardan hem de açık artırmalardan yararlanabilir.

Bu yaklaşım, kullanıcının uygulama etkileşimleri verilerinin reklam seçimine yön vermesini sağlar ve bu verilerin üçüncü taraflarla paylaşımı sınırlandırılır.

Reklam seçimi iş akışının başlatıldığını gösteren akış grafiği.

Bu reklam seçimi iş akışı, reklam teknolojisi tarafından sağlanan JavaScript kodunun cihaz üzerinde yürütülmesini aşağıdaki sıraya göre düzenler:

  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, özel kitlenin "Teklif verme mantığı URL'si" meta verileri tarafından tanımlanan herkese açık URL uç noktasına göre satın alma tarafında sağlanan JavaScript kodunu getirir. Satış tarafı karar kodu için URL uç noktası da reklam seçimi iş akışını başlatmak için bir giriş olarak iletilir.

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

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

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

  • Satıcı: eTLD+1 biçimine uygun, satıcı tarafı reklam platformu için tanımlayıcı
  • Karar mantığı URL'si: Bir reklam açık artırması başlatıldığında platform, kazanan reklamı puanlamak amacıyla satıcı tarafı platformundan JavaScript kodu getirmek için bu URL'yi kullanır.
  • Özel kitle alıcıları: Bu açık artırma için eTLD+1 biçimine göre özel kitleye dayalı talebe sahip alıcı tarafı platformlarının listesi.
  • Reklam seçimi sinyalleri: Açık artırmayla ilgili bilgiler (reklam boyutu, reklam biçimi vb.).
  • Satıcı sinyalleri: Arz tarafı platformuna özel sinyaller.
  • Güvenilir Puanlama Sinyalleri URL'si: Reklam öğesine özgü gerçek zamanlı bilgilerin alınabileceği satıcı tarafı güvenilir sinyalinin URL uç noktası.
  • Alıcıya göre sinyaller: Katılımcı talep tarafları, açık artırmaya giriş sağlamak için bu parametreyi kullanabilir. Örneğin, bu parametre teklifleri belirlemek için faydalı kapsamlı bağlamsal bilgiler içerebilir.

Aşağıdaki açıklayıcı kod snippet'i, önce AdSelectionConfig tanımlayıp ardından kazanan reklamı almak için selectAds yöntemini çağırarak reklam seçim iş akışını başlatan bir reklam teknolojisi platformu SDK'sını göstermektedir:

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. Kodun amacı, aday reklamlar için teklifleri belirlemektir. Sonucu belirlemek için ek iş mantığı uygulayabilir.

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

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, tüm reklamlar (içeriğe dayalı veya yeniden pazarlama) için bu işlevi sırayla çağırır. Birden fazla teklif 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, reklam grubu genelinde uygun bir özel kitleden
  • Açık artırma sinyalleri: Satış tarafı, platforma özel sinyaller.
  • Alıcıya göre sinyaller: Katılımcı talep tarafları, açık artırmaya giriş sağlamak için bu parametreyi kullanabilir. Örneğin, bu parametre teklifleri belirlemek için faydalı kapsamlı bağlamsal bilgiler içerebilir.
  • Güvenilir teklif sinyalleri: Reklam teknolojisi platformları, reklamların alınması ve puanlanması için gerçek zamanlı verilerden yararlanır. Örneğin, bir reklam kampanyasının bütçesi tükenebilir ve reklam yayınının hemen durdurulması gerekir. Bir reklam teknolojisi, bu gerçek zamanlı verilerin getirilebileceği bir URL uç noktası ve gerçek zamanlı aramanın gerçekleştirilmesi gereken anahtar kümesini tanımlayabilir. Reklam teknolojisi platformunun bu isteği yerine getiren yönetilen sunucusu, reklam teknolojisi platformu tarafından yönetilen güvenilir bir sunucu olacaktır.
  • Bağlamsal sinyaller: Bu veriler arasında, yaklaşık zaman damgası, yaklaşık konum bilgisi veya reklamın tıklama başına maliyeti yer alabilir.
  • 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 de döndürebilir. Örneğin:

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

Kazanan reklamsa adCost, gizlilik için sakıncalı olarak 8 bite yuvarlanır. Daha sonra adCost işlevinin yuvarlatılmış değeri, gösterim raporlama sırasında reportWin içindeki contextual_signals parametresine iletilir.

Alıcı tarafı filtreleme mantığı

Alıcı tarafı platformlar, reklam seçimi aşamasında kullanılabilen ek cihaz üzerindeki sinyallere göre reklamları filtreleyebilecek. Örneğin, reklam teknolojisi platformları sıklık sınırı özelliklerini burada uygulayabilir. Birden fazla filtreleme sağlayıcısı varsa sistem, sağlayıcılar arasında yürütme sırasını garanti etmez.

Alıcı tarafı filtreleme mantığı, belirli bir reklam için 0 teklif değeri döndürülerek teklif mantığının bir parçası olarak uygulanabilir.

Buna ek olarak, alıcı tarafı platformları belirli bir reklamın Protected Audience tarafından kullanılabilen ek cihaz üzerindeki sinyallere göre filtrelenmesi gerektiğini ve cihazın dışına çıkmamasını bildirebilir. Ek filtreleme mantığının tasarımlarını sağlamlaştırdıkça alıcı tarafı platformları da filtrelemenin yapılması gerektiğini belirtmek için aynı yapıyı izler.

Satıcı tarafı puanlama mantığı

Puanlama mantığı genellikle satış tarafı platformu tarafından sağlanır. Kodun amacı, teklif verme mantığı çıkışlarına göre kazanan reklamı belirlemektir. Sonucu belirlemek için ek iş mantığı uygulayabilir. Birden fazla karar mantığı sağlayıcısı varsa sistem, sağlayıcılar arasında yürütme sırasını garanti etmez. Platform, aşağıdaki işlev imzasını içermesi gereken JavaScript kodunu getirmek 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 parametrelerin olmasını bekler:

  • Reklam: Değerlendirilen reklam; generateBid() işlevinden elde edilir.
  • 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 hakkında bilgi vermek 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 konum bilgilerini içerebilir.
  • Kullanıcı sinyali: Uygulamanın yüklenmesini başlatan uygulama mağazası gibi bilgiler bu kapsamda yer alabilir.
  • Özel kitle sinyali: Puanlanan reklam, cihaz üzerindeki özel bir kitleden geliyorsa bu, özel kitlenin okuyucusu ve adı gibi bilgileri içerir.

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

Teklifte sistem, yapılandırılabilir URL uç noktalarından reklam teknolojisi platformu tarafından sağlanan açık artırma kodunu getirecek ve cihazda yürütülecektir. Mobil cihazlardaki kaynak kısıtlamaları göz önünde bulundurulduğunda, açık artırma kodunun aşağıdaki kurallara uygun olması gerekir:

  • 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 eşit şekilde uygulanır. Bu sınırın ayrıntıları daha sonraki bir güncellemede paylaşılacaktır.
  • Kodun bağımsız olması ve herhangi bir dış bağımlılığı olmaması gerekir.

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

Programlama dili

Reklam teknolojisi platformu tarafından sağlanan açık artırma kodu JavaScript'te yazılmalıdır. Bu sayede reklam teknolojisi platformları, örneğin Özel Korumalı Alan'ı destekleyen platformlarda teklif kodu paylaşabilir.

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 geçirilir.

Plan, kullanıcının özel kitle üyeliği veya uygulama etkileşim geçmişi hakkındaki bilgilerin, kazanan reklamla ilgili bilgiler aracılığıyla uygulama veya SDK tarafından belirlenememesini (Chrome'un çizli çerçeveler teklifine benzer) sağlayacak şekilde geliştirmektir.

Gösterim ve etkinlik raporlama

Reklam oluşturulduktan sonra kazanan gösterim, katılımcı alıcı ve satış tarafı platformlarına geri raporlanabilir. Bu sayede alıcılar ve satıcılar, kazanan gösterim raporuna açık artırmadaki bilgileri (ör. teklif veya özel kitle adı) ekleyebilir. Ayrıca satış tarafı ve kazanan alıcı tarafı platformu, kazanan reklam hakkında etkinlik düzeyinde ek raporlar almaya uygundur. Bu; tıklamalar, görüntülemeler ve diğer reklam etkinlikleriyle açık artırma hakkında bilgi (teklif, özel kitle adı vb.) ekleme olanağı sağlar. Platform, raporlama mantığını şu sırayla çağırır:

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

Bu sayede alıcı ve satış tarafı platformları gerçek zamanlı bütçe oluşturma, teklif modeli güncellemeleri ve doğru faturalandırma iş akışları gibi özellikleri etkinleştirmek için cihaz üzerindeki önemli bilgileri sunuculara geri gönderebilir. Bu gösterim raporlama desteği, Attribution Reporting API'yi tamamlayıcı niteliktedir.

Etkinlik raporlamasını desteklemek için gereken iki adım vardır: Satış tarafı ve alıcı tarafı JavaScript'in hangi etkinlik için etkinlik raporu alması gerektiğini kaydetmesi gerekir. Satış tarafı ise etkinlik düzeyindeki bilgileri raporlamaktan sorumludur.

Protected Audience, işaretçileri kaydederek kazanan bir açık artırmayla ilgili gelecekteki etkinliklere abone olmak için bir mekanizma sağlar. Satıcının reportResult() JavaScript işlevinde, satış tarafı platformları, platformun registerAdBeacon() işlevini kullanarak işaretçileri kaydedebilir. Benzer şekilde, alıcı tarafı platformları reportWin() JavaScript işlevinden registerAdBeacon() yöntemini çağırabilir.

registerAdBeacon(beacons)

Giriş:

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

Etkinlik anahtarları, açık artırmanın sonuçlarını raporlamaktan sorumlu satıcı tarafı SDK'sının sahip olduğu dize tanımlayıcılarıdır. Geri çağırmanın yapılması için reklam teknisyenleri, etkinlikleri bildirirken satış tarafının kullandığı anahtarlarla eşleşen anahtarlarla işaretçileri kaydeder. Bunların k-anonim olması gerekmez ancak belirli bir özel kitle için kaydedilebilecek anahtarların miktarı ve uzunluğuyla ilgili sınırlar söz konusudur. reportEvent() çağrılırsa açık artırmayı yürüten satıcı tarafı platformları her zaman bu etkinlik raporlarını alabilir. Yalnızca kazanan alıcı tarafı platformu bu raporları alabilir.

Satıcı tarafı raporları

Platform, selectAds() API için satıcının Karar mantığı URL'si 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}};
}

Çıkış: Aşağıdakileri içeren bir JSON nesnesi

  • 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.
  • Alıcı için sinyaller: Alıcının reportWin işlevine iletilecek bir JSON nesnesi.

Arz tarafı, açık artırma ve kazanan reklamla ilgili daha fazla bilgi edinmelerine yardımcı olmak için raporlama URL'sinde ilgili sinyalleri kodlayabilir. Örneğin, rapor aşağıdaki sinyalleri içerebilir:

  • Reklam oluşturma URL'si
  • Kazanan teklif tutarı
  • Uygulama adı
  • Sorgu tanımlayıcıları
  • Alıcıya yönelik sinyaller: Platform, arz tarafı ve talep tarafı arasında veri paylaşımını desteklemek için bu döndürme değerini, talep tarafı raporlama koduna giriş parametresi olarak iletir.

Alıcı tarafı raporlama

Platform, açık artırmayla ilişkili özel kitlenin Teklif mantığı URL'si meta verilerinden indirilen talep tarafı tarafından sağlanan kodda reportWin() JavaScript işlevini çağırır.

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, AuctionConfig kaynağından getirilir. Alıcı tarafı platformunun raporlama URL'sine iletmesi gereken tüm bilgiler bu veriden gelebilir.
  • signals_for_buyer, satıcı tarafı reportResult'ın çıktısıdır. Bu, satış tarafı platformuna raporlama amacıyla alıcı tarafı platformuyla veri paylaşma fırsatı sağlar.
  • contextual_signals, uygulama adı gibi bilgileri, custom_audience_signals ise özel kitle bilgilerini içeriyor. İleride başka bilgiler de 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 Raporlama

Etkinliklerin raporlanması, yalnızca açık artırma için gösterim raporlama tamamlandıktan sonra yapılabilir. Satıcı tarafı SDK'sı tüm etkinlikleri raporlamaktan sorumludur. Platform, son yapılan açık artırmayı, raporlanan etkinlik anahtarını, bu anahtarla ilişkilendirilen verileri, raporun alıcıya mı yoksa satıcıya mı (ya da her ikisine birden) gönderileceğini belirten ReportEventRequest ve reklam etkinlikleri için isteğe bağlı bir giriş etkinliğini alan bir API sunar. Müşteri, etkinlik anahtarını ve raporlanacak verilerin toplanmasını 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, AdSelectionOutcome kaynağından yakın zamanda alınan bir açık artırmanın AdSelectionId değeri olmalıdır.
  • event_key, etkileşim etkinliğini açıklayan satıcı tarafı tanımlı bir dizedir.
  • event_data, event_key ile ilişkili verileri temsil eden bir dizedir.
  • reporting_destinations, platform tarafından sağlanan flag'leri kullanan bir bit maskesi grubudur. FLAG_REPORTING_DESTINATION_SELLER veya FLAG_REPORTING_DESTINATION_BUYER ya da her ikisi olabilir.
  • Attribution Reporting API ile entegrasyon için input_event (isteğe bağlı) kullanılır. Bu bir InputEvent nesnesidir (tıklama etkinliği için) veya null (görüntüleme etkinliği için). Bu parametre hakkında daha fazla ayrıntı için Attribution Reporting API Entegrasyonu'na bakın.

Satıcı tarafı SDK'sı reportEvent işlevini çağırdıktan sonra ve reporting_destinations işaretine bağlı olarak platform, event_key öğesini alıcılar ve satıcılar tarafından reportWin ve reportResult JavaScript işlevlerinde kaydedilen anahtarlarla eşleştirmeye çalışır. Eşleşme varsa platform, event_data öğesini ilişkili reporting_url öğesine POSTA gönderir. İsteğin içerik türü, gövdenin event_data olduğu düz metindir. Bu istek, mümkün olan en iyi şekilde yapılır ve ağ hatası, sunucu hatası yanıtı veya eşleşen anahtar bulunamazsa sessizce başarısız olur.

Attribution Reporting API entegrasyonu

Protected Audience açık artırmasına katılan alıcıları desteklemek için Protected Audience ve Attribution Reporting API'lerde (ARA) API'ler arası işlevler sağlıyoruz. Bu işlev, reklam teknolojilerinin çeşitli yeniden pazarlama taktiklerinde ilişkilendirme performanslarını değerlendirebilmelerini sağlar. Böylece, hangi kitle türlerinin en yüksek YG'yi sağladığını anlayabilirler.

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

  • Hem 1) reklam etkileşimi raporlaması hem de 2) kaynak kaydı için kullanılacak bir anahtar/değer çifti eşlemesi oluşturun.
  • Toplu özet raporlama için Protected Audience açık artırmasının açık artırma verilerini kaynak tarafı anahtar eşlemesine dahil edin (Attribution Reporting API'yi kullanarak). Daha fazla bilgi için ARA tasarım teklifine bakın.

Bir 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ıklamayı Attribution Reporting API ile uygun bir kaynak olarak kaydetmek üzere kullanılacak olan gerekli verileri sağlar.
  • Reklam teknolojisi, CustomAudience URL'sini kullanarak CustomAudience (veya reklam yerleşimi ya da görüntüleme süresi gibi alakalı içerik bilgileri) iletmeyi tercih edebilir. Böylece, reklam teknolojisi toplu kampanya performansını incelerken bu meta veriler özet raporlara yayılabilir.

Kaynak kaydını etkinleştirme

reportEvent(), isteğe bağlı yeni InputEvent parametresini kabul edecek. Reklam işaretçileri kaydeden kazanan alıcılar, hangi reportEvent raporlarının, Attribution Reporting API'lere kayıtlı kaynak olarak kaydedileceğini seçebilir. reportEvent() tarafından gönderilen tüm etkinlik raporlama isteklerine, Attribution-Reporting-Uygun istek başlığı eklenecek. Uygun ARA başlıklarına sahip yanıtlar, diğer herhangi bir normal ARA kaynak kaydı yanıtıyla aynı şekilde ayrıştırılır. Kaynak URL'yi kaydetme hakkında bilgi edinmek için Attribution Reporting API açıklayıcısını inceleyin.

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

Açık artırma sonrası eventData hassas bilgiler içerebileceği için platformun yönlendirilen kaynak kaydı isteklerinde eventData öğesini bıraktığını unutmayın.

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

Bu örnekte, verileri açık artırmadaki, oluşturulan reklamdaki ve dönüşüm uygulamasındaki verileri ilişkilendirmek isteyen alıcı gözünden inceleyeceğiz.

Bu iş akışında, alıcı, açık artırmaya benzersiz bir kimlik göndermek için satıcıyla koordineli çalışır. Açık artırma sırasında alıcı, açık artırma verileriyle birlikte bu benzersiz kimliği gönderir. Oluşturulan reklamdan elde edilen veriler, oluşturma ve dönüşüm sırasında aynı benzersiz kimlikle gönderilir. Daha sonra, bu raporları birbiriyle ilişkilendirmek için benzersiz kimlik kullanılabilir.

İş akışı: Açık artırma başlamadan önce alıcı, programatik gerçek zamanlı teklif verme ("GZT") teklif yanıtının parçası olarak satıcıya benzersiz bir kimlik gönderir. Kimlik, auctionId gibi bir değişken olarak ayarlanabilir. Kimlik, auctionConfig içinde perBuyerSignals olarak iletilir 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 süresi sırasında ve belirli etkileşim etkinlikleri (registerAdBeacon()) için tetiklenecek bir reklam işaretçisi kaydedebilir. Bir reklam etkinliğinin açık artırma sinyallerini ilişkilendirmek için auctionId özelliğini, işaretçi URL'sinin sorgu parametresi olarak ayarlayın.
  2. Reklam oluşturma süresinde, açık artırma sırasında kaydettiğiniz işaretçiler etkinlik düzeyindeki verilerle tetiklenebilir veya geliştirilebilir. Satıcı reportEvent() öğesini tetiklemeli ve etkinlik düzeyindeki verileri iletmelidir. Platform, alıcının kayıtlı reklam işaretçisi URL'sini pingler. Bu URL, tetiklenen reportEvent() ile ilişkilidir.
  3. Alıcı, reklam işaretçisi isteklerine Attribution-Reporting-Register-Source başlığıyla yanıt vererek reklamı Attribution Reporting API'ye kaydeder. Bir dönüşüm etkinliği için açık artırma sinyallerini ilişkilendirmek için kaynak URL'sini kaydetme'de auctionId değerini ayarlayın.

Yukarıdaki işlemin ardından alıcı, birbiriyle ilişkilendirilebilecek benzersiz kimlik kullanılarak ilişkilendirilebilecek bir açık artırma raporu, etkileşim raporu ve dönüşüm raporu elde eder.

Benzer iş akışı, ilişkilendirme verilerine erişmesi gereken satıcılar için geçerlidir. Satıcı, registerAdBeacon() ile gönderim yapmak 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ığı, reklam adaylarının açık artırma için seçilip seçilmeyeceğini belirlemek üzere bütçe tükenmesi durumu gibi gerçek zamanlı bilgilere ihtiyaç duyar. Hem alıcı tarafı hem de satış tarafı platformları bu bilgileri işledikleri sunuculardan alabilir. Hassas bilgilerin bu sunucular üzerinden sızdırılmasını en aza indirmek için teklifte aşağıdaki kısıtlamaların uygulanması gerekir:

  • Bu sunucuların bu bölümün ilerleyen kısımlarında açıklanan davranışları, kullanıcı bilgilerini sızdırmaz.
  • Sunucular gördüğü verileri temel alarak belirsizleştirilmiş profiller oluşturmaz, yani bu profilin "güvenilir" olması gerekir.

Alıcı tarafı: Alıcı tarafı teklif verme mantığını başlattığında platform, güvenilir sunucudan güvenilir teklif verileri için bir HTTP getirmesi gerçekleştirir. URL, işlenen özel kitlenin Güvenilir Teklif Sinyalleri meta verilerinde bulunan URL ve anahtarların eklenerek oluşturulur. Bu getirme işlemi, yalnızca cihaz üzerindeki özel kitlelerden gelen reklamlar işlenirken yapılır. Bu aşamada, alıcı tarafı bütçeleri uygulayabilir, kampanya duraklatması / devam ettirme durumunu kontrol edebilir, hedefleme gerçekleştirebilir vb.

Aşağıda, özel kitledeki güvenilir teklif sinyali meta verilerine göre güvenilir teklif verilerini getirmek için kullanılacak örnek bir URL verilmiştir:

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

Sunucudan gelen yanıt, anahtarları anahtar1, anahtar2 vb. olan ve değerleri, alıcının teklif işlevleri tarafından kullanılabilecek bir JSON nesnesi olmalıdır.

Satıcı tarafı: Yukarıdaki alıcı tarafı akışına benzer şekilde, satıcı tarafı açık artırmada değerlendirilen reklam öğeleri hakkında bilgi getirmek isteyebilir. Örneğin bir yayıncı, marka güvenliğiyle ilgili endişelerden dolayı belirli reklam öğelerinin uygulamasında gösterilmemesini zorunlu kılmak isteyebilir. Bu bilgiler getirilebilir ve satış tarafı açık artırma mantığında kullanılabilir. Alıcı tarafı güvenilir sunucu aramasına benzer şekilde, satıcı tarafı güvenilir sunucu araması da HTTP getirme yoluyla yapılır. URL, Güvenilir Puanlama Sinyalleri URL'sine verilerin getirilmesi gereken reklam öğelerinin oluşturma URL'leri eklenerek oluşturulur.

Aşağıda, reklam öğesi oluşturma URL'lerine göre açık artırmada dikkate alınan reklam öğeleri hakkında bilgi getirmek için örnek bir URL verilmiştir:

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

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

Bu sunucular, güvenilir bir şekilde çalışarak çeşitli güvenlik ve gizlilik avantajları sunar:

  • Sunucunun her anahtar için döndürdüğü değer, yalnızca bu anahtara dayanılarak güvenilir hale getirilebilir.
  • Sunucu, etkinlik düzeyinde günlük kaydı yapmaz.
  • Sunucunun bu isteklere dayalı başka yan etkisi yok.

Geçici bir mekanizma olarak, alıcı ve satıcı bu teklif sinyallerini kendi oluşturdukları sunucu da dahil olmak üzere herhangi bir sunucudan alabilir. Ancak sürüm sürümünde istek yalnızca güvenilir anahtar/değer türündeki bir sunucuya gönderilir.

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