Panduan developer Sinyal Aplikasi Dilindungi

Untuk membantu developer mulai bereksperimen dengan Protected App Signals API, dokumen ini menjelaskan semua API dalam platform API, menjelaskan cara menyiapkan lingkungan pengujian, serta memberikan contoh konfigurasi dan skrip.

Catatan: Protected App Signals memerlukan server Bidding dan Lelang fungsional agar dapat berjalan. Pastikan Anda mengikuti langkah-langkah untuk men-deploy Bidding dan Lelang ke AWS atau Google Cloud.

Histori versi

Jan 2024

Rilis pertama panduan developer yang mendukung rilis MVP PAS

Maret 2024

Perubahan pada API untuk mendukung rilis M-2024-05 Android API dan rilis komponen sisi server April 2024. Perubahan yang paling penting:

• Menambahkan detail tentang izin yang diperlukan untuk API di perangkat
• Menambahkan detail tentang pengelolaan kuota sinyal di perangkat
• Memperbarui tanda tangan generateBid dengan perubahan yang terkait dengan dukungan pengambilan iklan kontekstual dan keluar
• Memperbarui dokumentasi reportWin termasuk dukungan keluar
• Memperbarui dokumentasi Ad Retrieval API yang menghapus dukungan untuk pengambilan iklan BYOS dan mendokumentasikan UDF pengambilan iklan

Ringkasan API

Platform Protected Signals API mencakup berbagai subset API pada sistem yang berbeda:

• API Android:
  • Signal Curation API, yang terdiri dari:
  • Update Signals API
  • Signals Encoding API
  • Protected Auction Support API: Digunakan oleh SDK untuk menjalankan lelang terlindungi di Server Bidding dan Lelang (B&A) menggunakan Protected App Signals.
• API sisi server:
  • Protected Auction API: Rangkaian skrip JS yang berjalan di Server Bidding dan Lelang. API ini memungkinkan Penjual dan Pembeli menulis logika untuk menerapkan lelang terlindungi.
  • Ad Retrieval API: Bertanggung jawab menyediakan daftar iklan kandidat dengan informasi pengguna dan kontekstual yang disediakan untuk server bidding pembeli.

Klien Android

Di sisi klien, platform Protected App Signals terdiri dari tiga API berbeda:

• Update Signals: API Sistem Android untuk mengaktifkan seleksi sinyal di perangkat.
• Signals Encoding: API JavaScript untuk menyiapkan sinyal yang akan dikirim ke server selama lelang.
• Protected Auction Support: API untuk mendukung pelaksanaan Protected Auction di Server Bidding dan Lelang. API ini tidak khusus untuk Protected App Signals, tetapi juga digunakan untuk mendukung lelang bagi Protected Audience API.

Catatan: Saat menguji dengan Protected App Signals di Pratinjau Developer, sebaiknya Anda menggunakan emulator karena dalam beberapa situasi, cara terbaik untuk menyelesaikan masalah dalam penyiapan adalah dengan menghapus total perangkat.

Update Signals API

Update Signals API memberi teknologi iklan kemampuan untuk mendaftarkan sinyal terkait pengguna dan aplikasi atas nama pembeli. API ini berfungsi di model delegasi. Pemanggil menyediakan URI tempat framework mengambil logika dan sinyal yang sesuai untuk mengenkode sinyal tersebut agar dapat digunakan dalam lelang.

API memerlukan izin android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS.

updateSignals() API akan mengambil objek JSON dari URI yang menjelaskan sinyal yang akan ditambahkan atau dihapus, dan cara menyiapkan sinyal tersebut untuk lelang.

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 membuat permintaan https ke URI yang disediakan dalam permintaan untuk mengambil update sinyal. Bersamaan dengan update sinyal, respons dapat mencakup endpoint yang menghosting logika encoding untuk mengubah sinyal mentah menjadi payload yang dienkode. Update sinyal diharapkan dalam bentuk JSON dan dapat memiliki kunci berikut:

