Protected Audience API ile özel kitle hedeflemeyi destekleme

Son güncellemeler

• Özel kitle güncellemelerini planlama hakkında bilgi eklendi.
• Protected Audience ile İlişkilendirme Raporlama entegrasyonu eklendi
• Protected Audience özelliklerinin zaman çizelgesini yayınladı.
• FLEDGE'in adı Protected Audience API olarak değiştirildi.
• Özel kitle temsiline yönelik teklif eklendi.
• Günlük güncelleme URL'si için k-anonimliği şartı kaldırıldı.

Protected Audience beta sürümündedir ve geliştirme için kullanılabilir.

Protected Audience ile şunları yapabilirsiniz:

• Önceki kullanıcı işlemlerine göre özel kitleleri yönetin.
• Tek satıcılı veya şelale aracılığı desteğiyle cihaz üzerinde açık artırmalar başlatın.
• Reklam seçimi sonrasında gösterim raporlaması yapın.

Başlamak için Protected Audience geliştirici kılavuzunu okuyun. Protected Audience'ı geliştirmeye devam ederken geri bildirimlerinizi bekliyoruz.

Zaman çizelgesi

Önümüzdeki aylarda yeni özellikler yayınlayacağız. Kesin yayınlanma tarihleri özelliğe göre değişir ve bu tablo, kullanıma sunuldukça doküman bağlantılarıyla güncellenir.

Genel Bakış

Mobil reklamcılıkta reklamverenler, daha önce reklamverenin uygulamasıyla nasıl etkileşimde bulunduklarına göre potansiyel olarak ilgilenen kullanıcılara reklam yayınlamaları gerekir. Örneğin, SportingGoodsApp geliştiricisi, kullanıcılara satın alma işlemini tamamlamalarını hatırlatan reklamlar göstererek alışveriş sepetinde ürün bırakan kullanıcılara reklam yayınlamak isteyebilir. Sektörde bu genel fikir genellikle "yeniden pazarlama" ve "özel kitle hedefleme" gibi terimlerle tanımlanır.

Günümüzde bu kullanım alanları genellikle reklamın nasıl gösterildiğiyle ilgili bağlamsal bilgilerin (ör. uygulama adı) ve hedef kitle listeleri gibi özel bilgilerin reklam teknolojisi platformlarıyla paylaşılmasıyla uygulanı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şımını hem de kullanıcının uygulama etkileşimi bilgilerinin üçüncü taraflarla paylaşımını sınırlayacak şekilde yaygın etkileşime dayalı kullanım alanlarını desteklemesi için aşağıdaki API'leri içerir:

1. Özel Kitle API'si: Bu API, reklamveren tarafından belirlenen ve ortak amaçlara sahip bir kitleyi temsil eden "özel kitle" soyutlaması üzerine kuruludur. Kitle bilgileri cihazda saklanır ve kitle için alakalı olabilecek aday reklamlarla ve teklif sinyalleri gibi rastgele meta verilerle 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: Bu API, yerel olarak depolanan aday reklamları dikkate alarak "kazanan" bir reklamı belirlemek ve bir reklam teknolojisi platformunun cihaza döndürdüğü aday reklamlar üzerinde ek işlemler gerçekleştirmek için cihaz üzerindeki sinyalleri kullanan reklam teknolojisi platformlarının iş akışlarını düzenleyen 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 tamamlamamaları durumunda sepetlerinde kalan ürünleri satın almalarını hatırlatmak istiyor. SportingGoodsApp, kullanıcıyı "sepeteki ürünler" kitle listesine eklemek için Özel Kitle API'sini kullanır. Platform, bu kitle listesini cihazda yönetip saklayarak üçüncü taraflarla paylaşımı sınırlar. 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ışında kullanılabilen aday reklamlar sağlar. Platform, arka planda kitle tabanlı güncellenmiş reklamları düzenli olarak getirecek şekilde yapılandırılabilir. Bu, kitle tabanlı aday reklamların listesinin güncel ve reklam fırsatı sırasında üçüncü taraf reklam sunucularına gönderilen isteklerle (ör. bağlamsal reklam isteği) ilişkisiz kalmasına yardımcı olur.

2. Kullanıcı aynı cihazda FrisbeeGame'i oynadığında 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ının parçası olabileceği herhangi bir kitle listesine (bu örnekte, SportingGoodsApp tarafından oluşturulan "alışveriş sepetindeki ürünler" özel kitlesi) göre kullanıcı için kazanan bir reklamı seçmek üzere Reklam Seçimi API'sini çağırmasıyla sağlanabilir. Reklam seçimi iş akışı, özel kitlelerle ilişkili cihaz içi reklamların yanı sıra reklam teknolojisi platformlarının sunucularından alınan reklamları ve diğer cihaz içi sinyalleri de 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şimleri verilerinin reklam seçimini bilgilendirmesini sağlarken bu verilerin üçüncü taraflarla paylaşımını sınırlar.

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

