Protected Audience API ile özel kitle hedeflemeyi destekleme

bookmark_border Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Son güncellemeler

• Özel kitle güncellemelerini planlama hakkında bilgi eklendi
• Protected Audiences ile İlişkilendirme Raporlama entegrasyonu eklendi
• Protected Audience özelliklerinin zaman çizelgesini yayınladık.
• FLEDGE, Protected Audience API olarak yeniden adlandırıldı.
• Özel kitle yetkilendirme teklifi eklendi.
• Günlük güncelleme URL'si için k-anonimlik koşulu kaldırıldı.

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ı veya şelale uyumlulaştırması desteğiyle 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. Protected Audience'ı geliştirmeye devam ederken geri bildirimleriniz bizim için çok değerlidir.

Zaman çizelgesi

Önümüzdeki aylarda yeni özellikler kullanıma sunacağız. Kesin sürüm tarihleri, özelliğe bağlı olarak değişir. Bu tablo, kullanıma sunulduğunda dokümanların bağlantılarıyla güncellenir.

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 genel fikir genellikle "yeniden pazarlama" ve "özel kitle hedefleme" gibi terimlerle açıklanır.

Günümüzde bu kullanım alanları genellikle reklamın nasıl gösterildiğiyle ilgili bağlama dayalı bilgiler (ör. uygulama adı) ve reklam teknolojisi platformlarıyla hedef kitle listeleri gibi gizli bilgiler paylaşılarak uygulanmaktadır. 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çları olan reklamveren tarafından atanan bir kitleyi temsil eden "özel kitle" soyutlaması etrafında döner. Kitle bilgileri cihaz üzerinde depolanır ve kitle için alakalı olan reklam adaylarıyla ve teklif sinyalleri gibi rastgele meta verileriyle ilişkilendirilebilir. Bu bilgiler, reklamveren teklifleri, reklam filtreleme ve oluşturma hakkında bilgi vermek için kullanılabilir.
2. Reklam Seçimi API'si: Yerel olarak depolanan reklam adaylarını dikkate alarak "kazanan" reklamı belirlemek için cihaz üzerindeki sinyalleri kullanan reklam teknolojisi platformlarının iş akışlarını koordine eden ve bir reklam teknolojisi platformunun cihaza döndürdüğü reklam adaylarında ek işlem gerçekleştiren bir çerçeve sağlar.

Genel olarak entegrasyon şu şekilde çalışır:

1. SportingGoodsApp, kullanıcılarına 2 gün içinde satın alma işlemini tamamlamadıkları takdirde alışveriş sepetlerinde kalan ürünleri satın almalarını hatırlatmak istiyor. SportingGoodsApp, kullanıcıyı "alışveriş sepeti içindeki ürünler" kitle listesine eklemek için Özel Kitle API'yi kullanır. Platform, bu kitle listesini cihazda yönetip depolar ve üçü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, kitle tabanlı reklam adaylarının listesinin güncel kalmasına ve reklam fırsatı sırasında üçüncü taraf reklam sunucularına gönderilen isteklerle (ör. bağlamsal reklam isteği) ilişkili olmamasına yardımcı olur.

2. Kullanıcı aynı cihazda FrisbeeGame'i oynarken SportingGoodsApp'in alışveriş sepetinde kalan öğelerin satın alma işlemini tamamlamasını hatırlatan bir reklam görebilir. 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ışı, 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çimini bilgilendirmesini sağlarken bu verilerin üçüncü taraflarla paylaşılmasını sınırlandırır.

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ştirme yapabilir.