Kunci tingkat teratas untuk objek JSON harus sesuai dengan salah satu dari lima perintah:

kunci	Deskripsi
put	Menambahkan sinyal baru agar dapat menimpa sinyal yang ada dengan kunci yang sama. Nilai untuk ini adalah objek JSON dengan kunci berupa string basis 64 yang sesuai dengan kunci yang akan dimasukkan, dan nilainya adalah string basis 64 yang sesuai dengan nilai yang akan dimasukkan.
append	Menambahkan satu/beberapa sinyal baru ke deret waktu sinyal agar dapat menghapus sinyal terlama untuk memberi ruang bagi yang baru jika ukuran deret melebihi batas maksimum yang ditentukan. Nilai untuk ini adalah objek JSON dengan kunci berupa string basis 64 yang sesuai dengan kunci yang akan ditambahkan, dan nilainya adalah objek dengan dua kolom: "values" dan "maxSignals". "values": Daftar string basis 64 yang sesuai dengan nilai sinyal yang akan ditambahkan ke deret waktu. "maxSignals": Jumlah nilai maksimum yang diizinkan dalam deret waktu ini. Jika jumlah sinyal saat ini yang terkait dengan kunci melebihi maxSignals, sinyal terlama akan dihapus. Perhatikan bahwa Anda dapat menambahkan ke kunci yang ditambahkan oleh put. Perhatikan bahwa menambahkan lebih dari jumlah nilai maksimum akan menyebabkan kegagalan.
put_if_not_present	Menambahkan sinyal baru, hanya jika tidak ada sinyal dengan kunci yang sama. Nilai untuk ini adalah objek JSON dengan kunci berupa string basis 64 yang sesuai dengan kunci yang akan dimasukkan, dan nilainya adalah string basis 64 yang sesuai dengan nilai yang akan dimasukkan.
remove	Menghapus sinyal untuk kunci. Nilainya adalah daftar string basis 64 yang sesuai dengan kunci sinyal yang harus dihapus.
update_encoder	Menyediakan tindakan untuk mengupdate endpoint, dan URI yang dapat digunakan untuk mengambil logika encoding. Sub-kunci untuk memberikan tindakan update adalah "tindakan", dan nilai yang saat ini didukung hanya "REGISTER" yang akan mendaftarkan endpoint encoder jika diberikan untuk pertama kalinya atau menimpa yang sudah ada dengan endpoint yang baru diberikan. Penyediaan endpoint diperlukan untuk tindakan "REGISTER". Sub-kunci untuk memberikan endpoint encoder adalah "endpoint", dan nilainya adalah string URI untuk endpoint.

Contoh permintaan JSON akan terlihat seperti berikut:

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

Sinyal akan memiliki kuota di perangkat dalam urutan 10-15Kb. Setelah kuota dilampaui, PPAPI akan mengeluarkan sinyal menggunakan strategi FIFO. Proses penghapusan akan memungkinkan kuota sedikit terlampaui selama interval waktu yang singkat untuk mengurangi frekuensi penghapusan.

Signals Encoding API

Pembeli diwajibkan untuk menyediakan fungsi Java Script yang akan digunakan untuk mengenkode sinyal yang disimpan di perangkat agar dikirim ke server selama proses Protected Auction. Pembeli dapat memberikan skrip ini dengan menambahkan URL yang dapat diambil menggunakan kunci "update_encoder" dalam respons apa pun terhadap permintaan UpdateSignal API. Skrip akan memiliki tanda tangan berikut:

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)};
}

Parameter signals adalah peta dari kunci dalam bentuk UInt8Arrays berukuran 4 ke daftar objek Protected App Signals. Setiap objek Protected App Signals memiliki tiga kolom:

• signal_value: UInt8Array yang mewakili nilai sinyal.
• creation_time: Angka yang mewakili waktu pembuatan sinyal dalam epoch-detik.
• package_name: String yang mewakili nama paket yang membuat sinyal.

Parameter maxSize adalah angka yang menjelaskan ukuran array terbesar yang diizinkan untuk output.

Fungsi ini akan menghasilkan objek dengan dua kolom:

• status: Harus 0 jika skrip berhasil dijalankan.
• results: Harus berupa UInt8Array yang panjangnya kurang dari atau sama dengan maxSize. Array ini akan dikirim ke server selama lelang, dan disiapkan oleh skrip prepareDataForAdRetrieval.

Encoding memberi teknologi iklan tahap awal rekayasa fitur, tempat teknologi iklan itu dapat menjalankan transformasi seperti mengompresi sinyal mentah menjadi versi gabungan berdasarkan logika kustomnya sendiri. Perhatikan bahwa selama Protected Auction berjalan di Trusted Execution Environment (TEE), logika kustom teknologi iklan akan memiliki akses baca ke payload sinyal yang dihasilkan oleh encoding. Logika kustom, yang dikenal sebagai Fungsi yang Ditentukan Pengguna (UDF) dan berjalan di TEE B&A Pembeli, akan memiliki akses baca ke sinyal yang dienkode dan sinyal kontekstual lainnya yang disediakan oleh aplikasi penayang untuk melakukan pemilihan iklan (pengambilan dan bidding iklan).

Encoding sinyal

Setiap jam, sinyal pembeli yang telah menyediakan logika encoding dengan sinyal terdaftar akan dienkode menjadi payload lelang. Array byte untuk payload lelang dipertahankan di perangkat, serta dienkripsi dan akan dikumpulkan oleh penjual sebagai bagian dari data Pemilihan Iklan untuk disertakan sebagai bagian dari Protected Auction. Untuk pengujian, Anda dapat memicu encoding ini di luar ritme per jamnya dengan menjalankan perintah berikut:

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

Pembuatan versi logika encoder

Saat permintaan dibuat untuk mendownload logika encoder kustom teknologi iklan, endpoint teknologi iklan dapat merespons dengan nomor versi di header respons. Versi ini dipertahankan bersama logika encoder di perangkat. Saat sinyal mentah dienkode, payload yang dienkode akan dipertahankan bersama versi yang digunakan untuk encoding. Versi ini juga akan dikirim ke server B&A selama Protected Auction sehingga teknologi iklan dapat menyelaraskan logika bidding dan encoding berdasarkan versi.

Response header for providing encoder version : X_ENCODER_VERSION

Protected Auction Support API

Di sisi perangkat, menjalankan lelang untuk Protected App Signals adalah sama seperti menjalankan lelang untuk audiens terlindungi.

Layanan Bidding dan Lelang

API Sisi Server meliputi:

• Protected Auction API: Rangkaian fungsi JS atau UDF yang dapat di-deploy oleh pembeli dan penjual pada komponen B&A yang mereka miliki untuk menentukan logika lelang dan bidding.
• Ad Retrieval API: Pembeli dapat menerapkan API ini dengan menerapkan REST Endpoint yang akan bertanggung jawab untuk menyediakan kumpulan iklan kandidat untuk lelang Protected App Signal.

Protected Auction API

Protected Auction API terdiri dari API JS atau UDF yang dapat digunakan oleh pembeli dan penjual untuk menerapkan logika lelang dan bidding mereka.

UDF teknologi iklan pembeli

prepareDataForAdRetrieval UDF

Sebelum Protected App Signals dapat digunakan untuk mengambil kandidat iklan dari layanan Pengambilan Iklan TEE, pembeli harus mendekode dan menyiapkan Protected App Signals serta data lainnya yang disediakan penjual. Output prepareDataForAdRetrieval UDF pembeli diteruskan ke layanan pengambilan iklan untuk mengambil iklan kandidat top-k untuk bidding.