4. Platform, gösterimlerin raporlanmasını ve reklam seçimi sonuçları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ştirme yapabilir.

Android'deki Protected Audience API'lerine erişme

Reklam teknolojisi platformlarının Protected Audience API'ye erişmek için kayıt yaptırması gerekir. Daha fazla bilgi için Özel Korumalı Alan hesabına kaydolma başlıklı makaleyi inceleyin.

Özel kitle yönetimi

Özel kitle

Özel kitle, reklamveren tarafından belirlenen ve ortak amaçlara veya ilgi alanlarına sahip bir kullanıcı grubunu temsil eder. Bir uygulama veya SDK, "alışveriş sepetinde öğe bırakan" ya da bir oyunun "başlangıç seviyelerini tamamlayan" gibi belirli bir kitleyi belirtmek için özel kitle kullanabilir. Platform, kitle bilgilerini cihazda yerel olarak saklar ve kullanıcının hangi özel kitlelerde olduğunu göstermez. Özel kitleler, Chrome'un Protected Audience ilgi 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.

Bir reklamveren uygulaması veya entegre SDK, örneğin bir uygulamadaki kullanıcı etkileşimine göre özel bir kitleye katılabilir veya özel bir kitleden ayrılabilir.

Özel kitle meta verileri

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

• Sahip: Sahip uygulamanın paket adı. Bu, arayan uygulamanın paket adı olarak dolaylı şekilde ayarlanır.
• Alıcı: Bu özel kitle için reklamları yöneten alıcı reklam ağı. Alıcı, özel kitleye erişebilecek ve alakalı reklam bilgilerini getirebilecek tarafı da temsil eder. Alıcı, eTLD+1 biçiminde belirtilir.
• Ad: Özel kitle için rastgele bir ad veya tanımlayıcı (ör. "alışveriş sepetini terk edenler" gibi bir kullanıcı). Bu özellik, örneğin reklamverenin reklam kampanyalarındaki hedefleme ölçütlerinden biri veya teklif kodu getirmek için URL'deki bir sorgu dizesi olarak kullanılabilir.
• Etkinleştirme zamanı ve geçerlilik bitiş zamanı: Bu alanlar, bu özel kitlenin etkili olacağı zaman aralığını tanımlar. Platform, bu bilgileri kullanarak özel kitle üyeliğini iptal eder. Son kullanma tarihi, özel bir kitlenin ömrünü sınırlamak için maksimum süre aralığını aşamaz.
• Günlük güncelleme URL'si: Platformun, "Kullanıcı teklif sinyalleri" ve "Güvenilir teklif sinyalleri" alanlarında tanımlanan aday reklamları ve diğer meta verileri düzenli olarak getirmek için kullandığı URL. Daha fazla bilgi için özel kitleler için olası reklamları getirme bölümüne bakın.
• Kullanıcı teklif sinyalleri: Yeniden pazarlama reklamlarının teklifleri için reklam teknolojisi platformuna özel sinyaller. Sinyallere örnek olarak kullanıcının yaklaşık konumu veya tercih ettiği yerel ayar verilebilir.
• Güvenilir teklif verme verileri: Reklam teknolojisi platformları, reklam alma ve puanlandırma hakkında bilgi vermek için gerçek zamanlı verilerden yararlanır. Örneğin, bir reklamın bütçesi tükenebilir ve reklamın yayını hemen durdurulması gerekebilir. 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 bir güvenilir sunucu olacaktır.
• Teklif verme mantığı URL'si: Platformun, talep tarafı platformundan teklif verme kodu getirmek 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 aday reklamların listesi. Buna, reklam teknolojisi platformuna özgü 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, mümkün olduğunda günlük güncelleme URL uç noktası kullanılarak yenilenir. Mobil cihazlardaki kaynak kısıtlamaları nedeniyle, özel kitlede depolanabilecek reklam sayısı sınırlıdır.

Özel kitle temsilcisi

