Korunan Uygulama Sinyalleri geliştirici kılavuzu

ad techproject_path: /_project.yaml book_path: /_book.yaml keywords: api:ProtectedAppSignals, docType:Guide, skill:Beginner, audienceAdBuyer, audienceAdSeller, topicAdAuction, contentTypeFundamental, category:Mobile, apiGroupAds

Bu belge, geliştiricilerin Protected App Signals API ile denemeler yapmasına yardımcı olmak için API yüzeyindeki tüm API'leri açıklar, test ortamının nasıl ayarlanacağını ayrıntılı olarak anlatır ve yapılandırma ile komut dosyalarıyla ilgili örnekler sunar.

Sürüm geçmişi

Ocak 2024

PAS MVP sürümünü destekleyen geliştirici kılavuzunun ilk sürümü

Mart 2024

Android API'nin M-2024-05 sürümünü ve sunucu tarafı bileşenlerinin Nisan 2024 sürümünü desteklemek için API'de yapılan değişiklikler. En önemli değişiklikler:

• Cihaz üzerinde API için gereken izinlerle ilgili ayrıntılar eklendi.
• Cihaz üzerindeki sinyallerin kota yönetimi hakkında ayrıntılar eklendi.
• Bağlamsal reklam alma ve çıkış desteğiyle ilgili değişiklikler içeren generateBid imzası güncellendi.
• Çıkış desteği de dahil olmak üzere reportWin dokümanları güncellendi.
• BYOS reklam alma desteğini kaldırarak ve reklam alma UDF'sini belgeleyerek Reklam Alma API'si dokümanlarını güncelleyin.

API'ye genel bakış

Protected Signals API yüzeyi, farklı sistemlerde API'nin farklı alt kümelerini içerir:

• Android API'leri:
  • Aşağıdakilerden oluşan Signal Curation API:
  • Update Signals API
  • Signals Encoding API
  • Protected Auction Support API: Protected App Signals kullanılarak teklif verme ve açık artırma (B&A) sunucularında Protected Auction'ı çalıştırmak için SDK'lar tarafından kullanılır.
• Sunucu tarafı API'leri:
  • Protected Auction API: Teklifli sistem ve açık artırma sunucularında çalışan bir dizi JS komut dosyası. Bu API, satıcıların ve alıcıların korumalı açık artırmayı uygulamak için mantık yazmasına olanak tanır.
  • Reklam Alma API'si: Alıcının teklif sunma sunucusuna sağlanan bağlamsal ve kullanıcı bilgilerine göre aday reklamların listesini sağlamaktan sorumludur.

Android istemcisi

İstemci tarafında Protected App Signals yüzeyi üç farklı API'den oluşur:

• Güncelleme Sinyalleri: Cihazdaki sinyallerin düzenlenmesini sağlayan bir Android sistem API'si.
• Sinyal Kodlama: Sinyalleri açık artırma sırasında sunucuya gönderilmeye hazırlamak için kullanılan bir JavaScript API'sidir.
• Korumalı açık artırma desteği: Teklif verme ve açık artırma sunucularında korumalı açık artırmanın yürütülmesini destekleyen bir API. Bu API, Protected App Signals'a özel değildir ve Protected Audience API için açık artırmaları desteklemek amacıyla da kullanılır.

Update Signals API

Update Signals API, reklam teknolojisi sağlayıcılarına bir alıcı adına kullanıcı ve uygulamayla ilgili sinyalleri kaydetme olanağı sunar. API, bir temsil modeline göre çalışır. Arayan, çerçevenin karşılık gelen sinyalleri ve bu sinyalleri açık artırmada kullanılacak şekilde kodlama mantığını getirdiği bir URI sağlar.

API için android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS izni gerekir.

updateSignals() API, hangi sinyallerin ekleneceğini veya kaldırılacağını ve bu sinyallerin açık artırmaya nasıl hazırlanacağını açıklayan URI'den bir JSON nesnesi alır.

Executor executor = Executors.newCachedThreadPool();
ProtectedSignalsManager protectedSignalsManager
     =  ProtectedSignalsManager.get(context);

// Initialize a UpdateSignalsRequest
UpdateSignalsRequest updateSignalsRequest = new
  UpdateSignalsRequest.Builder(Uri.parse("https://example-adtech1.com/signals"))
      .build();

