Korunan Uygulama Sinyalleri geliştirici kılavuzu

Geliştiricilerin Protected App Signals API'yi kullanmaya başlamasına yardımcı olmak için bu dokümanda API yüzeyindeki tüm API'ler açıklanmakta, test ortamının nasıl oluşturulacağı ayrıntılı olarak anlatılmakta ve yapılandırma ile komut dosyaları örnekleri verilmektedir.

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 üzerinde sinyal kotası yönetimi hakkında ayrıntılar eklendi
  • generateBid imzasını, bağlama dayalı reklam alma ve çıkış desteğiyle ilgili değişikliklerle güncellendi
  • Çıkış desteği de dahil olmak üzere reportWin dokümanları güncellendi
  • BYOS reklam getirme desteğini kaldırarak ve reklam getirme UDF'sini belgeleyerek Ad Retrieval API belgelerini güncelleme

API'ye genel bakış

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

  • Android API'leri:
    • Sinyal Seçme API'si, aşağıdakilerden oluşur:
    • Update Signals API
    • Signals Encoding API
    • Protected Auction Support API: Protected App Signals'ı kullanarak SDK'lar tarafından teklif verme ve açık artırma (B&A) sunucularında korunan açık artırmayı çalıştırmak için kullanılır.
  • Sunucu tarafı API'ler:
    • 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ı uygulama mantığını yazmasını sağlar.
    • Reklam Alma API'si: Alıcının teklif sunma sunucusuna sunulan içeriğe dayalı 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'sidir.
  • Sinyal Kodlama: Açık artırma sırasında sunucuya gönderilecek sinyalleri hazırlamak için kullanılan bir JavaScript API'sidir.
  • Protected Auction Support: Teklif Verme ve Açık Artırma Sunucularında Protected Auction'un yürütülmesini destekleyen bir API. Bu API, Protected App Signals'a özel değildir ve Protected Audience API açık artırmalarını desteklemek için de kullanılır.

Update Signals API

Update Signals API, reklam teknolojisi sağlayıcılara bir alıcı adına kullanıcı ve uygulamayla ilgili sinyalleri kaydetme olanağı sunar. API, yetkilendirme modeliyle çalışır. Arayan, çerçevenin ilgili sinyalleri alacağı bir URI ve bu sinyalleri açık artırmada kullanılmak üzere kodlayacak mantığı sağlar.

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

updateSignals() API, URI'den hangi sinyallerin ekleneceğini veya kaldırılacağını ve bu sinyallerin açık artırmaya nasıl hazırlanacağını açıklayan 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 almak için istekte belirtilen 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 içerebilir. Sinyal güncellemelerinin JSON biçiminde olması beklenir ve aşağıdaki anahtarlara sahip olabilir:

JSON nesnesinin üst düzey anahtarları beş komuttan birine karşılık gelmelidir:

key

Açıklama

put

Aynı anahtara sahip mevcut sinyallerin üzerine yazarak yeni bir sinyal ekler. Değer

for, anahtarların yerleştirilecek anahtara karşılık gelen base64 dizeleri ve değerlerin yerleştirilecek değere karşılık gelen base64 dizeleri olduğu bir JSON nesnesi.

append

Bir sinyal zaman serisine yeni sinyal/sinyaller ekler ve en eskisini kaldırır

sinyalleri, serinin boyutu belirtilen maksimum boyutu aşarsa yenilerine yer açmak için kullanılır. Bu parametrenin değeri, anahtarların eklenecek anahtara karşılık gelen base64 dizelerinin ve değerlerin "values" ve "maxSignals" olmak üzere iki alana sahip nesnelerin bulunduğu bir JSON nesnesi şeklindedir.

"values": Zaman serisine eklenecek sinyal değerlerine karşılık gelen Base64 dizelerinin listesi.

"maxSignals": Bu zaman serisinde izin verilen maksimum değer sayısı. Eğer

Anahtarla ilişkili mevcut sinyal sayısı maxSignals'ı aşarsa en eski sinyaller kaldırılır. put ile eklenen bir anahtara ekleme yapabileceğinizi unutmayın. Maksimum değer sayısından fazla değer eklemenin başarısızlığa neden olacağını unutmayın.

put_if_not_present

Yalnızca aynı anahtara sahip mevcut sinyaller yoksa yeni bir sinyal ekler. Bunun değeri, anahtarların yerleştirilecek anahtara karşılık gelen base64 dizeleri ve değerlerin yerleştirilecek değere karşılık gelen base64 dizeleri olduğu bir JSON nesnesi olacaktır.

remove

Bir anahtarın sinyalini kaldırır. Bu değerin değeri, silinmesi gereken sinyallerin anahtarlarına karşılık gelen base64 dizelerinin listesidir.

update_encoder

Uç noktayı güncellemek için bir işlem ve kullanılabilecek bir URI sağlar