Özel kitle tanımı ve yapılandırması için kullanılan yaklaşım genellikle sunucu tarafı teknolojilere ve reklam teknolojileri tarafından desteklenen entegrasyonlara dayanır. Bu entegrasyonlar, ajans ve reklamveren müşterileri ve iş ortaklarıyla yapılan iş ortaklıkları aracılığıyla sağlanır. Protected Audience API, kullanıcı gizliliğini korurken özel kitle tanımlama ve yapılandırma işlemlerine olanak tanır. Özel kitleye katılmak için uygulamalarda SDK varlığı olmayan alıcı reklam teknolojilerinin, cihaz üzerinde varlığı olan reklam teknolojileriyle (ör. mobil ölçüm ortakları [MMP'ler] ve arz tarafı platformları [STP'ler]) işbirliği yapması gerekir. Protected Audience API, cihaz üzerinde arayanların alıcılar adına özel kitle oluşturma işlemini çağırmasına olanak tanıyarak özel kitle yönetimi için esnek çözümler sunarak bu SDK'ları desteklemeyi amaçlar. Bu işleme özel kitle temsilcisi atama adı verilir. Aşağıdaki adımları uygulayarak özel kitle temsilcisini yapılandırın:

Özel kitleye katılma

Özel kitleye katılmak için iki yöntem vardır:

joinCustomAudience()

Bir uygulama veya SDK, CustomAudience nesnesi beklenen parametrelerle oluşturulduktan sonra joinCustomAudience() çağrısı yaparak ö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 gösterildiği gibi beklenen parametrelerle fetchAndJoinCustomAudience() çağrısı yaparak cihazda varlığı olmayan bir reklam teknolojisi adına özel 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ı yok sayılır (ve API tarafından otomatik olarak doldurulur). API, günlük güncelleme URL'sinin alıcının eTLD+1'iyle de eşleşmesini 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 alanının eTLD+1'inden belirler. CustomAudience alıcının kimliği, joinCustomAudience() tarafından yapılan kayıt ve uygulama yetkilendirme kontrollerini gerçekleştirmek için kullanılır ve get yanıtı tarafından değiştirilemez. CustomAudience sahibi, çağıran uygulamanın paket adıdır. eTLD+1 kontrolü dışında fetchUri için 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 nesnesi 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 hata yanıtı, fetchAndJoinCustomAudience işleminin başarısız olmasına neden olur. Özellikle 429 (Çok Fazla İstek) HTTP durum yanıtı, mevcut 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) nedeniyle yeniden denemeden sorumlu olan veya kalıcı hataları (ör. veri doğrulama hataları ya da sunucuyla iletişimde geçici olmayan diğer hatalar) işleyen API çağırana hatalar bildirilir.

CustomAudienceFetchRequest nesnesi, API çağrısı yapanın örnekte gösterilen isteğe bağlı özellikleri kullanarak özel kitleyle ilgili bazı bilgileri tanımlamasına olanak tanır. İstek içinde ayarlanırsa bu değerler, platform tarafından alınan alıcı yanıtıyla geçersiz kılınamaz. Protected Audience API, yanıttaki alanları yoksayar. İstek içinde ayarlanmamışlarsa yanıt içinde ayarlanmaları gerekir. Bu alanlar, özel kitle oluşturmak için gereklidir. API çağrısı yapan tarafından kısmen tanımlanan CustomAudience içeriğinin JSON gösterimi, fetchUri için yapılan GET isteğine özel bir başlıkta (X-CUSTOM-AUDIENCE-DATA) eklenir. Ö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. Alıcı, özel kitle doğrulamayı kolaylaştırmak için doğrulama jetonu sağlayabilir. Cihaz üzerindeki SDK, bu jetonu fetchUri içine eklemelidir. 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 ait olduğunu ve güvenilir bir cihaz üzerindeki iş ortağından kaynaklandığını doğrulamak için doğrulama jetonunu kullanabilir. Bilgi paylaşmak için alıcı, cihazdaki arayanla özel kitle oluşturmak üzere kullanılacak bilgilerin bir kısmının fetchUri'ya sorgu parametreleri olarak ekleneceğini kabul edebilir. Bu sayede alıcı, çağrıları denetleyebilir ve kötü amaçlı bir reklam teknolojisi tarafından birden fazla farklı özel kitle oluşturmak için doğrulama jetonunun kullanılıp kullanılmadığını tespit edebilir.

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 kendi adına oluşturulduğunu doğrulamak için kullanılabilir.
  • Protected Audience API teklifinde, doğrulama jetonunun biçimi veya alıcının doğrulama jetonunu arayana nasıl aktaracağı belirtilmemiştir. Ö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 kitle bırakma

Özel kitlenin sahibi, bu açıklayıcı kod snippet'inde gösterildiği gibi leaveCustomAudience() numaralı telefonu arayarak ayrılmayı seçebilir:

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

Depolama ve diğer cihaz kaynaklarının kullanımını korumak için özel kitlelerin geçerliliği sona erer ve önceden belirlenmiş bir süre sonra cihazdaki depodan kaldırılır. Varsayılan değer belirlenmelidir. Sahip bu varsayılan değeri geçersiz kılabilir.

Kullanıcı denetimi