// 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

Setelah iklan kandidat top-k ditampilkan, kandidat iklan akan diteruskan ke logika bidding kustom pembeli, generateBid UDF:

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

Output fungsi ini adalah satu bid untuk kandidat iklan, yang direpresentasikan sebagai JSON yang setara dengan ProtectedAppSignalsAdWithBidMetadata. Fungsi ini juga dapat menampilkan dua array yang kemudian akan diteruskan ke reportWin untuk mengaktifkan pelatihan model (untuk mengetahui detail selengkapnya tentang egress dan pelatihan model, lihat bagian pelaporan dalam penjelasan PAS)

reportWin UDF

Saat lelang berakhir, layanan lelang akan membuat URL pelaporan untuk pembeli dan mendaftarkan beacon menggunakan reportWin UDF (Ini adalah fungsi reportWin yang sama, yang digunakan untuk Protected Audience). Fungsi ini akan di-ping oleh perangkat setelah Iklan dirender oleh klien. Tanda tangan metode ini hampir sama dengan versi Protected Audience, kecuali untuk dua parameter tambahan egressPayload dan temporaryUnlimitedEgressPayload yang digunakan untuk mengaktifkan pelatihan model dan diisi dengan hasil dari generateBid.

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

UDF teknologi iklan penjual

scoreAd UDF

UDF ini digunakan oleh penjual untuk memilih iklan mana yang diterima dari pembeli yang akan memenangkan lelang.

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

reportResult UDF

UDF ini memungkinkan penjual (pada akhirnya) melakukan pelaporan tingkat peristiwa dengan informasi terkait iklan pemenang.

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

Ad Retrieval API

Dalam rilis MVP, layanan pengambilan iklan akan menjadi layanan yang dikelola dan dihosting pembeli, dan layanan bidding mengambil kandidat iklan dari layanan ini. Mulai April 2024, server pengambilan iklan harus berjalan di Trusted Execution Environment (TEE) dan akan menampilkan antarmuka GRPC/proto. Perusahaan teknologi iklan harus menyiapkan server ini dan memberikan URL-nya sebagai bagian dari deployment stack B&A. Implementasi layanan ini yang berjalan di TEE tersedia di GitHub Privacy Sandbox dan di seluruh dokumentasi, kami mengasumsikan bahwa ini adalah kode yang digunakan dalam deployment.

Mulai April 2024, versi B&A mendukung pengambilan iklan jalur kontekstual. Dalam hal ini, server Bidding akan menerima daftar ID iklan yang dikirim oleh server RTB selama bagian kontekstual lelang. ID akan dikirim ke server KV TEE untuk mengambil semua informasi terkait iklan yang akan digunakan selama fase bidding (misalnya ad-render-url, metadata, dan penyematan iklan yang akan digunakan dalam pemilihan top-k). Jalur kedua ini tidak memerlukan logika spesifik untuk di-deploy sehingga kita hanya akan mendokumentasikan di sini cara mengonfigurasi kasus penggunaan pengambilan iklan berbasis TEE.

UDF getCandidateAds

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

Dengan keterangan:

• requestMetadata: JSON. Metadata server per permintaan ke UDF. Kosong untuk saat ini.
• preparedDataForAdRetrieval: konten kolom ini bergantung pada strategi pengambilan iklan. Dalam kasus pengambilan iklan kontekstual , parameter ini akan berisi sinyal mentah yang berasal dari perangkat, dan diteruskan dari layanan bidding. Jika pengambilan iklan TEE menggunakan Server Pengambilan Iklan, parameter ini akan berisi hasil UDF prepareDataForAdRetrieval. Catatan: pada tahap ini, Protected App Signals akan didekode dan didekripsi.
• deviceMetadata: Objek JSON yang berisi metadata perangkat yang diteruskan oleh Layanan Iklan Penjual. Lihat dokumentasi B&A untuk mengetahui detail selengkapnya.
  • X-Accept-Language: bahasa yang digunakan di perangkat.
  • X-User-Agent: Agen Pengguna yang digunakan di perangkat.
  • X-BnA-Client-IP: Alamat IP perangkat.
