Geliştiricilerin Korumalı Uygulama Sinyalleri API'si ile denemeler yapmaya başlamalarına yardımcı olmak için bu belgede API yüzeyindeki tüm API'ler açıklanmış, test ortamı oluşturma ayrıntıları, yapılandırma ve komut dosyaları örnekleri verilmiştir.
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
API'de, Android API'nin M-2024-05 sürümünü ve sunucu tarafı bileşenlerin Nisan 2024 sürümünü desteklemek için yapılan değişiklikler. En önemli değişiklikler:
- Cihaz üzerinde API için gereken izinler hakkında ayrıntılar eklendi
- Cihaz üzerinde sinyal kota yönetimi hakkında ayrıntılar eklendi
generateBidimzası, içeriğe dayalı reklam alma ve çıkış desteğiyle ilgili değişikliklerle güncellendi- Çıkış desteği dahil
reportWinbelgeleri güncellendi - BYOS reklam alma desteğini kaldırarak ve reklam alma UDF'sini belgeleyen Ad Retrieval API dokümanlarını güncelleyin
API'ye genel bakış
Protected Signals API yüzeyi, farklı sistemlerde farklı API alt kümeleri içerir:
- Android API'leri:
- Signal Curation API şunlardan oluşur:
- Signals API'yi güncelleme
- Sinyal Kodlama API'si
- Protected Açık Artırma Desteği API'si: SDK'lar tarafından, Korunan Uygulama Sinyallerini kullanarak Teklifli Sistem ve Açık Artırma (B&A) Sunucularında korumalı açık artırmayı yürütmek için kullanılır.
- Sunucu tarafı API'ler:
- Protected Açık Artırma API'si: Teklifli Sistem ve Açık Artırma Sunucularında çalışan bir dizi JS komut dosyasıdır. Bu API, Satıcıların ve Alıcıların korunan açık artırmayı uygulama mantığını yazmasına olanak tanır.
- Ad Retrieval API: Alıcının teklif sunucusuna sunduğu bağlam ve kullanıcı bilgileriyle aday reklamların bir listesini sağlamaktan sorumludur.
Android istemcisi
İstemci tarafında, Korunan Uygulama Sinyalleri yüzeyi üç farklı API'den oluşur:
- Güncelleme Sinyalleri: Cihazda sinyallerin seçilmesini sağlayan bir Android System API.
- Sinyal Kodlaması: Açık artırma sırasında sunucuya gönderilecek sinyalleri hazırlayan bir JavaScript API'si.
- Korumalı Açık Artırma Desteği: Teklifli Sistem ve Açık Artırma Sunucularında Korumalı Açık Artırmanın yürütülmesini destekleyen bir API. Bu API, Korunan Uygulama Sinyalleri'ne özel değildir ve Protected Audience API açık artırmalarını desteklemek için de kullanılır.
Signals API'yi güncelleme
Update Signals API, reklam teknolojilerine kullanıcı ve uygulamayla ilgili sinyalleri alıcı adına kaydetme olanağı sunar. API, yetki modeli üzerinde çalışır. Çağrıyı yapan, çerçevenin ilgili sinyalleri getirdiği bir URI ve bu sinyallerin açık artırmada kullanılması için kodlama mantığını sağlar.
API android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS iznini gerektirir.
updateSignals() API, URI'dan 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 getirmek için istekte sağlanan URI'ye bir https isteği gönderir. Yanıt, sinyal güncellemeleriyle birlikte 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:
anahtar |
Açıklama |
|
Aynı anahtara sahip mevcut sinyallerin üzerine yazarak yeni bir sinyal ekler. Değer bunun bir JSON nesnesidir. Anahtarlar, yerleştirilecek anahtara karşılık gelen 64'lük taban dizelerden, değerlerin ise yerleştirilecek değere karşılık gelen 64 tabanlı dizelerden oluşur. |
|
Bir zaman serisine yeni sinyal/sinyal ekleyerek en eski sinyali kaldırır sinyallerine geçiş yapacaktır. Bunun değeri, anahtarların eklenecek anahtara karşılık gelen 64 tabanlı temel dizeler olduğu bir JSON nesnesidir. Değerler ise iki alanlı nesnelerdir: "values" ve "maxSignals". "values": Zaman serisine eklenecek sinyal değerlerine karşılık gelen 64 tabanlı dizelerin listesi. "maxSignals": Bu zaman serisinde izin verilen maksimum değer sayısı. Eğer Anahtarla ilişkili mevcut sinyal sayısı, en eski sinyallerin kaldırılacağı maxSignals değerini aşıyor. Yer işareti koyarak eklenen bir anahtara ekleme yapabileceğinizi unutmayın. Maksimum değer sayısından daha fazla değer eklemenin hataya neden olacağını unutmayın. |
|
Yalnızca aynı anahtara sahip mevcut bir sinyal yoksa yeni sinyal ekler. Bunun değeri, anahtarların yerleştirilecek anahtara karşılık gelen 64'lük taban dizeler ve değerlerin, yerleştirilecek değere karşılık gelen 64 tabanlı dizeler olduğu bir JSON nesnesidir. |
|
Tuşun sinyalini kaldırır. Bunun değeri, silinmesi gereken sinyal anahtarlarına karşılık gelen 64 tabanlı dizelerin bir listesidir. |
|
Uç noktayı güncellemek için bir işlem ve kullanılabilecek bir URI sağlar yöntemini çağırın. Güncelleme işlemi sağlamanın alt anahtarı "action", değerleri, şu anda ilk kez sağlanmışsa kodlayıcı uç noktasını kaydedecek veya yeni sağlanan uç noktayı mevcut değerin üzerine yazacak olan yalnızca "REGISTER"dır. "REGISTER" işlemi için uç nokta sağlanması gerekir.Kodlayıcı uç noktası sağlamanın alt anahtarı "uç nokta", değer ise URI'dir dizesine bakın. |
Örnek bir JSON isteği şöyle 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 içi kotası 10-15 Kb arasındadır. Kota aşıldığında PPAPI, bir FIFO stratejisi kullanarak sinyalleri kaldırır. Çıkarma işlemi, çıkarma sıklığını azaltmak için kotanın kısa zaman aralıklarında biraz aşılmasına imkan tanır.
Sinyal Kodlama API'si
Alıcıların, cihazda depolanan sinyalleri kodlamak amacıyla, Korumalı Açık Artırma sırasında sunucuya gönderilecek bir Java Script işlevi sağlaması gerekir. Alıcılar, bu komut dosyasını bir UpdateSignal API isteğine verilen yanıtlarda "update_encoder" anahtarı kullanılarak getirilebilecek URL'yi ekleyerek sağlayabilir. Komut dosyası aşağıdaki imzaya sahip olur:
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 boyutlu UInt8Arrays biçimindeki anahtarlar ile Korunan Uygulama Sinyalleri nesnelerinin listelerine yapılan bir eşlemedir. Her Korunan Uygulama Sinyalleri nesnesinin üç alanı vardır:
signal_value: Sinyalin değerini temsil eden bir UInt8Array.creation_time: Sinyallerin oluşturulma zamanını sıfır saniye cinsinden temsil eden 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 tanımlayan bir sayıdır.
İşlev, iki alanlı bir nesne çıktısı verir:
status: Komut dosyası başarıyla çalıştırıldıysa 0 olmalıdır.results: maxSize küçüktür veya eşit uzunlukta bir UInt8Array olmalıdır. Bu dizi, açık artırmalar sırasında sunucuya gönderilir veprepareDataForAdRetrievalkomut dosyası tarafından hazırlanır.
Kodlama, reklam teknolojisine özellik mühendisliğinin ilk aşamasını sağlar. Bu aşamada, ham sinyalleri kendi özel mantığına göre birleştirilmiş sürümler halinde sıkıştırmak gibi dönüştürme işlemleri gerçekleştirilebilir. Güvenilir Yürütme Ortamlarında (TEE) yayınlanan bir Korumalı Açık Artırma 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çimi (reklam alma ve teklif verme) yapmak için yayıncı uygulaması tarafından sağlanan kodlanmış sinyallere ve diğer içerik sinyallerine okuma erişimine sahip olur.
Sinyal kodlaması
Kayıtlı sinyalleriyle kodlama mantığı sağlayan alıcıların sinyalleri, açık artırma yüküne her saat başı kodlanır.Açık artırma yükü için bayt dizisi cihazda kalır, şifrelenir ve Korumalı Açık Artırmanın parçası olarak dahil edilmek üzere 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 temponun dışında tetikleyebilirsiniz:
adb shell cmd jobscheduler run -f com.google.android.adservices.api 29
Kodlayıcı mantık sürümü oluşturma
Reklam teknolojisi özel kodlayıcı mantığının indirilmesi için istekte bulunulduğunda, reklam teknolojisi uç noktası yanıt başlıklarında bir sürüm numarasıyla yanıt verebilir. Bu sürüm, cihazdaki kodlayıcı mantığıyla birlikte korunur. Ham sinyaller kodlandığında, kodlanmış yük, kodlama için kullanılan sürümle birlikte korunur. Bu sürüm, Korumalı Açık Artırma sırasında B&A sunucusuna da gönderilir. Böylece reklam teknisyenleri, sürüme göre teklif verme ve kodlama mantığını uyumlu hale getirebilir.
Response header for providing encoder version : X_ENCODER_VERSION
Protected Açık Artırma Desteği API'si
Cihaz tarafında, Korunan Uygulama Sinyalleri için açık artırma yürütmek, koruma altındaki kitleler için açık artırma yürütmekle aynıdır.
Teklif Verme ve Açık Artırma Hizmetleri
Sunucu Tarafı API'leri şunlardır:
- Protected Açık Artırma API'si: Alıcı ve satıcıların, teklif vermeyi 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'ler.
- Reklam Alma API'si: Alıcılar, Korunan Uygulama Sinyali açık artırması için bir dizi aday reklam sağlamaktan sorumlu olacak bir REST Uç Noktası uygulayarak bu API'yi uygulayabilir.
Korumalı Açık Artırma API'si
Protected Açık Artırma API'si, alıcı 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 UDF'leri
AdRetrieval içinHazır Veri UDF'si
Korumalı Uygulama Sinyallerinin TEE Reklam Alma hizmetinden reklam adaylarını getirmek için kullanılabilmesi için alıcıların Korumalı Uygulama Sinyallerinin ve satıcı tarafından sağlanan diğer verilerin kodunu çözüp hazırlaması gerekir. Alıcılar prepareDataForAdRetrieval UDF çıkışı, teklifli sistem 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 {};
}
Teklif UDF oluştur
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 sonucu, bir reklam adayı için tek teklif olup ProtectedAppSignalsAdWithBidMetadata ile eşdeğer JSON olarak gösterilir.
İşlev, model eğitimini etkinleştirmek için reportWin öğesine geçirilecek olan 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'si
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 (Bu, Korunan Kitleler için kullanılan reportWin işleviyle aynıdır) kullanarak işaretçileri kaydeder.
Reklam istemci tarafından oluşturulduktan sonra bu mesaj, cihaz tarafından pinglenir.
Bu yöntemin imzası, model eğitimini etkinleştirmek için kullanılan ve generateBid kaynağından sonuçlarla doldurulan iki ek parametre egressPayload ve temporaryUnlimitedEgressPayload dışında, Protected Audience sürümüyle hemen hemen aynıdır.
// Inputs / Outputs
// ----------------
// See detailed documentation here.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
buyerReportingSignals,
egressPayload, temporaryUnlimitedEgressPayload) {
// ...
}
Satıcı reklam teknolojisi UDF'leri
Skor Reklam UDF
Bu UDF satıcılar tarafından, alıcılardan alınan reklamlardan hangilerinin 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};
}
raporSonuç UDF
Bu UDF, satıcının (nihayetinde) kazanan reklamla ilgili bilgileri içeren etkinlik düzeyinde raporlama yapmasına olanak tanır.
function reportResult(auctionConfig, reporting_metadata) {
// ...
registerAdBeacon({"click", clickUrl,"view", viewUrl});
sendReportTo(reportResultUrl);
return signalsForWinner;
}
Reklam Retrieval API'si
MVP sürümünde , reklam alma hizmeti alıcı tarafından yönetilen ve barındırılan bir hizmet olacak ve teklif hizmeti, reklam adaylarını bu hizmetten alacaktır. Nisan 2024'ten itibaren reklam alma sunucusu, Güvenilir Yürütme Ortamında (TEE) çalışmalı ve bir GRPC/proto arayüzü gösterecek. Reklam teknolojisi şirketleri, bu sunucuyu ayarlamalı ve sunucu URL'sini, B&A yığın dağıtımının bir parçası olarak sağlamalıdır. Bu hizmetin TEE'de çalışan uygulaması Özel Korumalı Alan GitHub'da ve diğer belgelerde dağıtımda kullanılan kodun bu olduğunu varsayıyoruz.
Nisan 2024'ten itibaren siyah beyaz sürümleri içeriğe dayalı yol reklam alma özelliğini desteklemektedir. Bu durumda Teklifli Sistem sunucusu, açık artırmanın bağlamsal bölümünde GZT sunucusu tarafından gönderilen reklam tanımlayıcılarının listesini alır. Tanımlayıcılar, teklif verme aşamasında kullanılacak reklamla ilgili tüm bilgileri (ör. ilk k seçiminde kullanılacak reklam oluşturma URL'si, meta veriler ve reklam yerleştirmeleri) getirmek için bir TEE KV sunucusuna gönderilir. Bu ikinci yolun dağıtılması için belirli bir mantık gerektirmez. Bu yüzden, burada yalnızca TEE tabanlı reklam alma kullanım alanının nasıl yapılandırılacağını belgeleyeceğiz.
UDF İsteği işleme
function HandleRequest(requestMetadata, preparedDataForAdRetrieval,
deviceMetadata, contextualSignals) {
return adsMetadataString;
}
Burada:
requestMetadata: JSON. UDF'de istek başına sunucu meta verileri. Şimdilik boş.preparedDataForAdRetrieval: Bu alanın içeriği, reklam alma stratejisine bağlıdır. İçeriğe dayalı reklam alımı durumunda , bu parametre cihazdan gelen ve teklifli sistemden geçirilen ham sinyalleri içerir. Reklam Alma Sunucusu kullanılarak TEE reklamlarının alınması durumunda bu parametreprepareDataForAdRetrievalUDF'nin sonucunu içerir. Not: Bu aşamada, Korumalı Uygulama Sinyallerinin kodu çözülür ve şifrelenmez.deviceMetadata: Satıcının Reklam Hizmeti tarafından yönlendirilen cihaz meta verilerini içeren JSON nesnesi. Daha fazla ayrıntı 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 içeriğe dayalı teklif verme sunucusundan kaynaklanan rastgele dize. UDF'nin dizenin kodunu çözebilmesi ve kullanabilmesi beklenir. Bağlamsal Sinyaller, Korunan Uygulama Sinyalleri kullanılarak iletilen korumalı yerleştirme için makine öğrenimi modeli sürüm bilgileri gibi bilgileri içerebilir.
UDF'nin başarılı sonuç veren bir dize döndürmesi gerekir. Dize teklif sunucusuna döndürülür ve ardından generateBid UDF'ye iletir. Dize basit bir dize olabilir. Bununla birlikte, dizenin büyük olasılıkla şeması her reklam teknolojisi tarafından kendi başına tanımlandığı serileştirilmiş bir nesne olmalıdır.
Reklam teknolojisinin generateBid mantığı dizeyi tanıyıp kullanabildiği sürece şemada herhangi bir kısıtlama yoktur.
Sisteminizi geliştirme için ayarlayın
Android
Android geliştirme ortamınızı kurmak için aşağıdakileri yapmanız gerekir:
- Geliştirici Önizleme 10 görüntüsünü çalıştıran bir emülatör (tercih edilen) veya fiziksel cihaz oluşturun
- 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, uygulamalar tarafından önerilen reklamlara izin vermek için gösterilen seçeneği belirleyin.
- İlgili API'leri etkinleştirmek için aşağıdaki komutu çalıştırın. Devre dışı bırakma ayarının varsayılan yapılandırması düzenli aralıklarla senkronize edileceğinden bunu ara sıra 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;
- Cihazı yeniden başlatın.
- Cihazın açık artırma anahtarlarını, açık artırma anahtarı sunucunuza işaret edecek şekilde geçersiz kılın. Yanlış anahtarların önbelleğe alınmasını önlemek için, bir açık artırma çalıştırmayı denemeden önce bu adımın uygulanması önemlidir.
Teklif Verme ve Açık Artırma Hizmetleri
B&A sunucularını ayarlamak için self servis kurulum belgelerine bakın.
Satıcılar için herhangi bir değişiklik olmadığından bu belgede alıcıya özel sunucuların nasıl yapılandırılacağı ele alınmaktadır.
Ön koşullar
B&A hizmet yığınını dağıtmadan önce alıcı reklam teknolojisinin şunları yapması gerekir:
- Kendi TEE Reklam Alma Hizmeti'ni dağıttıklarından emin olun (ilgili bölüme bakın).
- Reklam teknolojisinde gerekli tüm UDF'lerin (
prepareDataForAdRetrieval,generateBid,reportWin,HandleRequest) tanımlandığından ve barındırıldığından emin olun.
Korunan Kitle ile Korumalı Açık Artırma'nı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 teknolojileri:
- B&A'da Korunan Uygulama Sinyalleri desteğini etkinleştirin.
prepareDataForAdRetrieval, generateBidvereportWiniçin yeni UDF'lerin getirilebileceği URL uç noktalarını sağlayın.
Buna ek olarak, bu kılavuzda, yeniden pazarlama için B&A kullanmak isteyen reklam teknisyenlerinin her zamanki gibi yeniden pazarlama açık artırması için tüm mevcut yapılandırma işaretlerini ayarlamaya devam edeceği varsayılır.
Alıcı reklamı teknoloji yapılandırması
Örnek olarak bu demo dosyasını kullanarak alıcıların aşağıdaki işaretleri ayarlaması gerekir:
- Korunan Uygulama Sinyallerini Etkinleştir: Korunan Uygulama Sinyalleri verilerini toplamak için etkinleştirilir.
- Korunan Uygulama Sinyalleri URL'leri: Korunan Uygulama Sinyalleri sunucularının URL'lerini ayarlayın.
Reklam teknolojileri, aşağıdaki alanlar için yer tutucularda doğru URL'leri 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ı teknoloji yapılandırması
Satıcılar, bu demo dosyasını örnek olarak kullanarak aşağıdaki işaretleri ayarlamalıdır. (Not: Burada yalnızca Korumalı Uygulama Sinyalleri ile ilgili yapılandırma vurgulanmıştır). Reklam teknisyenleri, yer tutucularda doğru URL'leri değiştirdiklerinden emin olmalı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, sistemde KV hizmetinin bir veya iki örneğinin dağıtılması gerekir. TEE tabanlı reklam alımı için kullanılan KV örneği örneğini Ad Retrieval Server, bağlamsal yola dayalı almayı desteklemek için ise KV Lookup Server örneğini kullanacağız.
Her iki durumda da sunucu dağıtımı, KV sunucusu GitHub'da bulunan belgeleri takip eder. İki durum arasındaki fark, arama alanının ek yapılandırma gerekmeden kullanıma hazır olarak işlemesi ve alma işleminde, alma mantığını uygulamak için HandleRequest 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 teklifli sistemle aynı hizmet ağında dağıtılmasını beklediğini unutmayın.
Örnek Kurulum
Şu senaryoyu düşünün: Bir reklam teknolojisi, Protected App Signals API'yi kullanarak kullanıcının uygulama kullanımına dayalı ilgili sinyalleri depolar. Ö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 bir Korumalı Açık Artırmaya geçirilir. Alıcının B&A'da yayınlanan UDF'leri, reklam adaylarını getirmek ve teklif hesaplamak için sinyalleri kullanır.
[Alıcı] Sinyal örnekleri
Anahtarı 0 ve 1 değerine sahip bir sinyal ekler.
{
"put": {
"AA==": "AQ=="
},
"update_encoder": {
"action": "REGISTER",
"endpoint": "https://example.com/example_script"
}
}
Anahtarı 1 ve 2 değerine sahip bir sinyal ekler.
{
"put": {
"AQ==": "Ag=="
},
"update_encoder": {
"action": "REGISTER",
"endpoint": "https://example.com/example_script"
}
}
[Buyer] encodeSignals örneği
Her bir sinyali iki bayt halinde kodlar. İlk bayt, sinyal anahtarının ilk baytı, ikinci bayt ise sinyal değerinin ilk baytı olur.
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;
}
[Alıcılar] Örnek reklam alma UDF'si
Örneğimizde reklam alma sunucusu, ilk k reklam adayının her biri için meta veriler (bu örnekte her bir reklamın kimliği) gönderir ancak her biri için daha sonra tekliflerin oluşturulmasında yardımcı olabilecek diğer verileri içerebilir.
function HandleRequest(requestMetadata, protectedSignals, deviceMetadata,
contextualSignals) {
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] reportWin ö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şlemenin bulunabilmesi 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 kullanarak SFE tarafından sorgulandığında aşağıdaki örnek puanlama sinyalleri 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 ö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
};
}
[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
Yukarıda açıklanan basit akışı kullanan bir uygulama oluşturmak için API'nin nasıl kullanılabileceğini gösteren bir örnek olarak, bu örnek depoda bulabileceğiniz Korunan Uygulama Sinyalleri örnek uygulaması oluşturduk.