• Bu öneri, kullanıcılara en az bir özel kitle oluşturmuş 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ına engel olur.
• Kullanıcılar, Protected Audience API'yi tamamen sıfırlayabilir. Bu durumda, cihazdaki mevcut tüm özel kitleler temizlenir.
• Kullanıcılar, Protected Audience API'nin de dahil olduğu Android'deki Ö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ışılmaktadır. Ayrıntılar daha sonraki bir güncellemede paylaşılacaktır.

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

Bu süreci kolaylaştırmak için reklam teknolojisi, scheduleCustomAudienceUpdate() API'sini çağırabilir. Bu API, arayanın API çağrısının ne zaman yapılacağını belirtmesine olanak tanır. Böylece, yanıt veren reklam teknolojisine uygulama düzeyindeki etkinlikleri işlemesi ve kullanıcının hangi Korunan Kitlelere katılması veya hangi Korunan Kitlelerden kaldırılması gerektiğini belirlemesi için 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, gecikmeli bir işin platformda çalıştırılması için gerekli bilgileri içerir. Belirtilen gecikme süresinden sonra, arka plan görevi düzenli olarak çalışır ve istekleri gönderir. The ScheduleCustomAudienceUpdateRequest can contain the following information:

• UpdateUri: Güncellemeyi getirmek için GET çağrısı gönderilecek URI uç noktası. Alıcı kimliği, eTLD+1'den doğal olarak çıkarılır ve açıkça sağlanması gerekmez. Ayrıca güncelleme yanıtıyla 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ığı zamandan itibaren gecikmeyi gösteren süre.

• PartialCustomAudience: API, cihazdaki 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 bağlı olarak özel kitle yönetimi üzerinde tam veya kısmi kontrol sağlayarak çift rol oynayabilir.

  • Bu sayede, benzer bilgi paylaşımına olanak tanıyan fetchAndJoinCustomAudience() API ile de uyumlu kalır.

• ShouldReplacePendingUpdates: Beklemede olan planlanmış güncellemelerin iptal edilip mevcut ScheduleCustomAudienceUpdateRequest içinde ayrıntılı olarak açıklanan güncellemeyle değiştirilip değiştirilmeyeceğini belirleyen Boole değeri. Bu 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ü

Önerinin amacı, uygulamaların özel kitleleri üzerinde kontrol sahibi olmasını sağlamaktır:

• Bir uygulama, özel kitlelerle olan 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ı üzerinde çalışılmaktadır. Ayrıntılar daha sonraki bir güncellemede paylaşılacaktır.

Reklam teknolojisi platformu kontrolü

Bu teklifte, reklam teknolojilerinin özel kitlelerini kontrol etme yöntemleri özetlenmektedir:

• Reklam teknolojisi sağlayıcılar, Özel Korumalı Alan'a kaydolur ve özel kitleye ait tüm URL'lerle eşleşen bir eTLD+1 alan adı sağlar.
• Reklam teknolojileri, özel kitle oluşturma işlemini doğrulamak için kullanılan doğrulama jetonları sağlamak üzere uygulamalar veya SDK'larla iş ortaklığı yapabilir. Bu süreç bir iş ortağına devredildiğinde, özel kitle oluşturma işleminin reklam teknolojisi tarafından onaylanması gerekecek şekilde yapılandırılabilir.
• Bir reklam teknolojisi, kendi adına joinCustomAudience çağrılarını 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'a kayıt sırasında güncellenebilir. Kontrolün tüm reklam teknolojilerine veya hiçbirine izin verdiğini unutmayın. Platform sınırlamaları nedeniyle, yetki izinleri reklam teknolojisi bazında verilemez.

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: Satın alma tarafı, reklam teknolojisine özgü reklam meta verileri. Örneğin, bu bilgiler arasında reklam kampanyasıyla ilgili bilgiler ve konum ile dil gibi hedefleme ölçütleri yer alabilir.
• 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ü inceleyin.

Reklam seçimi iş akışı

Bu teklif, reklam teknolojisi platformları için açık artırma yürütülmesini düzenleyen reklam seçimi API'sini tanıtarak gizliliği artırmayı amaçlamaktadır.

Günümüzde reklam teknolojisi platformları genellikle teklif verme ve reklam seçimi işlemlerini yalnızca kendi sunucularında gerçekleştirir. Bu teklifle birlikte, özel kitlelere ve diğer hassas kullanıcı sinyallerine (ör. yüklü paket bilgileri) yalnızca reklam seçimi API'si üzerinden erişilebilecek. Ayrıca, yeniden pazarlama kullanım alanında, aday reklamlar bant dışı olarak (yani reklamların gösterileceği bağlamda değil) getirilir. Reklam teknolojisi platformlarının, mevcut açık artırma ve reklam seçimi mantıklarının bazı bölümlerinin cihazda dağıtılıp yürütülmesine hazırlanması gerekir. Reklam teknolojisi platformları, reklam seçimi iş akışlarında aşağıdaki değişiklikleri yapabilir:

• Sunucuda yüklü paket bilgileri olmadığında reklam teknolojisi platformları, alakalı bir reklam gösterme şansını en üst düzeye çıkarmak için uygulama yüklemeye dayalı filtrelemeyi etkinleştirmek üzere reklam seçimi iş akışını çağırmak ve cihaza birden fazla bağlamsal reklam göndermek isteyebilir.
• Yeniden pazarlama reklamları bant dışı olarak getirildiğinden mevcut teklif modellerinin güncellenmesi gerekebilir. Reklam teknolojisi platformları, teklifleri tahmin etmek için cihazdaki alt model çıkışlarını birleştirerek reklam özelliklerinde ve bağlamsal sinyallerde ayrı ayrı çalışabilen teklif alt modelleri oluşturmak isteyebilir (uygulama, iki kuleli model adı verilen bir kalıba dayanabilir). Bu, hem sunucu tarafı açık artırmalardan hem de belirli bir reklam fırsatı için yapılan açık artırmalardan yararlanabilir.

Bu yaklaşım, kullanıcının uygulama etkileşimi verilerinin reklam seçimini etkilemesini sağlarken bu verilerin üçüncü taraflarla paylaşımını sınırlar.

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

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

Özel kitlelerin dahil olduğu 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ı tarafından sağlanan JavaScript kodunu getirir. Satış tarafı karar kodu için URL uç noktası, reklam seçimi iş akışını başlatmak üzere giriş olarak da iletilir.

Özel kitleleri içermeyen reklam seçimlerinin tasarımı aktif olarak yapılmaktadır.

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

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

• Satıcı: Satış tarafı reklam platformunun tanımlayıcısıdır ve eTLD+1 biçimindedir.
• Karar mantığı URL'si: Bir reklam açık artırması başlatıldığında platform, kazanan bir reklamı puanlamak için bu URL'yi kullanarak satıcı tarafı platformundan JavaScript kodu getirir.
• Özel kitle alıcıları: Bu açık artırma için özel kitle tabanlı talebi olan, eTLD+1 biçimindeki satın alma tarafı platformlarının listesi.
• Reklam seçme sinyalleri: Açık artırma hakkında bilgiler (reklam boyutu, reklam biçimi vb.).
• Satıcı sinyalleri: Arz tarafı platformuna özgü sinyaller.
• Güvenilir Puanlama Sinyalleri URL'si: Yaratıcıya özel gerçek zamanlı bilgilerin getirilebileceği, satıcı tarafındaki 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 üzere 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, önce AdSelectionConfig tanımlanarak, ardından kazanan reklamı almak için selectAds çağrılarak reklam seçimi iş akışını başlatan bir reklam teknolojisi platformu SDK'sı 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. 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, 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: Satın alma tarafı teklif kodu tarafından değerlendirilen reklam. Bu, uygun bir özel kitleye ait bir reklam olacaktır.
• Açık artırma sinyalleri: Satış 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 üzere bu parametreyi kullanabilir. Örneğin, bu parametre, teklifleri belirlemek için yararlı olan kapsamlı bağlamsal bilgiler içerebilir.
• Güvenilir teklif sinyalleri: Reklam teknolojisi platformları, reklam alma ve puanlandırma işlemlerini bilgilendirmek için gerçek zamanlı verilere güvenir. Örneğin, bir reklam kampanyasının bütçesi tükenebilir ve reklam yayınının hemen durdurulması gerekebilir. Bir reklam teknolojisi, bu anlık verilerin getirilebileceği bir URL uç noktası ve anlık aramanın yapılması gereken anahtar kümesini tanımlayabilir. Bu isteğe hizmet veren reklam teknolojisi platformunun yönetilen sunucusu, reklam teknolojisi platformu tarafından yönetilen güvenilir bir sunucu olacaktır.
• Bağlamsal sinyaller: Bu, kabalaştırılmış zaman damgası veya yaklaşık konum bilgileri ya da reklam tıklaması başına maliyeti içerebilir.
• Kullanıcı sinyalleri: Bu, yüklü paket bilgileri gibi bilgileri içerebilir.

Reklam maliyeti

Alıcı tarafı platformları, teklife ek olarak generateBid() kapsamında tıklama başına maliyeti döndürme seçeneğine de 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 kazanırsa gizlilik için adCost değeri 8 bit olacak şekilde stokastik olarak yuvarlanır. adCost değerinin yuvarlanmış 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 içi sinyallere göre reklamları filtreleyebilecek. Ö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 teklif değeri döndürülerek teklif verme mantığının bir parçası olarak uygulanabilir.