• contextualSignals: string arbitrer yang berasal dari server bidding kontekstual yang dioperasikan oleh DSP yang sama. UDF diharapkan dapat mendekode string dan menggunakannya. Sinyal Kontekstual dapat berisi informasi apa pun seperti informasi versi model ML untuk penyematan yang dilindungi yang diteruskan menggunakan Protected App Signals.
• contextualAdIds: Objek JSON yang berisi daftar ID iklan opsional.

UDF akan menampilkan string jika berhasil. String ditampilkan ke server bidding yang kemudian meneruskannya ke generateBid UDF. Meskipun string dapat berupa string sederhana, kemungkinan besar string tersebut harus berupa objek serialisasi yang skemanya ditentukan oleh setiap teknologi iklan. Tidak ada batasan pada skema selama logika generateBid teknologi iklan dapat mengenali dan menggunakan string.

Menyiapkan sistem untuk pengembangan

Android

Untuk menyiapkan lingkungan pengembangan Android, Anda perlu melakukan hal berikut:

1. Membuat emulator (lebih disukai) atau perangkat fisik yang menjalankan image Pratinjau Developer 10
2. Jalankan perintah berikut:

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

Kemudian, pilih opsi yang ditampilkan untuk mengizinkan iklan yang disarankan aplikasi.

1. Jalankan perintah berikut untuk mengaktifkan API yang relevan. Anda mungkin perlu menjalankannya kembali sesekali karena konfigurasi default nonaktif akan disinkronkan secara berkala.

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. Mulai ulang perangkat.
2. Ganti kunci lelang perangkat agar mengarah ke server kunci lelang Anda. Penting untuk menjalankan langkah ini sebelum mencoba menjalankan lelang guna mencegah kunci yang salah disimpan di cache.

Layanan Bidding & Lelang

Untuk menyiapkan server B&A, lihat dokumentasi penyiapan layanan mandiri.

Dokumen ini akan berfokus pada cara mengonfigurasi server khusus pembeli karena tidak ada perubahan yang diperlukan untuk penjual.

Prasyarat

Sebelum men-deploy stack layanan B&A, teknologi iklan pembeli harus:

• Memastikan mereka telah men-deploy Layanan Pengambilan Iklan TEE sendiri (lihat bagian yang relevan).
• Memastikan teknologi iklan memiliki semua UDF yang diperlukan (prepareDataForAdRetrieval, generateBid, reportWin, getCandidateAds) yang ditentukan dan dihosting.

Pemahaman tentang cara kerja Protected Auction dan Protected Audience dengan B&A juga akan membantu, tetapi tidak wajib.

Konfigurasi Terraform

Untuk menggunakan Protected App Signals, teknologi iklan harus:

• Mengaktifkan dukungan Protected App Signals di B&A.
• Menyediakan endpoint URL tempat UDF baru untuk prepareDataForAdRetrieval, generateBid dan reportWin dapat diambil.

Selain itu, panduan ini mengasumsikan bahwa teknologi iklan yang ingin menggunakan B&A untuk pemasaran ulang akan terus menetapkan semua flag konfigurasi yang ada untuk lelang pemasaran ulang seperti biasa.

Konfigurasi teknologi iklan pembeli

Dengan menggunakan file demo ini sebagai contoh, pembeli harus menyetel flag berikut:

• Aktifkan Protected App Signals: Diaktifkan untuk mengumpulkan data Protected App Signals.
• URL Protected App Signals: Tetapkan ke URL server Protected App Signals.

Teknologi iklan harus mengganti URL yang benar di placeholder untuk kolom berikut:

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"

Konfigurasi teknologi iklan penjual