OutcomeReceiver<Object, Exception> outcomeReceiver = new OutcomeReceiver<Object, Exception>() {
  @Override
  public void onResult(Object o) {
    //Post-success actions
  }

  @Override
  public void onError(Exception error) {
    //Post-failure actions
  };

// Call updateSignals
protectedSignalsManager.updateSignals(updateSignalsRequest,
    executor,
    outcomeReceiver);

Platform, sinyal güncellemelerini getirmek için istekte sağlanan URI'ye bir https isteği gönderir. Yanıt, sinyal güncellemelerinin yanı sıra ham sinyalleri kodlanmış yüke dönüştürmek için kodlama mantığını barındıran bir uç nokta da içerebilir. Sinyal güncellemelerinin JSON biçiminde olması ve aşağıdaki anahtarları içermesi beklenir:

JSON nesnesinin üst düzey anahtarları şu beş komuttan biriyle eşleşmelidir:

Örnek bir JSON isteği aşağıdaki gibi görünür:

{
    "put": {
        "AAAAAQ==": "AAAAZQ==",
        "AAAAAg==": "AAAAZg=="
    },
    "append": {
        "AAAAAw==": {
            "values": [
                "AAAAZw=="
            ],
            "max_signals": 3
        }
    },
    "put_if_not_present": {
        "AAAABA==": "AAAAaQ==",
        "AAAABQ==": "AAAAag=="
    },
    "update_encoder": {
        "action": "REGISTER",
        "endpoint": "https://adtech1.com/Protected App Signals_encode_script.js"
    }
}

Sinyallerin cihaz üzerinde 10-15 KB civarında bir kotası olacaktır. Kota aşıldığında PPAPI, FIFO stratejisini kullanarak sinyalleri çıkarır. Çıkarma işlemi, çıkarma sıklığını azaltmak için kısa süreliğine kotanın biraz aşılmasına izin verir.

Signals Encoding API

Alıcıların, cihazda depolanan ve Koruma Altındaki Açık Artırma sırasında sunucuya gönderilecek sinyalleri kodlamak için kullanılacak bir JavaScript işlevi sağlaması gerekir. Alıcılar, bir UpdateSignal API isteğine verilen yanıtlardan herhangi birinde "update_encoder" anahtarını kullanarak bu komut dosyasının getirilebileceği URL'yi ekleyerek komut dosyasını sağlayabilir. Komut dosyasının imzası şu şekilde olmalıdır:

function encodeSignals(signals, maxSize) {
  let result = new Uint8Array(maxSize);
  // first entry will contain the total size
  let size = 1;
  let keys = 0;
  
  for (const [key, values] of signals.entries()) {
    keys++;
    // In this encoding we only care about the first byte
    console.log("key " + keys + " is " + key)
    result[size++] = key[0];
    result[size++] = values.length;
    for(const value of values) {
      result[size++] = value.signal_value[0];
    }
  }
  result[0] = keys;
  
  return { 'status': 0, 'results': result.subarray(0, size)};
}

signals parametresi, 4 boyutunda UInt8Arrays biçimindeki anahtarlardan Protected App Signals nesnelerinin listelerine yönelik bir haritadır. Her Protected App Signals nesnesinde üç alan bulunur:

• signal_value: Sinyalin değerini temsil eden bir UInt8Array.
• creation_time: Sinyallerin oluşturulma zamanını epoch saniyesi cinsinden gösteren bir sayı.
• package_name: Sinyali oluşturan paketin adını temsil eden bir dize.

maxSize parametresi, çıkış için izin verilen en büyük dizi boyutunu açıklayan bir sayıdır.

İşlev, iki alan içeren bir nesne çıkışı vermelidir:

• status: Komut dosyası başarıyla çalıştırıldıysa 0 olmalıdır.
• results: Uzunluğu maxSize değerinden küçük veya bu değere eşit olan bir UInt8Array olmalıdır. Bu dizi, açık artırmalar sırasında sunucuya gönderilir ve prepareDataForAdRetrieval komut dosyası tarafından hazırlanır.

Kodlama, reklam teknolojilerine özellik mühendisliğinin ilk aşamasını sağlar. Bu aşamada, ham sinyalleri kendi özel mantıklarına göre birleştirilmiş sürümlere sıkıştırmak gibi dönüşümler gerçekleştirebilirler. Güvenilir Yürütme Ortamları'nda (TEE) çalışan bir korumalı açık artırma sırasında, reklam teknolojisi özel mantığının kodlamayla oluşturulan sinyal yüklerine okuma erişimi olacağını unutmayın. Alıcının B&A TEE'sinde çalışan ve Kullanıcı Tarafından Tanımlanan İşlev (UDF) olarak bilinen özel mantık, reklam seçimi (reklam alma ve teklif verme) gerçekleştirmek için yayıncı uygulaması tarafından sağlanan kodlanmış sinyallere ve diğer bağlamsal sinyallere okuma erişimine sahip olur.

Sinyal kodlama

Kayıtlı sinyalleriyle kodlama mantığı sağlayan alıcıların sinyalleri her saat açık artırma yüküne kodlanır.Açık artırma yükünün bayt dizisi cihazda kalıcı hale getirilir, şifrelenir ve Protected Auction'a dahil edilecek reklam seçimi verilerinin bir parçası olarak satıcılar tarafından toplanır. Test için aşağıdaki komutu çalıştırarak bu kodlamayı saatlik sıklığı dışında tetikleyebilirsiniz:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 29

Kodlayıcı mantığı sürümü oluşturma

Reklam teknolojisi özel kodlayıcı mantığını indirme isteğinde bulunulduğunda, reklam teknolojisi uç noktası yanıt üstbilgilerinde bir sürüm numarasıyla yanıt verebilir. Bu sürüm, cihazdaki kodlayıcı mantığıyla birlikte kalıcı hale getirilir. Ham sinyaller kodlandığında, kodlanmış yük, kodlama için kullanılan sürümle birlikte kalıcı hale getirilir. Bu sürüm, Protected Auction sırasında B&A sunucusuna da gönderilir. Böylece reklam teknolojisi sağlayıcılar, teklif ve kodlama mantıklarını sürüme göre ayarlayabilir.

Response header for providing encoder version : X_ENCODER_VERSION

Protected Auction Support API

Cihaz tarafında, Protected App Signals için açık artırma yürütmek korunan kitleler için açık artırma yürütmekle aynıdır.

Teklif ve Açık Artırma Hizmetleri

Sunucu tarafı API'leri şunlardır:

• Protected Auction API: Alıcıların ve satıcıların, teklif verme ve açık artırma mantığını belirlemek için sahip oldukları B&A bileşenlerine dağıtabileceği bir dizi JS işlevi veya UDF.
• Reklam Alma API'si: Alıcılar, Protected App Signal açık artırması için bir dizi aday reklam sağlamaktan sorumlu olacak bir REST uç noktası uygulayarak bu API'yi uygulayabilir.

Protected Auction API

Protected Auction API, alıcıların ve satıcıların açık artırma ve teklif mantıklarını uygulamak için kullanabileceği JS API'si veya UDF'lerden oluşur.

Alıcı reklam teknolojisi kullanıcı tanımlı işlevleri

prepareDataForAdRetrieval UDF

TEE Ad Retrieval hizmetinden reklam adayları getirmek için Protected App Signals kullanılmadan önce alıcıların Protected App Signals'ı ve satıcı tarafından sağlanan diğer verileri kodunu çözüp hazırlaması gerekir. Alıcılar prepareDataForAdRetrieval UDF çıkışı, teklif için en iyi k aday reklamı almak üzere reklam alma hizmetine iletilir.

// Inputs
// ------
// encodedOnDeviceSignals: A Uint8Array of bytes from the device.
// encodedOnDeviceSignalsVersion: An integer representing the encoded
//   version of the signals.
// sellerAuctionSignals: Information about auction (ad format, size) derived
//                       contextually.
// contextualSignals: Additional contextual signals that could help in
//                    generating bids.
//
// Outputs
// -------
// Returns a JSON structure to be used for retrieval.
// The structure of this object is left to the ad tech.
function prepareDataForAdRetrieval(encodedOnDeviceSignals,encodedOnDeviceSignalsVersion,sellerAuctionSignals,contextualSignals) {
   return {};
}

generateBid kullanıcı tanımlı işlevi

En iyi k aday reklam döndürüldükten sonra reklam adayları, alıcının özel teklif verme mantığına generateBid UDF iletilir:

// Inputs
// ------
// ads: Data string returned by the ads retrieval service. This can include Protected App Signals
//   ads and related ads metadata.
// sellerAuctionSignals: Information about the auction (ad format, size),
//                       derived contextually
// buyerSignals: Any additional contextual information provided by the buyer
// preprocessedDataForRetrieval: This is the output of this UDF.
function generateBid(ads, sellerAuctionSignals, buyerSignals,
                    preprocessedDataForRetrieval,
                    rawSignals, rawSignalsVersion) {
    return { "ad": <ad Value Object>,
             "bid": <float>,
             "render": <render URL string>,
             'adCost': <optional float ad cost>,
             "egressPayload": <limitedEgressPayload>,
             "temporaryUnlimitedEgressPayload": <temporaryUnlimitedEgressPayload>
    };
}

Bu işlevin çıkışı, bir reklam adayı için tek bir tekliftir ve ProtectedAppSignalsAdWithBidMetadata ile eşdeğer bir JSON olarak gösterilir. İşlev, model eğitimini etkinleştirmek için reportWin'a iletilecek iki dizi de döndürebilir (çıkış ve model eğitimi hakkında daha fazla bilgi için PAS açıklayıcısındaki raporlama bölümüne bakın).

reportWin UDF

Bir açık artırma sona erdiğinde açık artırma hizmeti, alıcılar için raporlama URL'leri oluşturur ve reportWin UDF'leri kullanarak işaretçileri kaydeder (Bu, Protected Audience için kullanılan reportWin işleviyle aynıdır). Bu, reklam istemci tarafından oluşturulduktan sonra cihaz tarafından pinglenir. Bu yöntemin imzası, Protected Audience sürümüyle neredeyse aynıdır. Tek fark, model eğitimini etkinleştirmek için kullanılan ve generateBid sonuçlarıyla doldurulan iki ek parametre (egressPayload ve temporaryUnlimitedEgressPayload) içermesidir.

// Inputs / Outputs
// ----------------
// See detailed documentation here.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
                   buyerReportingSignals,
                   egressPayload, temporaryUnlimitedEgressPayload) {
  // ...
}