Buna ek olarak, satın alma tarafı platformları, belirli bir reklamın Protected Audience'a sunulan ve cihazdan ayrılmayan ek cihaz içi sinyallere göre filtrelenmesi gerektiğini belirtebilecek. Ek filtreleme mantığı tasarımlarını kesinleştirdikçe satın alma tarafı platformları, filtrelemenin gerçekleşmesi gerektiğini belirtmek için aynı yapıyı kullanacak.

Satıcı tarafı puanlama mantığı

Puanlama mantığı genellikle satıcı tarafı platformu tarafından sağlanır. Kodun amacı, teklif mantığı çıkışlarına göre kazanan bir reklamı belirlemektir. Sonucu 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 getirmek için selectAds() API'sinin "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 hakkında bilgi vermek için gerçek zamanlı verilere güvenir. Ö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ğe hizmet veren sunucu, reklam teknolojisi tarafından yönetilen güvenilir bir sunucu olmalıdır.
• Bağlamsal sinyal: Bu, kabalaştırılmış zaman damgası veya yaklaşık konum bilgilerini içerebilir.
• Kullanıcı sinyali: Bu, uygulamanın yüklenmesini başlatan uygulama mağazası gibi bilgileri içerebilir.
• Özel kitle sinyali: Puan verilen reklam, cihaz üzerinde bir özel kitleden geliyorsa bu sinyal, okuyucu ve özel kitlenin 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 getirir ve cihazda yürütür. Mobil cihazlardaki kaynak kısıtlamaları nedeniyle, açık artırma kodu aşağıdaki yönergelere uymalıdır:

• Kodun yürütme işlemi önceden tanımlanmış bir süre içinde tamamlanmalıdır. Bu sınır, tüm alıcı reklam ağları için eşit şekilde geçerli olur. Bu sınırlamayla ilgili 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 gizli 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 platformlarda teklif kodunu paylaşabilir.

Kazanan reklamın oluşturulması

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