Dengan menggunakan file demo ini sebagai contoh, penjual harus menetapkan flag berikut. (Catatan: hanya konfigurasi terkait Protected App Signals yang ditandai di sini). Teknologi iklan harus memastikan bahwa mereka mengganti URL yang benar di placeholder:

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"

Layanan KV dan Pengambilan Iklan

Bergantung pada strategi yang dipilih untuk mendukung pengambilan iklan, sistem akan memerlukan deployment satu atau dua instance layanan KV. Kita akan merujuk ke instance instance KV yang digunakan untuk pengambilan iklan berbasis TEE sebagai Ad Retrieval Server dan ke instance untuk mendukung pengambilan berbasis jalur kontekstual sebagai KV Lookup Server.

Dalam kedua kasus, deployment server mengikuti dokumentasi yang tersedia di GitHub server KV. Perbedaan antara kedua kasus tersebut adalah kasus pencarian berfungsi secara default tanpa konfigurasi tambahan, sedangkan kasus pengambilan memerlukan deployment UDF getCandidateAds untuk menerapkan logika pengambilan. Untuk mengetahui detail selengkapnya, lihat panduan aktivasi server KV. Perhatikan bahwa B&A mengharapkan kedua layanan tersebut di-deploy di mesh layanan yang sama dengan layanan bidding.

Contoh Penyiapan

Pertimbangkan skenario berikut: menggunakan Protected App Signals API, teknologi iklan menyimpan sinyal yang relevan berdasarkan penggunaan aplikasi pengguna. Dalam contoh kami, sinyal disimpan yang mewakili pembelian dalam aplikasi dari beberapa aplikasi. Selama lelang, sinyal terenkripsi dikumpulkan dan diteruskan ke Protected Auction yang berjalan di B&A. UDF pembeli yang berjalan di B&A menggunakan sinyal untuk mengambil kandidat iklan dan menghitung bid.

[Pembeli] Contoh sinyal

Menambahkan sinyal dengan kunci 0 dan nilai 1.

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

Menambahkan sinyal dengan kunci 1 dan nilai 2.

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

[Pembeli] Contoh encodeSignals

Mengenkode setiap sinyal menjadi dua byte, dengan byte pertama menjadi byte pertama kunci sinyal dan byte kedua menjadi byte pertama nilai sinyal.

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

[Pembeli] Contoh prepareDataForAdRetrieval

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

[Pembeli] Contoh UDF pengambilan iklan

Dalam contoh kami, server pengambilan iklan mengirim metadata (yaitu ID untuk setiap iklan dalam contoh ini, tetapi dapat berisi data lain untuk setiap iklan yang dapat membantu dalam membuat bid nantinya) untuk setiap kandidat iklan top-k.

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

[Pembeli] Contoh generateBid

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

[Pembeli] Contoh reportWin

reportWin UDF melaporkan kepada pembeli bahwa mereka memenangkan lelang.

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

[Penjual] Penyiapan server KV

Penjual harus menyiapkan server KV sinyal penskoran sehingga tersedia pemetaan dari URL render iklan ke sinyal penskoran yang sesuai, misalnya: jika https:/buyer-domain.com/get-fitness-app dan https:/buyer-domain.com/get-fastfood-app ditampilkan oleh pembeli, penjual dapat memiliki contoh respons sinyal penskoran berikut saat dikueri oleh SFE menggunakan GET di https://key-value-server-endpoint.com?client_type=1&renderUrls=<render-url-returned-by-the-buyer>:

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

[Penjual] Contoh scoreAd

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

[Penjual] Contoh reportResult

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

Aplikasi contoh

Sebagai contoh cara API dapat digunakan untuk membuat aplikasi yang menggunakan alur sederhana seperti yang dijelaskan di atas, kami telah membuat aplikasi contoh Protected App Signals yang dapat ditemukan di repositori contoh ini.