Satıcı reklam teknolojisi kullanıcı tanımlı işlevleri

scoreAd UDF

Bu kullanıcı tanımlı işlev, satıcılar tarafından alıcılardan alınan reklamlardan hangisinin açık artırmayı kazanacağını seçmek için kullanılır.

function scoreAd(adMetadata, bid, auctionConfig,
                 trustedScoringSignals, bid_metadata) {
  // ...
  return {desirability: desirabilityScoreForThisAd,
              allowComponentAuction: true_or_false};
}

reportResult UDF

Bu UDF, satıcının (sonunda) kazanan reklamla ilgili bilgilerle etkinlik düzeyinde raporlama yapmasına olanak tanır.

function reportResult(auctionConfig, reporting_metadata) {
  // ...
  registerAdBeacon({"click", clickUrl,"view", viewUrl});
  sendReportTo(reportResultUrl);
  return signalsForWinner;
}

Ad Retrieval API

MVP sürümünde, reklam alma hizmeti alıcı tarafından yönetilen ve barındırılan bir hizmet olacak, teklif verme hizmeti ise bu hizmetten reklam adaylarını alacaktır. Nisan 2024'ten itibaren reklam alma sunucusunun güvenilir yürütme ortamında (TEE) çalışması ve bir GRPC/proto arayüzü sunması gerekecek. Reklam teknolojisi şirketleri bu sunucuyu kurmalı ve B&A yığını dağıtımının bir parçası olarak URL'sini sağlamalıdır. TEE'de çalışan bu hizmetin bir uygulaması Özel Korumalı Alan GitHub'da mevcuttur. Belgelerin geri kalanında, dağıtımda kullanılan kodun bu olduğu varsayılmaktadır.