Android API'lerinde Protected Audience'a erişim

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 ve kullanıcının hangi özel kitlelerde yer aldığını 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ı sınırlamaya 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, çağıran uygulamanın paket adı olarak dolaylı olarak ayarlanır.
• Alıcı: Bu özel kitlenin reklamlarını 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çimine göre 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, özel bir kitlenin üyeliğini iptal etmek için bu bilgileri kullanır. Özel kitlenin ömrünü sınırlamak için son kullanma süresi, 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ı için teklif verme işleminde reklam teknolojisi platformuna özgü sinyaller. Kullanıcının kaba konumu, tercih edilen yerel ayar vb. sinyallere örnek olarak verilebilir.
• Güvenilir teklif verileri: Reklam teknolojisi platformları, reklam alma ve puanlama işlemlerini bilgilendirmek için gerçek zamanlı verilerden yararlanır. Örneğin, bir reklamın bütçesi tükenebilir ve reklamın yayınının hemen durdurulması gerekebilir. 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. Bu isteği işleyen sunucu, reklam teknolojisi platformu tarafından yönetilen bir güvenilir sunucu olacaktır.
• Teklifli sistem mantığı URL'si: Platformun, teklifli sistem kodunu talep tarafı platformundan almak için kullandığı URL. Platform, reklam açık artırması başlatıldığında bu adımı gerçekleştirir.
• Reklamlar: Özel kitle için önerilen reklamların listesi. Reklam teknolojisi platformuna özgü reklam meta verileri ve reklamın oluşturulacağı URL bu kapsamdadır. Özel kitle için bir açık artırma başlatıldığında bu reklam meta verisi 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 ajans, reklamveren müşterileri ve iş ortaklarıyla iş ortaklığı yapan reklam teknolojileri tarafından desteklenen 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 (STP'ler) gibi cihaz üzerinde varlığı olan reklam teknolojileriyle birlikte çalışması gerekir. 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 aşağıdaki adımları uygulayın:

Özel bir kitleye katılma

Özel bir kitleye iki şekilde katılabilirsiniz:

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ının sahip olduğu URL uç noktası, yanıt gövdesinde bir CustomAudience JSON nesnesi ile 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 alıcının eTLD+1 ile 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, 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 sahibi, çağıran 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 adresine bir HTTP GET isteği gönderir ve özel kitleyi temsil eden bir JSON nesnesi bekler. Yanıta, özel kitle nesnesi alanları için zorunlu, isteğe bağlı kısıtlamalar ve varsayılan değerler uygulanır. Geliştirici Kılavuzumuzda mevcut koşullar ve sınırlamalar hakkında bilgi edinin.

Alıcıdan gelen herhangi bir HTTP hata yanıtı, fetchAndJoinCustomAudience'ün başarısız olmasına neden olur. Özellikle 429 (Çok Fazla İstek) HTTP durum yanıtı, geçerli uygulamadan gelen istekleri tanımlanacak bir süre boyunca engeller. Alıcıdan gelen yanıt bozuksa API çağrısı 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ğerler, platform tarafından alınan alıcı yanıtıyla üzerine yazılamaz. Protected Audience API, yanıttaki alanları yoksayar. Özel kitle oluşturmak için bu alanların gerekli olması nedeniyle, istekte ayarlanmamışlarsa yanıtta ayarlanmaları gerekir. API çağıran tarafından kısmen tanımlanan CustomAudience içeriğinin JSON temsili, fetchUri için GET isteğine özel bir X-CUSTOM-AUDIENCE-DATA başlığında 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ü 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 özel kitleyi oluşturmak üzere kullanılacak bilgilerin bir kısmının fetchUri'ye sorgu parametresi olarak ekleneceğini kabul edebilir. 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 API tarafından herhangi bir amaçla kullanılmaz 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

• Bu öneri, kullanıcılara en az bir özel kitle oluşturan yüklü uygulamaların listesini göstermeyi amaçlamaktadır.
• Kullanıcılar bu listeden uygulamaları 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 de 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ı üzerinde çalışmalarımız devam ediyor. Ayrıntılar daha sonraki bir güncellemede paylaşılacak.

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 reklamverenlerin ve reklam teknolojisi sağlayıcıların, kullanıcılar uygulamayı kullanırken gerçek zamanlı olarak kullanıcının hangi kitlelere ait olduğunu tanımlaması her zaman mümkün değildir.

Bu işlemi kolaylaştırmak için reklam teknolojisinin scheduleCustomAudienceUpdate() API'sini çağırması mümkündür. Bu API, arayanın API çağrısının ne zaman yapılması gerektiği konusunda 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, platformda çalışacak gecikmeli bir işin kaydedilmesi için gerekli bilgileri içerir. Belirtilen gecikme süresinden sonra, arka planda düzenli olarak çalışan bir iş 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. Bu sayede uygulama içi SDK'lar, DSP'lerle olan iş ortaklıklarına göre özel kitle yönetimi üzerinde tam kontrolden kısmi kontrole kadar iki rolü de üstlenebilir.

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

• 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 olarak ayarlanırsa ve aynı uygulamada aynı alıcı için daha önce istenen güncellemeler hâlâ beklemedeyse bu ScheduleCustomAudienceUpdateRequest ile scheduleCustomAudienceUpdate çağrısı başarısız olur. 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 olan ilişkilerini yönetebilir.
• Uygulamalar, üçüncü taraf reklam teknolojisi platformlarına kendi adına özel kitleleri yönetme izni verebilir.

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

Reklam teknolojisi platformu kontrolü

Bu öneride, reklam teknolojilerinin özel kitlelerini kontrol etme yöntemleri özetlenmiştir:

• 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, özel kitle oluşturmayı doğrulamak için kullanılan doğrulama jetonları sağlamak amacıyla uygulamalarla veya SDK'larla iş ortaklığı yapabilir. 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.
• Reklam teknolojisi, joinCustomAudience çağrılarını kendi adına devre dışı bırakmayı seçebilir ve yalnızca fetchAndJoinCustomAudience API'nin tüm çağrı özel kitlelerini etkinleştirmesine izin verebilir. 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 sınırlamaları nedeniyle yetkilendirme izinleri reklam teknolojisi bazında olamaz.

Aday reklamlar ve meta veri yanıtı

Alıcı tarafı platformdan döndürülen aday reklamlar ve meta veriler aşağıdaki alanları içermelidir:

• Meta veriler: Satın alma tarafı, reklam teknolojisine özgü reklam meta verileri. Örneğin, reklam kampanyasıyla ilgili bilgiler ve konum ile dil gibi hedefleme ölçütleri buna dahil olabilir.
• Oluşturma URL'si: Reklam öğesini oluşturmaya yönelik 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 satın alma tarafı filtreleme mantığı bölümünü 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 teklifli sistemi ve reklam seçimini yalnızca kendi sunucularında gerçekleştirir. 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ı için aday reklamlar bant dışından (yani reklamların gösterileceği bağlamda değil) getirilir. 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ı, reklam seçim iş akışında aşağıdaki değişiklikleri yapabilir:

• Sunucuda yüklü paket bilgileri bulunmadığında reklam teknolojisi platformları, cihaza birden fazla bağlama dayalı reklam göndermek ve alakalı bir reklam gösterme şansını en üst düzeye çıkarmak için uygulama yükleme tabanlı filtrelemeyi etkinleştirmek üzere reklam seçim iş akışını tetiklemek isteyebilir.
• Yeniden pazarlama reklamları bant dışı olduğundan mevcut teklif modellerinin güncellenmesi gerekebilir. Reklam teknolojisi platformları, reklam özellikleri ve bağlamsal sinyallerle ayrı ayrı çalışabilen ve teklifleri tahmin etmek için cihazdaki alt model çıktılarını birleştirebilen teklifli sistem alt modelleri (uygulama, iki kule modeli adlı bir kalıba dayalı olabilir) oluşturmak isteyebilir. 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 etkileşimi verilerinin reklam seçimini bilgilendirmesini sağlarken bu verilerin üçüncü taraflarla paylaşılmasını sınırlandırır.

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. Satın alma tarafı teklif mantığı yürütme
2. Alıcı tarafı reklam filtreleme ve işleme
3. Satıcı tarafı karar mantığı yürütme

Özel kitleleri içeren reklam seçimleri için platform, özel kitlenin "Teklif verme mantığı URL'si" meta verileriyle tanımlanan herkese açık URL uç noktasına göre alıcı tarafı tarafından sağlanan JavaScript kodunu getirir. Satıcı tarafı karar kodunun URL uç noktası da reklam seçimi iş akışını başlatmak için giriş olarak iletilir.

Özel kitleleri içermeyen reklam seçimlerinin tasarımı aktif olarak devam etmektedir.

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: Bir reklam açık artırması başlatıldığında platform, kazanan reklamı puanlamak için satıcı tarafı platformdan JavaScript kodu almak üzere bu URL'yi kullanır.
• Özel kitle alıcıları: eTLD+1 biçimini izleyen bu açık artırma için özel kitleye dayalı talebe sahip alıcı tarafı platformların listesi.
• Reklam seçimi sinyalleri: Açık artırma hakkında bilgiler (reklam boyutu, reklam biçimi vb.).
• Satıcı sinyalleri: Talep tarafı platforma özgü sinyaller.
• Güvenilir Puanlama Sinyalleri URL'si: Reklam öğesine özgü 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 yararlı olan kapsamlı bağlamsal bilgiler içerebilir.

Aşağıdaki açıklayıcı kod snippet'inde, reklam teknolojisi platformu SDK'sının reklam seçimi iş akışını başlatmak için önce AdSelectionConfig'ü tanımladığı ve ardından kazanan reklamı almak için selectAds'ü çağırdığı gösterilmektedir:

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 mantığı

Teklif verme mantığı genellikle alıcı tarafı platformlar tarafından sağlanır. Kodun amacı, aday reklamlar için teklifleri belirlemektir. Sonuç belirlemek için ek iş mantığı uygulayabilir.

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 (bağlamsal veya yeniden pazarlama) için sırayla çağırır. 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 parametreleri bekler:

• Reklam: Alıcı tarafı teklif kodu tarafından değerlendirilen reklam. Bu, uygun bir özel kitleden alınan bir reklam olacaktır.
• Açık artırma sinyalleri: Satıcı tarafına ait, platforma özgü sinyaller.
• 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 yararlı olan kapsamlı bağlamsal bilgiler içerebilir.
• 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ının bütçesi tükenebilir ve yayınının hemen durdurulması gerekebilir. 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 sunan 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': ...,};
}