Plan, çözümü geliştirerek bir kullanıcının özel kitle üyeliği veya uygulama etkileşimi geçmişiyle ilgili bilgilerin, kazanan reklamla ilgili bilgiler aracılığıyla uygulama veya SDK tarafından belirlenemeyeceğini doğrulamaktır (Chrome'un sınırlı çerçeveler önerisine benzer şekilde).

Gösterim ve etkinlik raporlaması

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

1. Satış tarafı raporlaması.
2. Satın alma tarafı raporları.

Bu, satın alma tarafı ve satış tarafı platformlarına, cihazdaki önemli bilgileri sunuculara geri göndererek gerçek zamanlı bütçelendirme, teklif modeli güncellemeleri ve doğru faturalandırma iş akışları gibi özellikleri etkinleştirme olanağı tanır. Bu gösterim raporlama desteği, Attribution Reporting API'yi tamamlayıcı niteliktedir.

Etkinlik raporlamasını desteklemek için iki adım gerekir: Satış tarafı ve satın alma tarafı JavaScript'inin, hangi etkinlik raporlarını alması gerektiğini kaydetmesi gerekir. Satış tarafı, etkinlik düzeyindeki bilgileri raporlamaktan sorumludur.

Protected Audience, işaretçileri kaydederek kazanan bir açık artırmayla ilgili gelecekteki etkinliklere abone olma mekanizması sağlar. Bir satıcının reportResult() JavaScript işlevinde, arz tarafı platformları registerAdBeacon() işlevini kullanarak platformun işaretçilerini kaydedebilir. Benzer şekilde, satın alma tarafı platformları registerAdBeacon() yöntemini reportWin() JavaScript işlevlerinden çağırabilir.

registerAdBeacon(beacons)

Giriş:

• event_key: Hangi etkileşim türünün kaydedileceğini belirten bir dize. Bu, platformun açık artırma sonuçlarını bildirirken ping gönderdiği bitiş noktasını aramak için anahtar olarak kullanılır.
• reporting_url: Etkinliği işlemek için reklam teknolojisi platformuna ait URL.

Etkinlik anahtarları, açık artırma sonuçlarını bildirmekten sorumlu olan satış tarafı SDK'sına ait dize tanımlayıcılardır. Geri arama yapılabilmesi için reklam teknolojileri, etkinlikleri raporlarken satış tarafı tarafından kullanılan anahtarlarla eşleşen anahtarlara sahip işaretçiler kaydeder. Belirli bir özel kitle için kaydedilebilecek anahtarların miktarı ve uzunluğuyla ilgili sınırlar olsa da bu anahtarların k-anonim olması gerekmez. reportEvent() çağrılırsa açık artırmayı yürüten satış tarafı platformları, bu etkinlik raporlarını almaya her zaman uygundur. Bu raporları yalnızca kazanan satın alma tarafı platformu alabilir.

Satış tarafı raporlaması

Platform, selectAds() API için satıcının Karar mantığı URL'si parametresinden indirilen, arz tarafı tarafından sağlanan koddaki 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ı sinyalleri: Alıcının reportWin işlevine iletilecek bir JSON nesnesi.

Arz tarafı, açık artırma ve kazanan reklam hakkında daha fazla bilgi edinmek için raporlama URL'sine alakalı sinyaller kodlayabilir. Örneğin, aşağıdaki gibi sinyaller içerebilir:

• Reklam oluşturma URL'si
• Kazanan teklif tutarı
• Uygulama adı
• Sorgu tanımlayıcıları
• Alıcı sinyalleri: Arz tarafı ile talep tarafı arasında veri paylaşımını desteklemek için platform, bu dönüş değerini talep tarafı raporlama koduna giriş parametresi olarak iletir.

Satın alma tarafı raporları

Platform, açık artırmayla ilişkili özel kitlenin Bidding logic URL meta verilerinden indirilen, talep tarafı tarafından sağlanan koddaki 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. Satın alma tarafı platformunun raporlama URL'sine iletmesi gereken tüm bilgiler bu veriden gelebilir.
• signals_for_buyer, satıcı tarafı raporu sonucunun çıkışıdır. Bu, satış tarafı platformuna raporlama amacıyla alıcı tarafı platformuyla veri paylaşma fırsatı verir.
• contextual_signals, uygulama adı gibi bilgileri, custom_audience_signals ise ö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

Etkinliklerin raporlanması yalnızca açık artırmanın gösterim raporlaması tamamlandıktan sonra mümkündür. Satış tarafı SDK'sı, tüm etkinliklerin raporlanmasından sorumludur. Platform, yakın zamanda çalıştırılan açık artırmayı, raporlanan etkinlik anahtarını, bu anahtarla ilişkili verileri, raporun alıcıya mı yoksa satıcıya mı (veya her ikisine de) gönderilmesi gerektiğini ve reklam etkinlikleri için isteğe bağlı bir giriş etkinliğini belirten bir ReportEventRequest alan bir API sunar. İ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 kaynağından alınan ve kısa süre önce çalıştırılan bir açık artırmanın AdSelectionId olmalıdır.
• event_key, etkileşim etkinliğini açıklayan, satıcı tarafında 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 ya da her ikisi de olabilir.
• input_event (isteğe bağlı), Attribution Reporting API ile entegrasyon için kullanılır. Tıklama etkinliği için InputEvent nesnesi, görüntüleme etkinliği için ise null'dur. Bu parametre hakkında daha fazla bilgi için Attribution Reporting API Entegrasyonu başlıklı makaleyi inceleyin.

Satış tarafı SDK'sı reportEvent işlevini çağırdıktan sonra ve reporting_destinations işaretine bağlı olarak platform, event_key ile alıcılar ve satıcılar tarafından reportWin ve reportResult JavaScript işlevlerine kaydedilen anahtarları eşleştirmeye çalışır. Eşleşme varsa platform, event_data öğesini ilişkili reporting_url öğesine POST eder. İsteğin content type, gövdesi event_data olan düz metindir. Bu istek, en iyi çabayla yapılır ve ağ hatası, sunucu hatası yanıtı durumunda 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'leri (ARA) arasında API'ler arası işlevsellik sağlıyoruz. Bu işlev, reklam teknolojisi sağlayıcıların çeşitli yeniden pazarlama taktiklerindeki ilişkilendirme performanslarını değerlendirmelerini sağlar. Böylece, hangi kitle türlerinin en yüksek YG'yi sağladığını anlayabilirler.

Bu API'ler arası entegrasyon sayesinde reklam teknolojisi şirketleri ş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 tarafındaki anahtar eşlemelerine Protected Audience açık artırmasından elde edilen açık artırma verilerini dahil etme (Attribution Reporting API'yi kullanarak). Daha fazla bilgi için ARA tasarım önerisine bakın.

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

• Protected Audience kullanılarak bu etkinlik etkileşimlerini bildirmek için kullanılan URL, görüntüleme 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 (veya reklam yerleşimi ya da görüntüleme süresi gibi reklamla ilgili diğer alakalı bağlamsal bilgiler) iletmeyi seçebilir. Böylece, reklam teknolojisi toplu kampanya performansını incelerken bu meta veriler özet raporlara yayılabilir.

Kaynak kaydını etkinleştirme