kodlama mantığını almak için. Güncelleme işlemi sağlamanın alt anahtarı "action" ve

değerleri şu anda yalnızca "REGISTER" (KAYDET) olarak desteklenmektedir. Bu değer, ilk kez sağlanırsa kodlayıcı uç noktasını kaydeder veya mevcut uç noktasının üzerine yeni sağlanan uç noktasıyla yazar. "REGISTER" işlemi için uç noktanın sağlanması gerekir. Kodlayıcı uç noktası sağlamanın alt anahtarı "endpoint", değeri ise URI'dir.

dizesi.

Ö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"
    }
}

Sinyaller, cihaz üzerinde 10-15 KB'lık bir kotaya sahiptir. Kota aşıldığında PPAPI, FIFO stratejisi kullanarak sinyalleri çıkarır. Kiracı çıkarma işlemi, kiracı çıkarma sıklığını azaltmak için kotanın kısa aralıklarla biraz aşılmasına izin verir.

Signals Encoding API

Alıcıların, Korumalı Açık Artırma sırasında sunucuya gönderilmek üzere cihazda depolanan sinyalleri kodlamak için kullanılacak bir JavaScript işlevi sağlaması gerekir. Alıcılar, UpdateSignal API isteğinin yanıtlarından herhangi birinde "update_encoder" anahtarını kullanarak bu komut dosyasının alınabileceği URL'yi ekleyerek bu komut dosyasını sağlayabilir. Komut dosyasında aşağıdaki imza bulunur:

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 giden bir haritadır. Her Protected App Signals nesnesinin üç alanı vardır:

  • signal_value: Sinyal değerini temsil eden bir UInt8Array.
  • creation_time: Sinyallerin oluşturulma zamanını epoch saniye cinsinden temsil eden 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ı olan bir nesne döndürmelidir:

  • status: Komut dosyası başarıyla çalıştıysa 0 olmalıdır.
  • results: Uzunluğu maxSize'ten küçük veya ona eşit 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 teknolojisi uzmanlarına özellik mühendisliğinin ilk aşamasını sunar. Bu aşamada, ham sinyalleri kendi özel mantıklarına göre birleştirilmiş sürümlere sıkıştırma gibi dönüşümler gerçekleştirebilirler. Güvenilir Yürütme Ortamları'nda (TEE) çalışan bir Protected Auction sırasında reklam teknolojisi özel mantığının, kodlama tarafından oluşturulan sinyal yüklerine okuma erişimi olacağını unutmayın. Alıcı'nın B&A TEE'sinde çalışan Kullanıcı Tanımlı İşlev (UDF) olarak bilinen özel mantık, reklam seçimini (reklam getirme ve teklif verme) gerçekleştirmek için yayıncı uygulaması tarafından sağlanan kodlanmış sinyallere ve diğer içeriğe dayalı sinyallere okuma erişimine sahip olur.

Sinyal kodlaması

Kayıtlı sinyalleriyle kodlama mantığı sağlayan alıcıların sinyalleri her saat bir açık artırma yükü olarak kodlanır.Açık artırma yükü için bayt dizisi cihazda kalır, şifrelenir ve Protected Auction'a dahil edilecek reklam seçimi verileri kapsamında satıcılar tarafından toplanır. Test için aşağıdaki komutu çalıştırarak bu kodlamayı saatlik ritmi 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ın indirilmesi için istek gönderildiğinde reklam teknolojisi uç noktası, yanıt üstbilgilerinde bir sürüm numarası ile yanıt verebilir. Bu sürüm, cihazdaki kodlayıcı mantığıyla birlikte devam eder. Ham sinyaller kodlandığında, kodlanmış yük, kodlama için kullanılan sürümle birlikte devam ettirilir. Bu sürüm, reklam teknolojilerinin teklif verme ve kodlama mantıklarını sürüme göre uyumlu hale getirebilmesi için korumalı açık artırma sırasında B&A sunucusuna da gönderilir.

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 yapmak korunan kitleler için açık artırma yapmakla 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, teklifli sistemi ve açık artırma mantığını belirlemek için sahip oldukları B&A bileşenlerine dağıtabilecekleri bir dizi JS işlevi veya UDF'dir.
  • Reklam Alma API'si: Alıcılar, Protected App Signal açık artırması için bir dizi reklam adayı 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 verme mantıklarını uygulamak için kullanabileceği JS API veya UDF'lerden oluşur.

Alıcı reklam teknolojisi özel kullanıcı tanımlı işlevleri
prepareDataForAdRetrieval UDF'si