Nisan 2024'ten itibaren B&A sürümleri, bağlamsal yol reklamı almayı desteklemektedir. Bu durumda teklif sunma sunucusu, açık artırmanın bağlamsal bölümünde GZT sunucusu tarafından gönderilen reklam kimliklerinin bir listesini alır. Tanımlayıcılar, teklif verme aşamasında kullanılacak tüm reklamla ilgili bilgileri (ör. reklam oluşturma URL'si, meta veriler ve top-k seçiminde kullanılacak reklam yerleştirmeleri) getirmek için TEE KV sunucusuna gönderilir. Bu ikinci yolun dağıtılması için herhangi bir mantık gerekmez. Bu nedenle, burada yalnızca TEE tabanlı reklam alma kullanım alanının nasıl yapılandırılacağını açıklayacağız.

getCandidateAds UDF

function getCandidateAds(requestMetadata, preparedDataForAdRetrieval,
                      deviceMetadata, contextualSignals, contextualAdIds,) {
    return adsMetadataString;
}

Burada:

• requestMetadata: JSON. İstek başına sunucu meta verileri UDF'ye iletilir. Şimdilik boş.
• preparedDataForAdRetrieval: Bu alanın içeriği, reklam alma stratejisine bağlıdır. Bağlamsal reklam alma durumunda bu parametre, cihazdan gelen ve teklif verme hizmetinden geçirilen ham sinyalleri içerir. Reklam Alma Sunucusu kullanılarak TEE reklamı alınması durumunda bu parametre, prepareDataForAdRetrieval UDF'nin sonucunu içerir. Not: Bu aşamada, korumalı uygulama sinyallerinin kodu çözülür ve şifreleri kaldırılır.
• deviceMetadata: Satıcının reklam hizmeti tarafından iletilen cihaz meta verilerini içeren JSON nesnesi. Daha fazla bilgi için B&A dokümanlarına bakın.
  • X-Accept-Language: Cihazda kullanılan dil.
  • X-User-Agent: Cihazda kullanılan kullanıcı aracısı.
  • X-BnA-Client-IP: Cihazın IP adresi.