Bu reklam kazanan olursa adCost, gizlilik için stokastik olarak 8 bit'e yuvarlanır. 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, reklam seçim aşamasında kullanılabilen ek cihaz üzerindeki sinyallere göre reklamları filtreleyebilir. Örneğin, reklam teknolojisi platformları burada sıklık sınırı özelliklerini uygulayabilir. 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ığı, belirli bir reklam için 0 değerinde bir teklif döndürerek teklif mantığı kapsamında uygulanabilir.

Buna ek olarak, alıcı tarafı platformlar, belirli bir reklamın Protected Audience'in erişimine açık olan ve cihazdan çıkmayan ek cihaz üzerinde sinyallere göre filtrelenmesi gerektiğini belirtebilir. Ek filtreleme mantığının tasarımlarını sağlamlaştırdıkça, satın alma tarafı platformlar da filtrelemenin yapılması gerektiğini belirtmek için bu yapıyı takip edecektir.

Satıcı tarafı puanlama mantığı

Puanlama mantığı genellikle satıcı tarafı platform tarafından sağlanır. Kodun amacı, teklif verme mantığı çıkışlarına göre kazanan reklamı belirlemektir. Sonuç belirlemek için ek iş mantığı uygulayabilir. 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şlevinin çıkışı.
• Teklif: generateBid() işlevinden elde edilen teklif tutarı.
• Açık artırma yapılandırması: selectAds() yöntemine giriş parametresi.
• 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ı, 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ğlam sinyali: Kaba zaman damgası veya yaklaşık konum bilgileri içerebilir.
• Kullanıcı sinyali: Uygulamanın yüklenmesini başlatan uygulama mağazası gibi bilgiler içerebilir.
• Özel kitle sinyali: Puanlanan reklam cihaz üzerinde bir özel kitleden geliyorsa bu sinyal, özel kitlenin okuyucusu ve adı gibi bilgileri içerir.