Korunan Uygulama Sinyalleri, TEE Reklam Alma hizmetinden reklam adaylarını almak için kullanılabilmesinden önce alıcıların Korunan Uygulama Sinyalleri'nin ve satıcı tarafından sağlanan diğer verilerin kodunu çözmesi ve hazırlaması gerekir. Alıcıların prepareDataForAdRetrieval UDF çıkışı, teklif verme için en iyi k aday reklamı almak amacıyla 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 adtech.
function prepareDataForAdRetrieval(encodedOnDeviceSignals,encodedOnDeviceSignalsVersion,sellerAuctionSignals,contextualSignals) {
   return {};
}
generateBid UDF

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 çıktısı, bir reklam adayı için tek bir tekliftir ve ProtectedAppSignalsAdWithBidMetadata ile eşdeğer bir JSON olarak temsil edilir. İşlev, daha sonra model eğitimini etkinleştirmek için reportWin işlevine iletilecek iki dizi de döndürebilir (Çıkış ve model eğitimi hakkında daha fazla bilgi için PAS açıklamalı kılavuzundaki 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'yi (Protected Audiences için kullanılan reportWin işleviyle aynıdır) kullanarak işaretçiler kaydeder. Reklam istemci tarafından oluşturulduktan sonra cihaz tarafından ping'lenir. Bu yöntemin imzası, model eğitimini etkinleştirmek için kullanılan ve generateBid'teki sonuçlarla doldurulan iki ek parametre egressPayload ve temporaryUnlimitedEgressPayload dışında Protected Audience sürümüyle neredeyse aynıdır.

// Inputs / Outputs
// ----------------
// See detailed documentation here.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
                   buyerReportingSignals,
                   egressPayload, temporaryUnlimitedEgressPayload) {
  // ...
}
Satıcı reklam teknolojisi özel kullanıcı tanımlı işlevleri
scoreAd UDF

Bu özel 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'si

Bu özel işlev, satıcının (nihayetinde) kazanan reklamla ilgili bilgileri kullanarak 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

İlk sürümde reklam alma hizmeti, alıcı tarafından yönetilen ve barındırılan bir hizmet olacak ve teklif verme hizmeti, reklam adaylarını bu hizmetten alacak. Nisan 2024'ten itibaren reklam alma sunucusu, Güvenilir Yürütme Ortamı'nda (TEE) çalışmalıdır ve GRPC/proto arayüzü sunmalıdır. Reklam teknolojisi şirketleri, B&A yığın dağıtımı kapsamında bu sunucuyu ayarlamalı ve URL'sini sağlamalıdır. TEE'de çalışan bu hizmetin bir uygulaması Privacy Sandbox GitHub'da mevcuttur ve dokümanların geri kalanında, dağıtımda kullanılan kodun bu olduğu varsayılmaktadır.

B&A sürümleri, Nisan 2024'ten itibaren bağlamsal yol reklamı getirmeyi destekler. Bu durumda teklif sunma sunucusu, açık artırmanın bağlamsal kısmı sırasında GZT sunucusu tarafından gönderilen reklam tanımlayıcılarının bir listesini alır. Tanımlayıcılar, teklif verme aşamasında kullanılacak reklamla ilgili tüm bilgileri (ör. en iyi k seçiminde kullanılacak reklam oluşturma URL'si, meta veriler ve reklam yerleştirmeleri) almak için bir TEE KV sunucusuna gönderilir. Bu ikinci yol için dağıtılması gereken belirli 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'si
function getCandidateAds(requestMetadata, preparedDataForAdRetrieval,
                      deviceMetadata, contextualSignals, contextualAdIds,) {
    return adsMetadataString;
}

Burada:

  • requestMetadata: JSON. UDF'ye istek başına sunucu meta verileri. Şu anda boş.
  • preparedDataForAdRetrieval: Bu alanın içeriği, reklam getirme stratejisine bağlıdır. Bağlamsal reklam alma durumunda bu parametre, cihazdan gelen ve teklif verme hizmetinden iletilen ham sinyalleri içerir. Reklam Alma Sunucusu kullanılarak TEE reklamı alınması durumunda bu parametre, prepareDataForAdRetrieval UDF'sinin sonucunu içerir. Not: Bu aşamada, Korunan Uygulama Sinyalleri'nin kodu çözülür ve şifresi kaldırılır.
  • deviceMetadata: Satıcının reklam hizmeti tarafından yönlendirilen cihaz meta verilerini içeren JSON nesnesi. Daha fazla bilgi için B&A belgelerini inceleyin.
    • X-Accept-Language: Cihazınızda 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ğlama dayalı teklif sunma sunucusundan gelen rastgele dize. UDF'nin dizenin kodunu çözebilmesi ve kullanabilmesi gerekir. Bağlamsal sinyaller, Korunan Uygulama Sinyalleri kullanılarak iletilen korumalı yerleşim için ML modeli sürümü bilgileri gibi tüm bilgileri içerebilir.
  • contextualAdIds: İsteğe bağlı bir reklam kimlikleri listesi içeren JSON nesnesi.