• contextualSignals: Aynı TTP tarafından işletilen bağlamsal teklif sunma sunucusundan kaynaklanan rastgele dize. Kullanıcı tanımlı işlevin, dizeyi çözebilmesi ve kullanabilmesi beklenir. Bağlamsal sinyaller, Protected App Signals kullanılarak iletilen korumalı yerleştirme için makine öğrenimi modeli sürüm bilgileri gibi her türlü bilgiyi içerebilir.
• contextualAdIds: Reklam kimliklerinin isteğe bağlı bir listesini içeren JSON nesnesi.

İşlev, başarılı olduğunda bir dize döndürmelidir. Dize, teklif sunucusuna döndürülür. Teklif sunucusu da dizeyi generateBid UDF'ye iletir. Dize yalnızca temel bir dize olabilir ancak büyük olasılıkla şeması her reklam teknolojisi tarafından ayrı ayrı tanımlanan bir serileştirilmiş nesne olmalıdır. Reklam teknolojisinin generateBidmantığı dizeyi tanıyıp kullanabildiği sürece şemayla ilgili bir kısıtlama yoktur.

Sisteminizi geliştirme için ayarlama

Android

Android geliştirme ortamınızı kurmak için aşağıdakileri yapmanız gerekir:

1. Developer Preview 10 görüntüsünü çalıştıran bir emülatör (tercih edilir) veya fiziksel cihaz oluşturun.
2. Aşağıdaki komutu çalıştırın:

adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity

Ardından, uygulama tarafından önerilen reklamlara izin vermek için gösterilen seçeneği belirleyin.

1. İlgili API'leri etkinleştirmek için aşağıdaki komutu çalıştırın. Devre dışı bırakma varsayılan yapılandırması düzenli olarak senkronize edileceğinden bu işlemi zaman zaman yeniden çalıştırmanız gerekebilir.

adb shell device_config put adservices fledge_custom_audience_service_kill_switch false;  adb shell device_config put adservices fledge_select_ads_kill_switch false; adb shell device_config put adservices fledge_on_device_auction_kill_switch false; adb shell device_config put adservices fledge_auction_server_kill_switch false; adb shell "device_config put adservices disable_fledge_enrollment_check true";  adb shell device_config put adservices ppapi_app_allow_list '\*'; adb shell device_config put adservices fledge_auction_server_overall_timeout_ms 60000;

1. Cihazı yeniden başlatın.
2. Cihazın açık artırma anahtarlarını geçersiz kılarak açık artırma anahtarı sunucunuza yönlendirin. Yanlış anahtarların önbelleğe alınmasını önlemek için bu adımı açık artırma çalıştırmayı denemeden önce çalıştırmanız önemlidir.

Teklif ve Açık Artırma Hizmetleri

B&A sunucularını ayarlamak için self servis kurulum dokümanlarına bakın.

Bu belgede, satıcılar için herhangi bir değişiklik yapılması gerekmediğinden alıcıya özel sunucuların nasıl yapılandırılacağı ele alınacaktır.

Ön koşullar

Bir ÖY hizmet yığını dağıtmadan önce alıcı reklam teknolojisinin şunları yapması gerekir:

• Kendi TEE reklam alma hizmetlerini dağıttıklarını doğrulayın (ilgili bölüme bakın).
• Reklam teknolojisinin gerekli tüm UDF'lerin (prepareDataForAdRetrieval, generateBid, reportWin, getCandidateAds) tanımlandığını ve barındırıldığını doğrulayın.

Protected Audience ile Protected Auction'ın B&A ile nasıl çalıştığını anlamak da faydalı olacaktır ancak zorunlu değildir.

Terraform yapılandırması

Korunan uygulama sinyallerini kullanmak için reklam teknolojisi sağlayıcıların:

• B&A'da Protected App Signals desteğini etkinleştirin.
• prepareDataForAdRetrieval, generateBid ve reportWin için yeni UDF'lerin getirilebileceği URL uç noktalarını sağlayın.

Ayrıca bu kılavuzda, yeniden pazarlama için B&A'yı kullanmak isteyen reklam teknolojilerinin, yeniden pazarlama açık artırması için mevcut tüm yapılandırma işaretlerini her zamanki gibi ayarlamaya devam edeceği varsayılmaktadır.

Alıcı reklam teknolojisi yapılandırması

Bu demo dosyasını örnek olarak kullanırsak alıcıların aşağıdaki işaretleri ayarlaması gerekir:

• Protected App Signals'ı etkinleştirin: Protected App Signals verilerini toplamak için etkinleştirilir.
• Protected App Signals URL'leri: Protected App Signals sunucularının URL'leri olarak ayarlayın.

Reklam teknolojileri, aşağıdaki alanlardaki yer tutuculara doğru URL'leri yerleştirmelidir:

module "buyer" {
  # ... More config here.

  runtime_flags = {
    # ... More config here.

    ENABLE_PROTECTED_APP_SIGNALS                  = "true"
    PROTECTED_APP_SIGNALS_GENERATE_BID_TIMEOUT_MS = "60000"
    TEE_AD_RETRIEVAL_KV_SERVER_ADDR               = "<service mesh address of the instance>"
    AD_RETRIEVAL_TIMEOUT_MS                       = "60000"
    BUYER_CODE_FETCH_CONFIG                       = <<EOF
    {
        "protectedAppSignalsBiddingJsUrl": "<URL to Protected App Signals generateBid UDF>",
        "urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
        "urlFetchPeriodMs": 13000000,
        "prepareDataForAdsRetrievalJsUrl": "<URL to the UDF>"
    }
    EOF

  }  # runtime_flags

}  # Module "buyer"

Satıcı reklam teknolojisi yapılandırması

Bu demo dosyasını örnek olarak kullanan satıcılar aşağıdaki işaretleri ayarlamalıdır. (Not: Burada yalnızca korumalı uygulama sinyalleriyle ilgili yapılandırma vurgulanır.) Reklam teknolojileri, yer tutucularda doğru URL'leri kullandıklarını doğrulamalıdır:

module "seller" {
  # ... More config here.

  runtime_flags = {
    # ... More config here.

    ENABLE_PROTECTED_APP_SIGNALS                  = "true"

    SELLER_CODE_FETCH_CONFIG                           = <<EOF
  {
    "urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
    "urlFetchPeriodMs": 13000000,
    "protectedAppSignalsBuyerReportWinJsUrls": {"<Buyer Domain>": "URL to reportWin UDF"}
  }
  EOF

  }  # runtime_flags

}  # Module "seller"

KV ve Reklam Alma Hizmetleri

Reklam alımını desteklemek için seçilen stratejilere bağlı olarak sistem, KV hizmetinin bir veya iki örneğinin dağıtılmasını gerektirir. TEE tabanlı reklam alma için kullanılan KV örneğini Ad Retrieval Server, bağlama dayalı yol tabanlı alma işlemini destekleyen örneği ise KV Lookup Server olarak adlandıracağız.

Her iki durumda da sunucu dağıtımı, KV sunucusu GitHub'da bulunan dokümanlara göre yapılır. İki durum arasındaki fark, arama durumunun herhangi bir ek yapılandırma olmadan kullanıma hazır olması, alma durumunun ise alma mantığını uygulamak için getCandidateAds UDF'nin dağıtılmasını gerektirmesidir. Daha fazla bilgi için KV sunucusu ilk katılım kılavuzuna göz atın. B&A'nın, her iki hizmetin de teklif hizmetiyle aynı hizmet ağında dağıtılmasını beklediğini unutmayın.

Örnek Kurulum