reportEvent(), yeni bir isteğe bağlı parametreyi InputEvent kabul edecek. Reklam işaretçilerini kaydeden kazanan alıcılar, hangi reportEvent raporlarının Attribution Reporting API'lerine kayıtlı kaynak olarak kaydedileceğini seçebilir. İstek başlığı Attribution-Reporting-Eligible, reportEvent() adresinden gönderilen tüm etkinlik raporlama isteklerine eklenecek. Uygun ARA başlıklarına sahip tüm yanıtlar, diğer normal ARA kaynağı kaydı yanıtları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ü ayırt etmek için InputEvents kullanılır. ARA kaynak kaydında olduğu gibi, reportEvent() API'si platform tarafından doğrulanmış bir InputEvent öğesini tıklama etkinliği olarak yorumlar. InputEvent eksik, null veya geçersizse kaynak kaydı görüntüleme olarak kabul edilir.

Açık artırma sonrası eventData hassas bilgiler içerebileceğinden platform, yönlendirilen kaynak kayıt isteklerinde eventData değerini bırakır.

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

Bu örnekte, açık artırmadan, oluşturulan reklamdan ve dönüşüm uygulamasından gelen verileri birlikte ilişkilendirmek isteyen alıcı perspektifinden bakacağız.

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

İş akışı: Açık artırma başlamadan önce alıcı, programatik gerçek zamanlı teklif verme ("RTB") teklif yanıtı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.

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

Bu sürecin sonunda alıcı, her biriyle ilişkilendirmek için kullanılabilecek benzersiz kimlik kullanılarak ilişkilendirilebilen bir açık artırma raporu, etkileşim raporu ve dönüşüm raporuna sahip olur.

Benzer iş akışı, ilişkilendirme verilerine erişmesi gereken bir satıcı için de geçerlidir ve satıcı, registerAdBeacon() ile göndermek üzere 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üzdeki reklam seçimi mantığı, reklam adaylarının açık artırma için seçilip seçilmeyeceğini belirlemek amacıyla bütçe tükenme durumu gibi gerçek zamanlı bilgiler gerektirir. Hem satın alma tarafı hem de satış tarafı platformları, bu bilgiyi işlettikleri sunuculardan alabilir. Bu sunucular kullanılarak hassas bilgilerin sızdırılmasını en aza indirmek için teklifte aşağıdaki kısıtlamalar önerilmektedir:

• Bu sunucuların, bu bölümün ilerleyen kısımlarında açıklanan davranışları, kullanıcı bilgilerinin sızmasına neden olmaz.
• Sunucular, gördüğü verilere göre anonimleştirilmiş profiller oluşturmaz. Yani "güvenilir" olması gerekir.

Satın alma tarafı: Satın alma tarafı, satın alma tarafı teklif verme mantığını başlattıktan sonra platform, güvenilir sunucudan güvenilir teklif verme verilerini HTTP ile getirir. URL, işlenen özel kitlenin Güvenilir Teklif Sinyalleri meta verilerinde bulunan URL ve anahtarlar eklenerek oluşturulur. Bu getirme işlemi yalnızca cihaz üzerinde özel kitlelerden gelen reklamlar işlenirken yapılır. Bu aşamada, satın alma tarafı bütçeleri zorunlu kılabilir, kampanyanın duraklatılmış / devam ettirilmiş durumunu kontrol edebilir, hedefleme gerçekleştirebilir vb.

Bu, özel kitledeki güvenilir teklif sinyali meta verilerine dayalı olarak güvenilir teklif verme verilerini getirmek için kullanılan örnek bir URL'dir:

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 işlevlerine sunulacak bir JSON nesnesi olmalıdır.

Satıcı tarafı: Bu satın alma tarafı akışına benzer şekilde, satıcı tarafı da açık artırmada dikkate alınan reklam öğeleri hakkında bilgi getirmek isteyebilir. Örneğin, bir yayıncı marka güvenliği endişeleri nedeniyle belirli reklam öğelerinin uygulamasında gösterilmemesini isteyebilir. Bu bilgiler, satın alma tarafı açık artırma mantığına getirilip sunulabilir. Satın alma tarafı güvenilir sunucu aramasına benzer şekilde, satış tarafı güvenilir sunucu araması da bir HTTP getirme işlemi kullanılarak yapılır. URL, verilerin getirilmesi gereken reklam öğelerinin oluşturma URL'leri ile güvenilir puanlama sinyalleri URL'sinin eklenmesiyle 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 kullanılan ö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, ç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 dayalı olduğu güvenle kabul edilebilir.
• 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 ve web'de Özel Korumalı Alan ile uyumlu platformlar için ortak bir güvenilir anahtar-değer türü sunucusu kullanabilir.