UDF, başarılı olduğunda bir dize döndürmelidir. Dize, teklif sunma sunucusuna döndürülür ve sunucu, dizeyi generateBid UDF'ye iletir. Dize basit bir dize olabilir ancak büyük olasılıkla şeması her reklam teknolojisi tarafından ayrı ayrı tanımlanan, serileştirilmiş bir nesne olmalıdır. Reklam teknolojisinin mantığı dize generateBid tanımlayıp kullanabildiği sürece şema üzerinde herhangi bir kısıtlama yoktur.

Sisteminizi geliştirme için ayarlama

Android

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

  1. Developer Preview 10 resmini ç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ırakmanın varsayılan yapılandırması düzenli olarak senkronize edileceğinden bu işlemi zaman zaman yeniden yapmanı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ı, açık artırma anahtarı sunucunuzu işaret edecek şekilde geçersiz kılın. Yanlış anahtarların önbelleğe alınmasını önlemek için açık artırma çalıştırmayı denemeden önce bu adımı ç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.

Satıcılar için herhangi bir değişiklik gerekmediğinden bu dokümanda, alıcıya özel sunucuların nasıl yapılandırılacağı ele alınacaktır.

Ön koşullar

Alıcı reklam teknolojisinin B&A hizmet grubunu dağıtmadan önce:

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

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ı

Reklam teknolojilerinin Protected App Signals'i kullanabilmesi için:

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

Ayrıca bu kılavuzda, yeniden pazarlama için B&A 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 kullanarak alıcıların aşağıdaki işaretleri ayarlaması gerekir:

  • Protected App Signals'ı etkinleştir: Protected App Signals verilerini toplamak için etkinleştirilir.
  • Protected App Signals URL'leri: Protected App Signals sunucularının URL'lerine ayarlanır.

Reklam teknolojisi uzmanları, yer tutuculardaki doğru URL'leri aşağıdaki alanlarla değiş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ı

Satıcılar, bu demo dosyasını örnek alarak aşağıdaki işaretleri ayarlamalıdır. (Not: Burada yalnızca Protected App Signals ile ilgili yapılandırma vurgulanmıştır.) Reklam teknolojilerinin, yer tutucularda doğru URL'leri değiştirdiğinden emin olması gerekir:

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 getirmeyi 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 getirme için kullanılan KV örneğine Ad Retrieval Server, içeriğe dayalı yol tabanlı getirmeyi destekleyen örneğe ise KV Lookup Server olarak atıfta bulunacağız.

Her iki durumda da sunucu dağıtımı, KV sunucusu GitHub'da bulunan dokümanları takip eder. İki durum arasındaki fark, arama işleminin herhangi bir ek yapılandırma olmadan kutudan çıktığı, geri alma işleminin ise geri 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 verme hizmetiyle aynı servis ağına dağıtılmasını beklediğini unutmayın.

Örnek Kurulum

Aşağıdaki senaryoyu düşünün: Bir reklam teknolojisi şirketi, Protected App Signals API'yi kullanarak kullanıcının uygulama kullanımına dayalı alakalı sinyalleri saklar. Örneğimizde, çeşitli uygulamalardan yapılan 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 Protected Auction'a iletilir. Alıcının B&A'da çalışan özel işlevleri, reklam adaylarını almak ve teklif hesaplamak için sinyalleri kullanır.

[Alıcı] Sinyal örnekleri

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

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

Anahtarı 1 ve 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 bayta 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, 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 adtech 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;
}

[Buyers] Örnek reklam getirme UDF'si

Örneğimizde reklam alma sunucusu, en iyi k reklam adayından her biri için meta verileri (ör. bu örnekte her reklamın kimliği, ancak her biri için 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\"}]"

[Buyers] 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};
}

[Buyers] reportWin örneği

reportWin UDF, açık artırmayı kazandığını alıcıya 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 ilgili puanlama sinyallerine bir eşleme olacak şekilde bir puanlama sinyali KV sunucusu oluşturmalıdır. Örneğin: Satın alma işlemini yapan kullanıcı tarafından https:/buyer-domain.com/get-fitness-app ve https:/buyer-domain.com/get-fastfood-app döndürülürse SFE tarafından https://key-value-server-endpoint.com?client_type=1&renderUrls=<render-url-returned-by-the-buyer> üzerinde GET kullanılarak sorgulandığında satıcı aşağıdaki örnek puanlama sinyali yanıtını alabilir:

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

[Satıcı] scoreAd example

/**
 * 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
  };
}

[Satıcı] 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, yukarıda açıklanan basit bir akışı kullanan bir uygulama oluşturmak için nasıl kullanılabileceğine dair bir örnek olarak bu örnek depoda bulunabilen Protected App Signals örnek uygulamasını oluşturduk.