Şu senaryoyu ele alalım: Bir reklam teknolojisi, Protected App Signals API'yi kullanarak kullanıcıların uygulama kullanımına göre alakalı sinyalleri depolar. Örneğimizde, birkaç uygulamadaki uygulama içi satın alma işlemlerini temsil eden sinyaller depolanır. Açık artırma sırasında şifrelenmiş sinyaller toplanır ve B&A'da çalışan bir Protected Auction'a iletilir. B&A'da çalışan alıcının kullanıcı tanımlı işlevleri, reklam adaylarını getirmek ve teklif hesaplamak için sinyalleri kullanır.

[Alıcı] Sinyal örnekleri

Anahtarı 0, değeri 1 olan bir sinyal ekler.

{
  "put": {
    "AA==": "AQ=="
  },
  "update_encoder": {
    "action": "REGISTER",
    "endpoint": "https://example.com/example_script"
  }
}

Anahtarı 1, değeri 2 olan bir sinyal ekler.

{
  "put": {
    "AQ==": "Ag=="
  },
  "update_encoder": {
    "action": "REGISTER",
    "endpoint": "https://example.com/example_script"
  }
}

[Buyer] encodeSignals örneği

Her sinyali iki bayt olarak kodlar. İlk bayt, sinyal anahtarının ilk baytı, ikinci bayt ise sinyal değerinin ilk baytıdır.

function encodeSignals(signals, maxSize) {
  // if there are no signals don't write a payload
  if (signals.size === 0) {
      return {};
  }

  let result = new Uint8Array(signals.size * 2);
  let index = 0;
  
  for (const [key, values] of signals.entries()) {
    result[index++] = key[0];
    result[index++] = values[0].signal_value[0];
  }
  
  return { 'status': 0, 'results': result};
}

[Buyer] prepareDataForAdRetrieval örneği

/**
 * `encodedOnDeviceSignals` is a Uint8Array and would contain
 * the app signals emanating from device. For purpose of the
 * demo, in our sample example, we assume that device is sending
 * the signals with pair of bytes formatted as following:
 * "<ID><In app spending>". Where ID corresponds to an ad category
 * that user uses on device, and the in app spending is a measure
 * of how much money the user has spent in this app category
 * previously. In our example, an ID of 0 will correspond to a
 * fitness ad category and a non-zero ID will correspond to
 * food app category -- though this info will be useful
 * later in the B&A pipeline.
 *
 * Returns a JSON object indicating what type of ad(s) may be
 * most relevant to the user. In a real setup ad techs might
 * want to decode the signals as part of this script.
 *
 * Note: This example script makes use of only encoded device signals
 * but ad tech can take other signals into account as well to prepare
 * the data that will be useful down stream for ad retrieval and
 * bid generation. The max length of the app signals used in this
 * sample example is arbitrarily limited to 4 bytes.
 */
function prepareDataForAdRetrieval(encodedOnDeviceSignals,
                                   encodedOnDeviceSignalsVersion,
                                   sellerAuctionSignals,
                                   contextualSignals) {
  if (encodedOnDeviceSignals.length === 0 || encodedOnDeviceSignals.length > 4 ||
      encodedOnDeviceSignals.length % 2 !== 0) {
     throw "Expected encoded signals length to be an even number in (0, 4]";
  }

  var preparedDataForAdRetrieval = {};
  for (var i = 0; i < encodedOnDeviceSignals.length; i += 2) {
    preparedDataForAdRetrieval[encodedOnDeviceSignals[i]] = encodedOnDeviceSignals[i + 1];
  }
  return preparedDataForAdRetrieval;
}

[Alıcılar] Örnek reklam alma UDF'si

Örneğimizde, reklam alma sunucusu ilk k reklam adayının her biri için meta veri (örneğimizde her reklamın kimliği, ancak daha sonra teklif oluşturmada faydalı olabilecek başka veriler de içerebilir) gönderir.