Reklam seçimi 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. Mobil cihazlardaki kaynak kısıtlamaları göz önüne alındığında, açık artırma kodu aşağıdaki yönergelere uymalıdır:

• Kod, önceden tanımlanmış bir sürede yürütülmeyi tamamlamalıdır. 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 ile yazılmalıdır. Bu sayede reklam teknolojisi platformları, örneğin Özel Korumalı Alan'ı destekleyen platformlar arasında 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 iletilir.

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 belirlenememesi için çözümü geliştirmeyi (Chrome'un çitli çerçeve önerisine benzer şekilde) içeriyor.

Gösterim ve etkinlik raporlaması

Reklam oluşturulduktan sonra kazanan gösterim, katılan alıcı tarafı ve satıcı tarafı platformlarına geri raporlanabilir. 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ı platform, kazanan reklamla ilgili etkinlik düzeyinde ek raporlar almaya uygundur. Bu sayede, tıklamalar, görüntülemeler ve diğer reklam etkinliklerine açık artırma hakkındaki bilgileri (teklif, özel kitle adı vb.) ekleyebilirsiniz. Platform, raporlama mantığını şu sırayla çağırır:

1. Satıcı tarafı raporlama.
2. Satın alma tarafı raporları.

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

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, işaretçileri kaydederek kazanan açık artırmayla ilgili gelecekteki etkinliklere abone olma mekanizması sağlar. 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şlevlerinden registerAdBeacon() yöntemini çağırabilir.

registerAdBeacon(beacons)

Giriş:

• event_key: Hangi etkileşim türüne kaydedileceğini belirten bir dize. Bu, açık artırma sonuçlarını raporlarken platformun ping'lediği bitiş noktasını aramak için bir anahtar olarak kullanılır.
• reporting_url: Etkinliği işlemek 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. Bu anahtarların k-anonim olması gerekmez ancak belirli bir özel kitle için kaydedilebilecek anahtarların miktarı ve uzunluğuyla ilgili sınırlamalar vardır. reportEvent() çağrılırsa açık artırmayı yürüten satıcı tarafı platformlar bu etkinlik raporlarını her zaman almaya uygundur. Yalnızca kazanan alıcı tarafı platform bu raporları almaya uygundur.

Satıcı tarafı raporlama

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ı: Aşağıdakileri 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 işlevine geçirilecek bir JSON nesnesi.

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ı için sinyaller: Platform, arz tarafı ile talep tarafı arasında veri paylaşımını desteklemek için bu döndürülen değeri, talep tarafı raporlama koduna giriş parametresi olarak iletir.

Alıcı tarafı raporlama

Platform, açık artırmayla ilişkili özel kitlenin Teklif verme mantığı URL 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ı platformun raporlama URL'sine iletmesi gereken tüm bilgiler bu veri kaynağından gelebilir.
• signals_for_buyer, satıcı tarafı reportResult işlevinin sonucudur. Bu sayede satış tarafı platformu, raporlama amacıyla alıcı tarafı platformla veri paylaşabilir.
• contextual_signals, uygulama adı gibi bilgileri içerir ve custom_audience_signals, özel kitle bilgilerini içerir. Gelecekte başka bilgiler de eklenebilir.

Çıkış:

• 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.

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'sı 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, AdSelectionOutcome'den alınan yakın zamanda yürütülen bir açık artırmanın AdSelectionId olmalıdır.
• event_key, etkileşim etkinliğini tanımlayan, satıcı tarafı tarafından tanımlanmış bir dizedir.
• event_data, event_key ile ilişkili verileri temsil eden bir dizedir.
• reporting_destinations, platform tarafından sağlanan işaretler kullanılarak ayarlanan bir bit maskesidir. FLAG_REPORTING_DESTINATION_SELLER veya FLAG_REPORTING_DESTINATION_BUYER'ten biri ya da ikisi olabilir.
• input_event (isteğe bağlı), Attribution Reporting API ile entegrasyon için kullanılır. Bir InputEvent nesnesi (tıklama etkinliği için) veya null değeridir (görüntüleme etkinliği için). Bu parametreyle ilgili daha fazla bilgi için Attribution Reporting API Entegrasyonu başlıklı makaleyi inceleyin.

Satış tarafı SDK'sı reportEvent'ü çağırdıktan sonra, reporting_destinations işaretine bağlı olarak platform, event_key'yi 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 POST eder. İsteğin içerik türü düz metindir ve gövde event_data olur. Bu istek, mümkün olduğunca 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 İlişkilendirme Raporlama API'leri (ARA) genelinde API'ler arası işlevsellik sağlıyoruz. Bu işlev, reklam teknolojilerinin çeşitli yeniden pazarlama taktikleri genelinde ilişkilendirme performanslarını değerlendirmelerine olanak tanır. Böylece, hangi kitle türlerinin en yüksek YG'yi sağladığını anlayabilirler.

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

• Hem 1) reklam etkileşimi raporlaması hem de 2) kaynak kaydı için kullanılacak URI'lerin anahtar/değer eşlemesini oluşturun.
• Toplu özet raporlama için kaynak taraflı anahtar eşlemelerine Protected Audience açık artırmasından elde edilen açık artırma verilerini ekleyin (İlişkilendirme Raporlama API'sini kullanarak). 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, bir görüntülemeyi veya tıklamayı Attribution Reporting API ile uygun bir kaynak olarak kaydetmek için alıcıya gerekli verileri sağlar.
• 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(), yeni bir isteğe bağlı parametre InputEvent kabul eder. Reklam işaretçisi kaydeden kazanan alıcılar, hangi reportEvent raporlarının kayıtlı bir kaynak olarak Attribution Reporting API'lerine kaydedileceğini seçebilir. reportEvent() adresinden gönderilen tüm etkinlik raporlama isteklerine Attribution-Reporting-Eligible istek başlığı eklenir. Uygun ARA üstbilgilerine sahip tüm yanıtlar, diğer normal ARA kaynak kaydı yanıtlarıyla aynı şekilde ayrıştırılır. Kaynak URL'yi kaydetme hakkında bilgi edinmek için Attribution Reporting API'yi açıklayan makaleyi inceleyin.

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

Açık artırma sonrası eventData'ün hassas bilgiler içerebileceğini unutmayın. Bu nedenle platform, yönlendirilen kaynak kayıt isteklerinde eventData'ü kaldırır.

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

Bu örnekte, açık artırma, oluşturulan reklam ve dönüşüm uygulamasındaki verileri bir araya getirmek isteyen bir alıcının bakış açısından konuya bakacağız.

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ı, açık artırma verileriyle birlikte bu benzersiz kimliği gönderir. 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ışı: Alıcılar, açık artırma başlamadan önce programatik gerçek zamanlı teklif verme ("GZT") teklif yanıtlarının bir 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 verme mantığında kullanılabilir hale gelir.

1. reportWin yürütülürken alıcı, reklam oluşturma süresi ve belirli etkileşim etkinlikleri (registerAdBeacon()) sırasında tetiklenecek bir reklam işaretçisi kaydedebilir. Bir reklam etkinliği için açık artırma sinyallerini ilişkilendirmek üzere auctionId'yi işaretçi URL'sinin sorgu parametresi olarak ayarlayın.
2. Reklam oluşturma süresi sırasında, açık artırma süresi boyunca kaydettiğiniz işaretçiler tetiklenebilir veya etkinlik düzeyindeki verilerle geliştirilebilir. Satıcı, reportEvent() öğesini tetiklemelidir ve etkinlik düzeyindeki verileri iletmelidir. Platform, tetiklenen reportEvent() ile ilişkili olarak alıcının kayıtlı reklam işaretçisi URL'sini pingler.
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 üzere Kaydet kaynak URL'sinde auctionId değerini ayarlayın.

Yukarıdaki işlemden sonra alıcı, açık artırma raporu, etkileşim raporu ve dönüşüm raporu alır. Bu raporlar, benzersiz kimlik kullanılarak birbiriyle ilişkilendirilebilir.

İ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 tarafından 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ükenme durumu gibi gerçek zamanlı bilgiler gerektirir. Hem alıcı tarafı hem de satıcı tarafı platformlar, bu bilgileri işlettikleri sunuculardan alabilir. Bu sunucular üzerinden 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ı olarak takma adlı profiller oluşturmaz. Yani "güvenilir" olması gerekir.

Satın alma tarafı: Satın alma tarafı, satın alma tarafı teklifli sistem mantığını başlattığında platform, güvenilir sunucudan güvenilir teklifli sistem verilerini HTTP ile getirir. URL, işlenen özel kitlenin Trusted Bidding Signals meta verilerinde bulunan URL'nin ve anahtarların eklenmesiyle oluşturulur. Bu getirme işlemi yalnızca cihaz üzerindeki özel kitlelerdeki reklamlar işlenirken yapılır. Bu aşamada alıcı tarafı bütçeleri uygulayabilir, kampanyanın duraklatılma / duraklatma 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ı key1, key2 vb. olan ve değerleri alıcının teklif verme işlevlerine sunulan bir JSON nesnesi olmalıdır.

Satıcı tarafı: Yukarıdaki alıcı tarafı akışına benzer şekilde, satıcı tarafı da açık artırmada değerlendirilen reklam öğeleri hakkında bilgi almak isteyebilir. Ö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, satıcı tarafı güvenilir sunucu araması da bir HTTP getirme işlemi kullanılarak gerçekleşir. 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 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ı istekle gönderilen oluşturma URL'leri olan bir JSON nesnesi olmalıdır.

Bu sunucular, çeşitli güvenlik ve gizlilik avantajları sunmak için güvenilir bir şekilde çalışır:

• Sunucunun her anahtar için döndürdüğü değerin yalnızca bu anahtara dayandığına güvenilebilir.
• Sunucu, etkinlik düzeyinde günlük kaydı oluşturmaz.
• Sunucunun bu isteklerden kaynaklanan başka yan etkileri yoktur.

Geçici bir mekanizma olarak alıcı ve satıcı, bu teklif sinyallerini kendi işlettikleri sunucu da dahil olmak üzere herhangi bir sunucudan getirebilir. 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'deki Özel Korumalı Alan ile uyumlu platformlar ve web için ortak bir güvenilir anahtar/değer türü sunucu kullanabilir.