function getCandidateAds(requestMetadata, protectedSignals, deviceMetadata,
                      contextualSignals,   contextualAdIds,) {
 return "[{\"adId\":\"0\"},{\"adId\":\"1\"}]"

[Alıcılar] generateBid örneği

/**
 * This script receives the data returned by the ad retrieval service
 * in the `ads` argument. This argument is supposed to contain all
 * the Protected App Signals related ads and the metadata obtained from the retrieval
 * service.
 *
 * `preparedDataForAdRetrieval` argument contains the data returned
 * from the `prepareDataForAdRetrieval` UDF.
 *
 * This script is responsible for generating bids for the ads
 * collected from the retrieval service and ad techs can decide to
 * run a small inference model as part of this script in order to
 * decide the best bid given all the signals available to them.
 *
 * For the purpose of the demo, this sample script assumes
 * that ad retrieval service has sent us most relevant ads for the
 * user and this scripts decides on the ad render URL as well as
 * what value to bid for each ad based on the previously decoded
 * device signals. For simplicity sake, this script only considers
 * 2 types of app categories i.e. fitness and food.
 *
 * Note: Only one bid is returned among all the
 * input ad candidates.
 */
function generateBid(ads, sellerAuctionSignals, buyerSignals, preparedDataForAdRetrieval) {
  if (ads === null) {
    console.log("No ads obtained from the ad retrieval service")
    return {};
  }     
        
  const kFitnessAd = "0";
  const kFoodAd = "1";
  const kBuyerDomain = "https://buyer-domain.com";
        
  let resultingBid = 0;
  let resultingRender = kBuyerDomain + "/no-ad";
  for (let i = 0 ; i < ads.length; ++i) {
    let render = "";
    let bid = 0;
    switch (ads[i].adId) {
      case kFitnessAd:
        render = kBuyerDomain + "/get-fitness-app";
        bid = preparedDataForAdRetrieval[kFitnessAd];
        break;
      case kFoodAd:
        render = kBuyerDomain + "/get-fastfood-app";
        bid = preparedDataForAdRetrieval[kFoodAd];
        break;
      default:
        console.log("Unknown ad category");
        render = kBuyerDomain + "/no-ad";
        break;
    }
    console.log("Existing bid: " + resultingBid + ", incoming candidate bid: " + bid);
    if (bid > resultingBid) {
      resultingBid = bid;
      resultingRender = render;
    }
  }
  return {"render": resultingRender, "bid": resultingBid};
}

[Alıcılar] raporu kazanma örneği

reportWin UDF, alıcıya açık artırmayı kazandığını bildirir.

function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
                                       buyerReportingSignals, directFromSellerSignals,
                                       egressPayload,
                                       temporaryUnlimitedEgressPayload) {
  sendReportTo("https://buyer-controlled-domain.com/");
  registerAdBeacon({"clickEvent":"https://buyer-controlled-domain.com/clickEvent"});
  return;
}

[Satıcı] KV sunucusu kurulumu

Satıcılar, reklam oluşturma URL'lerinden karşılık gelen puanlama sinyallerine bir eşleme sağlanması için bir puanlama sinyalleri KV sunucusu oluşturmalıdır. Örneğin: https:/buyer-domain.com/get-fitness-app ve https:/buyer-domain.com/get-fastfood-app alıcı tarafından döndürülürse, satıcı, https://key-value-server-endpoint.com?client_type=1&renderUrls=<render-url-returned-by-the-buyer> üzerinde GET kullanılarak SFE tarafından sorgulandığında aşağıdaki örnek puanlama sinyalleri yanıtına sahip olabilir:

{
   "renderUrls" : {
      "https:/buyer-domain.com/get-fitness-app" : [
         "1",
         "2"
      ],
      "https:/buyer-domain.com/get-fastfood-app" : [
         "3",
         "4"
      ]
   }
}

[Satıcı] scoreAd örneği

/**
 * This module generates a random desirability score for the Protected App
 * Signals ad in this example. In a production deployment,
 * however, the sellers would want to use all the available signals to generate
 * a score for the ad.
 */
function getRandomInt(max) {
  return Math.floor(Math.random() * max);
}

function scoreAd(adMetadata, bid, auctionConfig,
                                   trustedScoringSignals, deviceSignals,
                                   directFromSellerSignals) {
  return {
    "desirability": getRandomInt(10000),
    "allowComponentAuction": false
  };
}

[Seller] reportResult örneği

function reportResult(auctionConfig, sellerReportingSignals, directFromSellerSignals){
  let signalsForWinner = {};
    sendReportTo("https://seller-controlled-domain.com");
    registerAdBeacon({"clickEvent":
                    "https://seller-controlled-domain.com/clickEvent"});
    return signalsForWinner;
}

Örnek uygulama

API'nin bu akışı kullanan bir uygulama oluşturmak için nasıl kullanılabileceğine dair bir örnek olarak, bu örnek depoda bulabileceğiniz bir Protected App Signals örnek uygulaması oluşturduk.