Panduan developer Protected Audience API

Saat Anda membaca dokumentasi Privacy Sandbox di Android, gunakan tombol Pratinjau Developer atau Beta untuk memilih versi program yang sedang Anda gunakan, karena petunjuknya dapat bervariasi.

Berikan masukan

Protected Audience API di Android (sebelumnya disebut FLEDGE) menyertakan Custom Audience API dan Ad Selection API. Platform teknologi iklan dan pengiklan dapat menggunakan API ini untuk menayangkan iklan yang disesuaikan berdasarkan interaksi aplikasi sebelumnya sehingga membatasi berbagi ID di seluruh aplikasi dan membatasi berbagi informasi interaksi aplikasi pengguna dengan pihak ketiga.

Custom Audience API berpusat di sekitar abstraksi "audiens kustom" yang mewakili sekelompok pengguna dengan niat yang sama. Pengiklan dapat mendaftarkan pengguna ke audiens kustom dan mengaitkan iklan yang relevan dengan audiens kustom tersebut. Informasi ini disimpan secara lokal dan dapat digunakan untuk menginformasikan bid pengiklan, pemfilteran iklan, dan rendering iklan.

Ad Selection API menyediakan framework yang memungkinkan beberapa developer menjalankan lelang secara lokal untuk audiens kustom. Untuk mencapai hal ini, sistem akan mempertimbangkan iklan yang relevan yang terkait dengan audiens kustom dan melakukan pemrosesan tambahan pada iklan yang ditampilkan oleh platform teknologi iklan ke perangkat.

Platform teknologi iklan dapat mengintegrasikan API ini untuk menerapkan pemasaran ulang yang tetap menjaga privasi pengguna. Dukungan untuk kasus penggunaan tambahan, seperti iklan instal aplikasi, direncanakan untuk rilis mendatang. Pelajari lebih lanjut Protected Audience API di Android dalam proposal desain.

Panduan ini menjelaskan cara menggunakan Protected Audience API di Android untuk melakukan hal berikut:

1. Mengelola audiens kustom
2. Menyiapkan dan menjalankan pemilihan iklan di perangkat
3. Melaporkan tayangan iklan

Sebelum memulai

Sebelum Anda memulai, selesaikan hal-hal berikut:

1. Menyiapkan lingkungan pengembangan Anda untuk Privacy Sandbox di Android.
2. Instal image sistem ke perangkat yang didukung atau siapkan emulator yang menyertakan dukungan untuk Privacy Sandbox di Android.

3. Di terminal, aktifkan akses ke Protected Audience API (dinonaktifkan secara default) dengan perintah adb berikut.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Sertakan izin ACCESS_ADSERVICES_CUSTOM_AUDIENCE dalam manifes aplikasi Anda:

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

5. Referensikan konfigurasi layanan iklan di elemen <application> manifes Anda:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

6. Tentukan resource XML layanan iklan yang dirujuk dalam manifes, seperti res/xml/ad_services_config.xml. Pelajari izin layanan iklan dan kontrol akses SDK lebih lanjut.

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

7. Secara default, Ad Selection API menerapkan batas jumlah maksimum memori yang dapat dialokasikan oleh skrip pelaporan lelang atau tayangan. Fitur pembatasan memori memerlukan WebView versi 105.0.5195.58 atau yang lebih tinggi. Platform ini menerapkan pemeriksaan versi dan panggilan ke selectAds API dan reportImpression API akan gagal jika hal ini tidak terpenuhi. Ada dua opsi untuk menyiapkannya:

   • Opsi 1: Jalankan perintah adb berikut untuk menonaktifkan pemeriksaan ini:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Opsi 2: Instal WebView Beta dari Google Play Store. Versi ini harus sama dengan atau lebih tinggi dari versi yang disebutkan sebelumnya.

Bergabung dengan audiens kustom

Audiens kustom mewakili sekelompok pengguna yang memiliki niat atau minat sama seperti yang ditentukan oleh aplikasi pengiklan. Aplikasi atau SDK dapat menggunakan audiens kustom untuk menunjukkan audiens tertentu, seperti seseorang yang telah meninggalkan item dalam keranjang belanja. Untuk membuat atau bergabung dengan audiens kustom secara asinkron, lakukan hal berikut:

1. Lakukan inisialisasi objek CustomAudienceManager.
2. Buat objek CustomAudience dengan menentukan parameter utama seperti paket pembeli dan nama yang relevan. Lalu, inisialisasi objek JoinCustomAudienceRequest dengan objek CustomAudience.
3. Panggil joinCustomAudience() asinkron dengan objek JoinCustomAudienceRequest dan objek Executor dan OutcomeReceiver yang relevan.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

Kombinasi parameter berikut secara unik mengidentifikasi setiap objek CustomAudience di perangkat:

• owner: Nama paket aplikasi pemilik. Secara implisit, nama ini ditetapkan ke nama paket aplikasi pemanggil.
• buyer: ID untuk jaringan iklan pembeli yang mengelola iklan untuk audiens kustom ini.
• name: Nama atau ID arbitrer untuk audiens kustom.

Memanggil joinCustomAudience() berulang kali dengan instance CustomAudience lain akan mengupdate semua CustomAudience yang ada dengan owner, buyer yang cocok, dan parameter name. Untuk membantu menjaga privasi, hasil API tidak membedakan antara "creation" (pembuatan) dan "update".

Selain itu, CustomAudience harus dibuat dengan parameter yang diperlukan berikut:

• URL update harian: URL HTTPS dikueri setiap hari di latar belakang untuk mengupdate sinyal bidding pengguna audiens kustom, data bidding tepercaya, serta URL dan metadata render untuk iklan.
• URL logika bidding: URL HTTPS yang dikueri selama pemilihan iklan untuk mengambil logika bidding JavaScript pembeli. Lihat tanda tangan fungsi yang diperlukan dalam JavaScript ini.
• ID Render Iklan: ID arbitrer yang ditetapkan oleh teknologi iklan pembeli. Penetapan ini adalah pengoptimalan untuk menghasilkan payload untuk B&A.

Parameter opsional untuk objek CustomAudience dapat mencakup:

• Waktu aktivasi: Audiens kustom hanya dapat berpartisipasi dalam pemilihan iklan dan update harian setelah waktu aktivasinya. Misalnya, waktu aktivasi bisa berguna untuk melibatkan pengguna aplikasi yang tidak aktif.
• Waktu habis masa berlaku: Waktu mendatang saat audiens kustom dihapus dari perangkat.
• Sinyal bidding pengguna: String JSON yang berisi sinyal pengguna, seperti lokalitas pilihan pengguna, yang digunakan oleh JavaScript logika bidding pembeli untuk menghasilkan bid selama proses pemilihan iklan. Format ini membantu platform teknologi iklan menggunakan kembali kode di seluruh platform dan memudahkan pemakaian dalam fungsi JavaScript.
• Data bidding tepercaya: URL HTTPS dan daftar string yang digunakan selama proses pemilihan iklan yang mengambil sinyal bidding dari server Kunci/Nilai yang tepercaya.
• Iklan: Daftar objek AdData yang sesuai dengan iklan yang berpartisipasi dalam pemilihan iklan. Setiap objek AdData terdiri dari:
  • URL Render: URL HTTPS yang dikueri untuk merender iklan akhir.
  • Metadata: Objek JSON yang diserialisasi sebagai string yang berisi informasi yang akan digunakan oleh logika bidding pembeli selama proses pemilihan iklan.
  • Filter Iklan: Class yang berisi semua informasi yang diperlukan untuk penginstalan iklan dan pembatasan frekuensi penginstalan aplikasi selama pemilihan iklan.

Berikut adalah contoh pembuatan instance objek CustomAudience:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

Menangani hasil joinCustomAudience()

Metode joinCustomAudience() asinkron menggunakan objek OutcomeReceiver untuk memberi sinyal hasil panggilan API.

• Callback onResult() menandakan bahwa audiens kustom berhasil dibuat atau diperbarui.
• Callback onError() menandakan adanya dua kemungkinan kondisi.
  • Jika JoinCustomAudienceRequest diinisialisasi dengan argumen yang tidak valid, AdServicesException akan menunjukkan IllegalArgumentException sebagai penyebabnya.
  • Semua error lainnya akan menerima AdServicesException dengan IllegalStateException sebagai penyebabnya.

Berikut adalah contoh penanganan hasil joinCustomAudience():

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

Keluar dari audiens kustom

Jika pengguna tidak lagi memenuhi kriteria bisnis untuk audiens kustom tertentu, aplikasi atau SDK dapat memanggil leaveCustomAudience() untuk menghapus audiens kustom dari perangkat. Untuk menghapus CustomAudience berdasarkan parameter uniknya, lakukan hal berikut:

1. Lakukan inisialisasi objek CustomAudienceManager.
2. Lakukan inisialisasi LeaveCustomAudienceRequest dengan buyer dan name audiens kustom. Untuk mempelajari kolom input ini lebih lanjut, baca "Bergabung dengan audiens kustom".
3. Panggil metode leaveCustomAudience() asinkron dengan objek LeaveCustomAudienceRequest serta objek Executor dan OutcomeReceiver yang relevan.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

Seperti halnya memanggil joinCustomAudience(), OutcomeReceiver menandakan akhir panggilan API. Untuk membantu melindungi privasi, hasil error tidak membedakan antara error internal dan argumen yang tidak valid. Callback onResult() dipanggil saat panggilan API telah selesai, baik audiens kustom yang cocok berhasil dihapus maupun tidak.

Menjalankan pemilihan iklan

Untuk menggunakan Protected Audience API untuk memilih iklan, panggil metode selectAds():

1. Lakukan inisialisasi objek AdSelectionManager.
2. Buat objek AdSelectionConfig.
3. Panggil metode selectAds() asinkron dengan objek AdSelectionConfig serta objek Executor dan OutcomeReceiver yang relevan.

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

Metode selectAds() memerlukan input AdSelectionConfig, dan Anda harus menentukan parameter wajib berikut:

• Penjual: ID untuk jaringan iklan penjual yang memulai pemilihan iklan.
• URL logika keputusan: URL HTTPS yang dikueri untuk mendapatkan logika JavaScript jaringan iklan penjual.
  • URL HTTPS: dikueri untuk mendapatkan logika JavaScript jaringan iklan penjual. Lihat tanda tangan fungsi yang diperlukan.
  • URI bawaan: yang mengikuti format pemilihan iklan FLEDGE. IllegalArgumentException ditampilkan, jika URI bawaan yang tidak didukung atau salah format diteruskan.
• Pembeli audiens kustom: Daftar lengkap ID untuk jaringan iklan pembeli yang diizinkan oleh penjual untuk berpartisipasi dalam proses pemilihan iklan. ID pembeli ini sesuai dengan CustomAudience.getBuyer() audiens kustom yang berpartisipasi.

Parameter berikut dapat ditentukan secara opsional untuk pemilihan iklan yang lebih disesuaikan:

• Sinyal pemilihan iklan: Objek JSON, yang diserialisasi sebagai string, berisi sinyal yang akan digunakan oleh JavaScript logika bidding pembeli yang diambil dari CustomAudience.getBiddingLogicUrl().
• Sinyal penjual: Objek JSON, yang diserialisasi sebagai string, yang berisi sinyal yang digunakan oleh logika keputusan JavaScript yang diambil penjual dari AdSelectionConfig.getDecisionLogicUrl().
• Sinyal per pembeli: Peta objek JSON, yang diserialisasi sebagai string, yang berisi sinyal untuk digunakan oleh JavaScript logika bidding pembeli tertentu yang diambil dari CustomAudience.getBiddingLogicUrl(), yang diidentifikasi oleh kolom pembeli pada audiens kustom yang berpartisipasi.
• Iklan kontekstual: Kumpulan kandidat iklan yang dikumpulkan langsung dari pembeli selama lelang yang berlangsung di luar lelang Audiens yang Dilindungi.

Setelah iklan dipilih, hasil, bid, dan sinyal akan dipertahankan secara internal untuk pelaporan. Callback OutcomeReceiver.onResult() menampilkan AdSelectionOutcome yang berisi:

• URL render untuk iklan pemenang yang diperoleh dari AdData.getRenderUrl().
• ID pemilihan iklan yang unik untuk pengguna perangkat. ID ini digunakan untuk melaporkan tayangan iklan.

Jika pemilihan iklan tidak berhasil diselesaikan karena alasan seperti argumen tidak valid, waktu tunggu habis, atau konsumsi resource berlebih, callback OutcomeReceiver.onError() akan memberikan AdServicesException dengan perilaku berikut:

• Jika pemilihan iklan dimulai dengan argumen yang tidak valid, AdServicesException akan menunjukkan IllegalArgumentException sebagai penyebabnya.
• Semua error lainnya akan menerima AdServicesException dengan IllegalStateException sebagai penyebabnya.

Iklan kontekstual

Protected Audience dapat menyertakan iklan kontekstual ke Protected Auction. Iklan kontekstual harus dipilih di server teknologi iklan dan ditampilkan ke perangkat di luar Dilindungi Audience API. Iklan kontekstual kemudian dapat disertakan dalam lelang menggunakan AdSelectionConfig saat iklan tersebut berfungsi sama seperti pada iklan perangkat, termasuk kelayakan untuk pemfilteran iklan negatif. Setelah lelang Audiens Dilindungi selesai, Anda perlu memanggil reportImpression(). Tindakan ini memanggil reportWin() dalam iklan kontekstual pemenang, dengan pola yang sama seperti pelaporan tayangan, untuk menerima iklan pemenang di perangkat. Setiap iklan kontekstual membutuhkan pembeli, bid, link ke logika pelaporan, URL render, dan metadata iklan.

Untuk men-deploy iklan kontekstual dalam aplikasi, aplikasi target harus membuat objek ContextualAds:

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

Objek ContextualAds yang dihasilkan kemudian dapat diteruskan saat membuat AdSelectionConfig:

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

Pemfilteran iklan instal aplikasi

Pemfilteran iklan instal aplikasi membantu Anda memfilter iklan penginstalan untuk aplikasi yang sudah diinstal di perangkat.

Langkah pertama dalam proses ini adalah menentukan pengiklan yang memiliki kemampuan untuk memfilter paket yang diinstal. Hal ini harus terjadi di aplikasi yang ingin Anda targetkan dengan iklan.

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

Saat kode sebelumnya dieksekusi, pengiklan yang diteruskan kemudian dapat memfilter aplikasi terinstal yang Anda tentukan selama pembuatan bid. Jika pengiklan perlu menghapus akses pengiklan ke status penginstalan aplikasi ini, jalankan lagi kode ini dengan menghapus informasi pengiklan.

Langkah berikutnya adalah menyiapkan pemfilteran iklan di dalam aplikasi penayang. Pihak yang menayangkan iklan di dalam aplikasi penayang (kemungkinan besar berupa SDK sisi suplai) harus melakukan inisialisasi objek AdFilters mereka dengan informasi tentang iklan yang terkait dengan aplikasi yang akan mereka tampilkan ingin memfilter:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

Penayang sisi permintaan juga dapat menetapkan AdFilter untuk iklan yang ada di dalam audiens kustom mereka.

AdFilters juga dapat diteruskan pada saat membuat instance objek AdData baru:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

Pemfilteran batas frekuensi

Pemfilteran batas frekuensi memungkinkan teknologi iklan membatasi frekuensi iklan ditampilkan. Pemfilteran batas frekuensi mengurangi eksposur iklan yang berlebihan dan mengoptimalkan pemilihan iklan alternatif untuk kampanye iklan tertentu.

Ada dua komponen utama dari filter batas frekuensi: jenis peristiwa iklan dan kunci penghitung iklan. Jenis peristiwa iklan yang tersedia dan dapat digunakan adalah:

• Menang (segera hadir): Peristiwa menang menunjukkan bahwa iklan telah memenangkan lelang. Peristiwa menang akan otomatis diperbarui oleh Protected Audience API dan tidak dapat dipanggil langsung oleh developer. Data menang hanya dapat dilihat oleh iklan dalam audiens kustom tertentu.
• Tayangan: Terpisah dari reportImpression, pemanggil di perangkat (SSP atau MMP) menggunakan updateAdCounterHistogram() untuk memanggil peristiwa tayangan pada titik dalam kode yang dipilihnya. Peristiwa tayangan terlihat oleh semua iklan yang termasuk dalam DSP tertentu, dan tidak terbatas pada iklan dalam audiens kustom yang sama.
• Tampilan: Peristiwa dipanggil oleh pemanggil di perangkat (SSP atau MMP) pada titik dalam kode yang dipilih menggunakan panggilan ke updateAdCounterHistogram(). Peristiwa tampilan terlihat oleh semua iklan yang termasuk dalam DSP tertentu dan tidak terbatas pada iklan dalam Audiens Kustom yang sama.
• Klik: Peristiwa dipanggil oleh pemanggil di perangkat (SSP atau MMP) pada titik dalam kode yang dipilih menggunakan panggilan ke updateAdCounterHistogram(). Peristiwa klik terlihat oleh semua iklan yang termasuk dalam DSP tertentu dan tidak terbatas pada iklan dalam Audiens Kustom yang sama.

Di aplikasi penayang, SSP atau MMP yang ada di perangkat memanggil peristiwa iklan. Saat updateAdCounterHistogram() dipanggil, penghitung filter batas frekuensi akan bertambah sehingga lelang mendatang akan memiliki informasi terbaru tentang eksposur pengguna terhadap iklan tertentu. Jenis peristiwa iklan tidak terikat secara paksa ke tindakan pengguna yang sesuai dan merupakan panduan yang diberikan untuk membantu pemanggil membuat struktur sistem peristiwa. Untuk menambahkan penghitung iklan saat peristiwa muncul, aktor di perangkat memberikan ID pemilihan iklan dari lelang iklan pemenang.

Kunci penghitung iklan adalah bilangan bulat arbitrer bertanda 32-bit yang ditetapkan oleh teknologi iklan pembeli, dan sesuai dengan kumpulan iklan tertentu seperti yang ditetapkan oleh DSP. Karena kunci penghitung iklan hanya terbatas pada iklan yang termasuk dalam DSP tertentu, kunci ini dapat dipilih tanpa tumpang-tindih dengan histogram dari teknologi iklan lainnya. Kunci penghitung iklan digunakan untuk menambah ID khusus DSP di seluruh iklan DSP atau dalam audiens kustom tertentu untuk memfilter iklan dari lelang di masa mendatang.

Kunci penghitung dapat dimanfaatkan untuk memprioritaskan iklan yang mungkin lebih menarik bagi pengguna tertentu berdasarkan interaksi mereka dengan iklan lain dari teknologi iklan pembeli tertentu. Misalnya, iklan yang telah menerima interaksi tingkat tinggi dari lelang iklan, tampilan, dan klik pemenang, menunjukkan titik data yang disimpulkan. Untuk mengilustrasikan hal ini lebih lanjut: iklan stik golf untuk tangan kiri mungkin menunjukkan bahwa pengguna tidak akan tertarik dengan stik untuk tangan kanan. Filter pembatasan frekuensi yang ditetapkan untuk kunci penghitung yang ditetapkan untuk iklan tangan kiri dapat memfilter iklan untuk tangan kanan.

Untuk menggunakan pembatasan frekuensi di lelang, Anda harus terlebih dahulu membuat objek KeyedFrequencyCap seperti ditunjukkan di bawah ini:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

Setelah objek KeyedFrequencyCap dibuat, Anda dapat meneruskannya ke objek AdFilters.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

Saat objek AdFilters diisi dengan filter batas frekuensi, objek tersebut dapat diteruskan saat audiens kustom dibuat:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

Saat filter batas frekuensi diterapkan ke audiens kustom, SSP kemudian dapat memanggil peristiwa klik, tampilan, atau tayangan yang diperlukan.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

Iklan yang telah mencapai batas filter batas frekuensi yang telah ditetapkan sebelumnya akan dikecualikan dari lelang. Pemfilteran terjadi sebelum logika bidding dijalankan untuk lelang di perangkat, dan saat payload dibuat untuk lelang layanan Bidding & Lelang. Toolkit ini memberi teknologi iklan fleksibilitas untuk menggunakan interaksi antara pengguna dan iklan dalam audiens kustom untuk memfokuskan penargetan iklan sekaligus meminimalkan eksposur iklan yang berlebihan.

Pemfilteran iklan kontekstual tanpa panggilan jaringan

Jika tidak ada permintaan pemasaran ulang di perangkat, Anda dapat menjalankan pemilihan iklan untuk iklan kontekstual tanpa panggilan jaringan. Dengan URI bawaan dan daftar iklan kontekstual dengan bid, platform ini dapat melewati pengambilan logika bidding, sinyal bidding, dan sinyal skor. Platform ini menggunakan URI bawaan untuk memilih iklan kontekstual dengan bid tertinggi.

Untuk meningkatkan latensi, teknologi iklan dapat menjalankan alur pemilihan iklan yang hanya menyertakan iklan kontekstual dengan fungsi pemfilteran iklan tanpa panggilan jaringan. Hal ini dicapai dengan menggunakan URI bawaan untuk menilai sinyal. Lihat bagian Kasus penggunaan dan nama URI bawaan yang didukung untuk mengetahui daftar implementasi scoreAds.

Untuk menjalankan pemilihan iklan tanpa panggilan jaringan:

1. Siapkan pemfilteran iklan
2. Buat iklan kontekstual

3. Buat objek AdSelectionConfig dengan hal berikut:

   1. Daftar pembeli kosong
   2. URI bawaan untuk memilih bid tertinggi
   3. Iklan kontekstual
   4. URI kosong untuk sinyal penskoran. URI kosong diizinkan untuk menunjukkan bahwa Anda tidak ingin menggunakan pengambilan sinyal tepercaya untuk penskoran:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. Jalankan pemilihan iklan:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Menjalankan JavaScript pelaporan Anda sendiri saat menggunakan URI bawaan

Saat ini, platform Privacy Sandbox hanya memiliki implementasi JavaScript pelaporan dasar yang tersedia untuk URI bawaan. Jika ingin menjalankan JavaScript pelaporan sendiri saat masih menggunakan URI bawaan untuk pemilihan iklan latensi rendah, Anda dapat mengganti DecisionLogicUri antara pemilihan iklan dan pelaporan.

1. Menjalankan langkah-langkah untuk menjalankan pemilihan iklan kontekstual untuk iklan menggunakan URI bawaan

2. Membuat salinan AdSelectionConfig Anda sebelum menjalankan pelaporan

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. Menjalankan pelaporan tayangan

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Menjalankan mediasi waterfall

Mediasi waterfall mewajibkan beberapa SDK pihak ketiga (jaringan pihak ketiga) diatur oleh jaringan mediasi SDK pihak pertama. Mediasi waterfall dilakukan dengan cara yang sama, terlepas dari apakah lelang berlangsung di perangkat atau berjalan di layanan Bidding & Lelang (B&A).

Jaringan pihak ketiga

Jaringan pihak ketiga harus menyediakan adaptor yang memungkinkan jaringan mediasi memanggil metode yang diperlukan untuk menjalankan lelang:

• Menjalankan pemilihan iklan
• Melaporkan tayangan

Berikut adalah contoh adaptor jaringan mediasi:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Setiap SDK memiliki klien dan pengelola layanan pemilihan iklan sendiri serta implementasi selectAds dan reportImpressions mereka sendiri. Penyedia SDK dapat melihat bagian tentang cara menjalankan pemilihan iklan untuk lelang di perangkat atau penjelasan B&A untuk lelang B&A. Ikuti cara melaporkan tayangan iklan (mengikuti pelaporan tayangan SSP tunggal untuk pelaporan.

Jaringan mediasi

Serupa dengan jaringan pihak ketiga, jaringan mediasi memerlukan implementasi selectAds dan reportImpression. Lihat bagian tentang cara menjalankan pemilihan iklan dan cara melaporkan tayangan iklan untuk informasi selengkapnya.

Jaringan mediasi bertanggung jawab untuk menjalankan rantai mediasi dan menempatkan dirinya sendiri di rantai mediasi. Bagian berikutnya membahas cara menyiapkan dan menjalankan proses ini.

Mengambil rantai mediasi dan nilai minimum bid

Jaringan mediasi bertanggung jawab untuk mengambil iklan kontekstual pihak pertama (1P), rantai mediasi, dan nilai minimum bid jaringan pihak ketiga (3P). Hal ini dapat terjadi dalam permintaan untuk mengambil iklan kontekstual yang dijalankan oleh jaringan mediasi. Rantai mediasi menentukan cara melakukan iterasi melalui Jaringan Pihak Ketiga, dan nilai minimum bid dapat diteruskan ke proses lelang sebagai adSelectionSignals.

Penempatan jaringan dalam rantai mediasi

SDK mediasi dapat menempatkan dirinya sendiri di rantai mediasi berdasarkan eCPM langsung bid iklan pihak pertamanya. Di Protected Audience API, bid iklan tidak transparan. SDK mediasi harus menggunakan AdSelectionFromOutcomesConfig agar dapat membandingkan bid iklan pihak pertama yang ditentukan dengan nilai minimum bid jaringan pihak ketiga berikutnya di rantai tersebut. Jika bid pihak pertama lebih tinggi dari nilai minimum bid, berarti SDK mediasi ditempatkan di depan jaringan pihak ketiga tersebut.

Menjalankan pemilihan iklan

Untuk mengambil kandidat iklan pihak pertama, jaringan mediasi dapat menjalankan lelang di perangkat dengan mengikuti langkah-langkah di bagian menjalankan pemilihan iklan. Tindakan ini menghasilkan kandidat iklan pihak pertama, bid, dan AdSelectionId yang digunakan dalam proses mediasi.

Membuat AdSelectionFromOutcomesConfig

AdSelectionFromOutcomesConfig memungkinkan jaringan mediasi meneruskan daftar AdSelectionIds (hasil dari lelang sebelumnya), sinyal pemilihan iklan, dan URI untuk mengambil JavaScript yang memilih iklan dari beberapa kandidat. Daftar AdSelectionIds beserta bid-nya dan sinyal diteruskan ke JavaScript yang dapat menampilkan salah satu AdSelectionIds jika mengalahkan nilai minimum bid, atau tidak sama sekali jika rantai mediasi harus dilanjutkan.

Jaringan Mediasi membuat AdSelectionFromOutcomesConfig menggunakan AdSelectionId pihak pertama dari bagian sebelumnya, dan nilai minimum bid untuk Jaringan Pihak Ketiga yang dipertimbangkan. AdSelectionFromOutcomesConfig baru harus dibuat untuk setiap langkah dalam rantai mediasi.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

Penggantian metode selectAds() untuk mediasi waterfall memerlukan input AdSelectionFromOutcomesConfig, tempat Anda harus menentukan parameter yang diperlukan berikut:

• Penjual: ID untuk jaringan iklan penjual yang memulai pemilihan iklan.
• AdSelectionIds: Daftar singleton dari selectAds() sebelumnya yang dijalankan untuk iklan pihak pertama.
• Sinyal pemilihan iklan: Objek JSON, yang diserialisasi sebagai string, berisi sinyal yang akan digunakan oleh logika bidding pembeli. Dalam hal ini, sertakan nilai minimum bid yang diambil untuk jaringan pihak ketiga yang ditentukan.
• URI Logika Pemilihan: URL HTTPS yang dikueri selama pemilihan iklan untuk mengambil JavaScript jaringan mediasi guna memilih iklan pemenang. Lihat tanda tangan fungsi yang diperlukan dalam JavaScript ini. JavaScript harus menampilkan iklan pihak ketiga jika bid lebih tinggi dari nilai minimum bid. Jika tidak, null yang ditampilkan. Hal ini memungkinkan SDK mediasi memotong rantai mediasi saat pemenang ditemukan.

Setelah AdSelectionOutcomesConfig dibuat, panggil metode selectAds() jaringan pihak ketiga yang pertama dalam rantai.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

Mengatur mediasi waterfall

Berikut ini urutan operasi untuk menjalankan proses mediasi.

1. Jalankan pemilihan iklan pihak pertama.
2. Lakukan iterasi melalui rantai mediasi. Untuk setiap jaringan pihak ketiga, lakukan hal berikut:
   1. Build AdSelectionFromOutcomeConfig, termasuk outcomeId pihak pertama dan nilai minimum bid SDK pihak ketiga.
   2. Panggil selectAds() dengan konfigurasi dari langkah sebelumnya.
   3. Jika hasilnya tidak kosong, tampilkan iklan.
   4. Panggil metode selectAds() adaptor jaringan SDK saat ini. Jika hasilnya tidak kosong, tampilkan iklan.
3. Jika tidak ada pemenang yang ditemukan dari rantai, tampilkan iklan pihak pertama.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

Melaporkan tayangan iklan

Ada dua alur untuk melaporkan tayangan iklan, bergantung pada cara lelang dijalankan. Jika Anda adalah satu SSP yang menjalankan lelang, ikuti bagian ini. Jika Anda akan menerapkan mediasi waterfall, ikuti langkah-langkah yang ditemukan di bagian pelaporan tayangan mediasi waterfall.

Pelaporan tayangan SSP tunggal

Setelah iklan yang menang dipilih dari alur kerja pemilihan iklan, Anda dapat melaporkan kembali tayangan ke platform sisi jual dan sisi beli yang berpartisipasi dengan metode AdSelectionManager.reportImpression(). Untuk melaporkan tayangan iklan:

1. Lakukan inisialisasi objek AdSelectionManager.
2. Buat objek ReportImpressionRequest dengan ID pemilihan iklan.
3. Panggil metode reportImpression() asinkron dengan objek ReportImpressionRequest serta objek Executor dan OutcomeReceiver yang relevan.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

Lakukan inisialisasi ReportImpressionRequest dengan parameter yang diperlukan berikut:

• ID pemilihan iklan: ID unik hanya untuk pengguna perangkat yang mengidentifikasi pemilihan iklan yang berhasil.
• Konfigurasi pemilihan iklan: Konfigurasi yang sama yang digunakan dalam panggilan selectAds() yang diidentifikasi oleh ID pemilihan iklan yang disediakan.

Metode reportImpression() asinkron menggunakan objek OutcomeReceiver untuk memberi sinyal hasil panggilan API.

• Callback onResult() menunjukkan apakah URL pelaporan tayangan telah dibuat dan permintaan telah dijadwalkan.
• Callback onError() menunjukkan kemungkinan kondisi berikut:
  • Jika panggilan diinisialisasi dengan argumen input yang tidak valid, AdServicesException akan menunjukkan IllegalArgumentException sebagai penyebabnya.
  • Semua error lainnya akan menerima AdServicesException dengan IllegalStateException sebagai penyebabnya.

Pelaporan tayangan mediasi waterfall

SDK mediasi perlu memantau SDK pemenang untuk memicu alur pelaporannya. SDK yang berpartisipasi dalam rantai mediasi harus menyediakan metode bagi mediator untuk memanggil guna memicu alur pelaporannya sendiri. SDK yang berpartisipasi dalam lelang yang dimediasi dapat mengikuti langkah-langkah di atas untuk menerapkan pelaporannya sendiri.

SSP dapat menggunakan contoh kode SDK pihak ketiga ini sebagai prototipe untuk cara bergabung dalam alur mediasi:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

Endpoint pelaporan tayangan

API tayangan laporan akan menerbitkan permintaan GET HTTPS ke endpoint yang disediakan oleh platform sisi jual dan platform sisi beli yang menang:

Endpoint platform sisi beli:

• API ini menggunakan URL logika bidding yang ditentukan dalam audiens kustom untuk mengambil JavaScript yang disediakan pembeli yang menyertakan logika untuk menampilkan URL pelaporan tayangan.
• Panggil fungsi JavaScript reportWin() yang diharapkan akan menampilkan URL pelaporan tayangan pembeli.

Endpoint platform sisi jual:

• Gunakan URL logika keputusan yang ditentukan dalam objek AdSelectionConfig untuk mengambil JavaScript logika keputusan penjual.
• Panggil fungsi JavaScript reportResult() yang diharapkan akan menampilkan URL pelaporan tayangan pembeli.

Pelaporan layanan Bidding & Lelang

Lelang yang dijalankan di layanan Bidding & Lelang akan memiliki semua informasi pelaporan yang diperlukan, termasuk URL yang dihasilkan untuk pelaporan interaksi iklan, yang disertakan dalam respons terenkripsi dari lelang sisi server. Saat respons didekripsi, URL yang sesuai akan didaftarkan dengan platform, sehingga pelaporan iklan dan tayangan mengikuti langkah-langkah yang sama seperti yang tercantum di atas.

Upaya terbaik Pelaporan tayangan

reportImpression() dirancang untuk menawarkan upaya penyelesaian pelaporan yang paling mudah.

Melaporkan Interaksi Iklan

Protected Audience memberikan dukungan untuk melaporkan interaksi yang lebih terperinci untuk iklan yang dirender. Hal ini dapat mencakup interaksi seperti waktu tampilan, klik, kursor, atau metrik berguna lainnya yang dapat dikumpulkan. Ada dua langkah untuk menerima laporan ini. Pertama, pembeli dan penjual harus mendaftar untuk menerima laporan ini di JavaScript pelaporannya. Selanjutnya, klien harus melaporkan peristiwa ini.

Mendaftar untuk menerima peristiwa interaksi

Proses pendaftaran peristiwa interaksi terjadi di reportWin() pembeli dan fungsi JavaScript reportResult() penjual menggunakan fungsi JavaScript yang disediakan oleh platform: registerAdBeacon. Untuk mendaftar guna menerima laporan peristiwa, cukup panggil Fungsi JavaScript platform dari JavaScript pelaporan Anda. Cuplikan berikut menggunakan reportWin() pembeli, tetapi pendekatan yang sama berlaku untuk reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri
    registerAdBeacon("click", clickUri)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

Melaporkan peristiwa interaksi

Setelah melaporkan tayangan, klien dapat melaporkan interaksi kembali ke platform sisi beli dan sisi jual yang menang yang sebelumnya terdaftar dengan metode AdSelectionManager.reportInteraction(). Untuk melaporkan peristiwa iklan:

1. Lakukan inisialisasi objek AdSelectionManager.
2. Bangun objek ReportInteractionRequest dengan ID pemilihan iklan, kunci interaksi, data interaksi, dan tujuan pelaporan.
3. Panggil metode reportInteraction() asinkron dengan objek request dan objek Executor dan OutcomeReceiver yang relevan.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

Lakukan inisialisasi ReportInteractionRequest dengan parameter yang diperlukan berikut:

• ID pemilihan iklan: ID pemilihan iklan yang diambil dari AdSelectionOutcome yang ditampilkan sebelumnya.
• Kunci Interaksi: Kunci string yang ditentukan oleh klien yang menjelaskan tindakan yang dilaporkan. Ini harus cocok dengan kunci yang didaftarkan oleh penjual atau pembeli dalam fungsi JavaScript pelaporan.
• Data Interaksi: String yang berisi data yang akan disertakan dengan laporan peristiwa, yang akan di-POST kembali ke server pelaporan.
• Tujuan Pelaporan: Bit mask yang menentukan apakah peristiwa harus dilaporkan kepada pembeli, penjual, atau keduanya. Tanda ini disediakan oleh platform dan mask tujuan akhir dapat dibuat menggunakan operasi bitwise. Untuk melaporkan ke satu tujuan, Anda dapat menggunakan tanda yang disediakan langsung oleh platform. Untuk melaporkan ke beberapa tujuan, Anda dapat menggunakan bitwise OR (|) untuk menggabungkan nilai tanda.

Metode reportInteraction() asinkron menggunakan objek OutcomeReceiver untuk memberi sinyal hasil panggilan API.

• Callback onResult() menunjukkan panggilan interaksi laporan valid.
• Callback onError() menunjukkan kemungkinan kondisi berikut:
  • Jika panggilan dilakukan saat aplikasi berjalan di latar belakang, IllegalStateException dengan deskripsi kegagalan akan ditampilkan.
  • Jika klien di-throttle agar tidak memanggil reportInteraction(), LimitExceededException akan ditampilkan.
  • Jika paket tidak terdaftar untuk memanggil Privacy Preserving API, SecurityException() akan ditampilkan.
  • Jika interaksi pelaporan aplikasi berbeda dari aplikasi yang memanggil selectAds(), IllegalStateException akan ditampilkan.
• Jika pengguna belum memberikan izin untuk mengaktifkan Privacy Sandbox API, panggilan akan gagal tanpa ada peringatan.

Endpoint pelaporan interaksi

API interaksi laporan menerbitkan permintaan POST HTTPS ke endpoint yang disediakan oleh platform sisi jual dan platform sisi beli yang menang. Audience Terlindungi akan cocok dengan kunci interaksi dengan URI yang dideklarasikan dalam pelaporan JavaScript dan mengeluarkan permintaan POST ke setiap endpoint untuk setiap interaksi yang dilaporkan. Jenis konten permintaan adalah teks biasa dengan isi berupa Data Interaksi.

Upaya terbaik Pelaporan interaksi

reportInteraction() dirancang untuk menawarkan upaya penyelesaian pelaporan yang sebaik mungkin melalui HTTP POST.

Update latar belakang harian

Saat membuat audiens kustom, aplikasi atau SDK Anda dapat menginisialisasi metadata audiens kustom. Selain itu, platform ini dapat mengupdate bagian dari metadata audiens kustom berikut dengan proses update di latar belakang harian.

• Sinyal bidding pengguna
• Data bidding tepercaya
• Daftar AdData

Proses ini mengajukan kueri terhadap URL Update harian yang ditentukan dalam audiens kustom dan URL tersebut dapat menampilkan respons JSON.

• Respons JSON mungkin berisi salah satu kolom metadata yang didukung dan perlu diperbarui.
• Setiap kolom JSON divalidasi secara terpisah. Klien mengabaikan kolom yang rusak sehingga tidak ada update pada kolom tersebut dalam respons.
• Respons HTTP kosong atau objek JSON kosong "{}" tidak akan menghasilkan update metadata.
• Ukuran pesan respons harus dibatasi hingga 10 KB.
• Semua URI diperlukan untuk menggunakan HTTPS.
• trusted_bidding_uri harus memiliki ETLD+1 yang sama dengan pembeli.

Contoh: Respons JSON untuk update harian latar belakang

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript untuk pemilihan iklan

Alur kerja pemilihan iklan mengatur eksekusi JavaScript yang disediakan pembeli dan yang disediakan penjual.

JavaScript yang disediakan pembeli diambil dari URL logika Bidding yang ditentukan dalam audiens kustom. JavaScript yang ditampilkan harus menyertakan fungsi berikut:

• generateBid()
• reportWin()

JavaScript yang disediakan penjual diambil dari URL logika keputusan yang ditentukan dalam parameter AdSelectionConfig untuk ad selection API. JavaScript yang ditampilkan harus menyertakan fungsi berikut:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Parameter input:

• ad: objek JSON dengan format var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: objek JSON yang ditentukan dalam objek konfigurasi lelang

• custom_audience_bidding_signals: objek JSON yang dihasilkan oleh platform. Format untuk objek JSON ini adalah:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  dalam hal ini:

  • owner, buyer, name adalah string yang diambil dari properti dengan nama Audiens Khusus yang sama yang berpartisipasi dalam pemilihan iklan
  • activation_time dan expiration_time adalah waktu aktivasi dan berakhirnya masa berlaku audiens kustom yang dinyatakan sebagai detik sejak epoch Unix
  • ca_user_bidding_signals adalah string JSON yang ditentukan dalam kolom userBiddingSignals dari CustomAudience pada waktu pembuatan
  • trusted_bidding_signals, contextual_signals dan user_signals adalah objek JSON. Objek tersebut diteruskan sebagai objek kosong dan akan diisi di rilis mendatang. Formatnya tidak diterapkan oleh platform dan dikelola oleh teknologi iklan.

Hasil:

• ad: adalah iklan yang dirujuk oleh bid. Skrip ini diizinkan untuk menampilkan salinan iklan yang diterima dengan metadata berbeda. Properti render_url iklan tidak akan diubah.
• bid: nilai float yang mewakili nilai bid untuk iklan ini
• status: nilai bilangan bulat yang dapat berupa:
  • 0: untuk keberhasilan eksekusi
  • 1: (atau nilai apa pun yang bukan nol) jika sinyal input apa pun tidak valid. Jika nilai bukan nol ditampilkan oleh generate-bid, proses bidding untuk semua iklan CA menjadi tidak valid

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Parameter input:

• ad: lihat dokumentasi generateBid
• bid: nilai bid untuk iklan

• ad_selection_config: objek JSON yang mewakili parameter AdSelectionConfig selectAds API. Formatnya adalah:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals: Objek JSON yang dibaca dari parameter API sellerSignals AdSelectionConfig

• trusted_scoring_signal: yang dibaca dari kolom adSelectionSignals di parameter API AdSelectionConfig

• contextual_signals, user_signals: Objek JSON. Saat ini objek tersebut diteruskan sebagai objek kosong dan akan diisi di rilis mendatang. Formatnya tidak diterapkan oleh platform dan dikelola oleh teknologi iklan.

• per_buyer_signals: Objek JSON dibaca dari peta perBuyerSignal dalam parameter API AdSelectionConfig menggunakan kunci sebagai pembeli Audiens Kustom saat ini. Kosong jika peta tidak berisi entri untuk pembeli tertentu.

Output:

• score: nilai float yang mewakili nilai skor untuk iklan ini
• status: nilai bilangan bulat yang dapat berupa:
  • 0: untuk keberhasilan eksekusi
  • 1: jika customAudienceSignals tidak valid
  • 2: jika AdSelectionConfig tidak valid
  • 3: jika salah satu sinyal lain tidak valid
  • Nilai apa pun yang bukan nol menyebabkan kegagalan proses, nilai tersebut akan menentukan jenis pengecualian yang ditampilkan

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Parameter input:

• outcomes: objek JSON {"id": id_string, "bid": bid_double}
• selection_signals: Objek JSON yang ditentukan dalam objek konfigurasi lelang

Output:

• status: 0 untuk berhasil dan bukan nol untuk gagal
• result: salah satu hasil yang diteruskan atau null

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Parameter input:

• ad_selection_config: lihat dokumentasi scoreAds
• render_url: URL render iklan pemenang
• bid: bid yang ditawarkan untuk iklan pemenang
• contextual_signals: lihat dokumentasi generateBid

Output:

• status: 0 untuk berhasil dan bukan nol untuk gagal
• results: objek JSON yang berisi:
  • signals_for_buyer: objek JSON yang diteruskan ke fungsi reportWin
  • reporting_url: URL yang digunakan oleh platform untuk memberi tahu tayangan kepada pembeli

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

Parameter input:

• ad_selection_signals, per_buyer_signals: lihat dokumentasi untuk scoreAd
• signals_for_buyer: objek JSON yang ditampilkan oleh reportResult
• contextual_signals, custom_audience_signals: lihat dokumentasi untuk generateBid

Output:

• status: 0 untuk berhasil dan bukan nol untuk gagal
• results: objek JSON yang berisi:
  • reporting_url: URL yang digunakan oleh platform untuk memberi tahu tayangan kepada penjual

registerAdBeacon()

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Parameter Input:

• interaction_key: String yang mewakili peristiwa. Hal ini digunakan oleh platform nanti saat melaporkan interaksi peristiwa untuk mencari reporting_uri yang akan diberi tahu. Kunci ini harus cocok antara apa yang didaftarkan oleh pembeli atau penjual, dan apa yang dilaporkan oleh penjual.
• reporting_uri: URI untuk menerima laporan peristiwa. Ini harus spesifik untuk jenis peristiwa yang dilaporkan. Aplikasi harus menerima permintaan POST untuk menangani data yang dilaporkan bersamaan dengan peristiwa tersebut.

URI bawaan Pilihan Iklan

URI bawaan memberi teknisi iklan kemampuan untuk menetapkan fungsi JavaScript untuk logika keputusan pemilihan iklan di class AdSelectionConfig dan AdSelectionFromOutcomesConfig. URI bawaan tidak memerlukan panggilan jaringan untuk mendownload JavaScript yang sesuai. Teknologi iklan dapat menggunakan URI bawaan tanpa harus menyiapkan domain terdaftar untuk menghosting JavaScript.

URI bawaan dibuat menggunakan format berikut:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

Platform Privacy Sandbox menyediakan JavaScript menggunakan informasi dari URI ini dalam runtime.

IllegalArgumentException ditampilkan jika:

• salah satu parameter yang diperlukan tidak ada di URI
• ada parameter yang tidak dikenal dalam URI

Kasus penggunaan dan nama URI bawaan yang didukung

Kasus penggunaan 1: pemilihan iklan

URI bawaan dalam kasus penggunaan ad-selection didukung dalam alur selectAds(AdSelectionConfig).

Nama URI bawaan: highest-bid-wins

URI bawaan ini menyediakan JavaScript yang memilih iklan dengan bid tertinggi setelah bidding. Laporan ini juga menyediakan fungsi pelaporan dasar untuk melaporkan render_uri dan bid pemenang.

Parameter yang diperlukan

reportingUrl: URL pelaporan dasar yang diparameterisasi dengan render_uri dan bid iklan pemenang:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

Penggunaan

Jika URL pelaporan dasar Anda adalah https://www.ssp.com/reporting, URI bawaan akan menjadi:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Kasus penggunaan 2: ad-selection-from-outcomes

URI bawaan dalam kasus penggunaan ad-selection-from-outcomes mendukung alur kerja selectAds(AdSelectionFromOutcomesConfig).

Nama URI bawaan: waterfall-mediation-truncation

waterfall-mediation-truncation URI bawaan menyediakan JavaScript yang mengimplementasikan logika pemotongan mediasi waterfall tempat JavaScript menampilkan iklan pihak pertama jika bid lebih tinggi atau sama dengan bid floor, dan jika tidak, menampilkan null.

Parameter yang diperlukan

bidFloor: Kunci dari nilai minimum bid yang diteruskan di getSelectionSignals() yang dibandingkan dengan iklan SDK mediasi.

Penggunaan

Jika sinyal pemilihan iklan Anda terlihat seperti {"bid_floor": 10}, URI bawaan yang dihasilkan akan menjadi:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

Pengujian

Untuk membantu Anda memulai Protected Audience API, kami telah membuat aplikasi contoh di Kotlin dan Java yang dapat ditemukan di GitHub.

Prasyarat

Protected Audience API memerlukan beberapa JavaScript selama pemilihan iklan dan pelaporan tayangan. Ada dua metode untuk menyediakan JavaScript ini di lingkungan pengujian:

• Menjalankan server dengan endpoint HTTPS yang diperlukan yang menampilkan JavaScript
• Mengganti pengambilan jarak jauh dengan memberikan kode yang diperlukan dari sumber lokal

Salah satu pendekatan tersebut memerlukan penyiapan endpoint HTTPS untuk menangani pelaporan tayangan.

Endpoint HTTPS

Untuk menguji pemilihan iklan dan pelaporan tayangan, Anda harus menyiapkan 7 endpoint HTTPS yang dapat diakses oleh perangkat pengujian atau emulator Anda:

1. Endpoint pembeli yang menayangkan JavaScript logika bidding.
2. Endpoint yang menayangkan sinyal bidding.
3. Endpoint penjual yang menayangkan JavaScript logika keputusan.
4. Endpoint yang menyalurkan sinyal skor.
5. Endpoint pelaporan tayangan pembeli yang menang.
6. Endpoint pelaporan tayangan penjual.
7. Endpoint untuk menayangkan update harian untuk audiens kustom.

Demi kemudahan, repo GitHub menyediakan kode JavaScript dasar untuk tujuan pengujian. Repo GitHub ini juga mencakup definisi layanan OpenAPI yang dapat di-deploy ke platform tiruan atau microservice yang didukung. Untuk mengetahui detail selengkapnya, lihat README project.

Mengganti pengambilan JavaScript jarak jauh

Fitur ini dimaksudkan untuk digunakan dalam pengujian menyeluruh. Untuk mengganti pengambilan jarak jauh, aplikasi Anda harus berjalan dalam mode debug dengan opsi developer diaktifkan.

Guna mengaktifkan mode debug untuk aplikasi Anda, tambahkan baris berikut ke atribut aplikasi dalam AndroidManifest.xml:

<application
  android:debuggable="true">

Untuk contoh cara menggunakan penggantian ini, lihat aplikasi contoh Protected Audience API di GitHub.

Anda harus menambahkan JavaScript kustom Anda sendiri untuk menangani rutinitas pemilihan iklan, seperti bidding, keputusan skor, dan pelaporan. Anda dapat menemukan contoh kode JavaScript dasar yang menangani semua permintaan yang diperlukan di repo GitHub. Aplikasi contoh Protected Audience API menunjukkan cara membaca kode dari file tersebut dan menyiapkannya untuk digunakan sebagai penggantian.

Anda dapat mengganti pengambilan JavaScript sisi jual dan sisi beli secara terpisah, meskipun Anda memerlukan endpoint HTTPS untuk menayangkan JavaScript apa pun yang tidak diberi penggantian. Lihat README untuk mengetahui informasi tentang cara menyiapkan server yang menangani kasus ini.

Anda hanya dapat mengganti pengambilan JavaScript untuk audiens kustom yang dimiliki oleh paket Anda.

Mengganti JavaScript sisi jual

Untuk menyiapkan penggantian JavaScript sisi jual, lakukan hal berikut seperti yang ditunjukkan dalam contoh kode berikut:

1. Lakukan inisialisasi objek AdSelectionManager.
2. Dapatkan referensi ke TestAdSelectionManager dari objek AdSelectionManager.
3. Buat objek AdSelectionConfig.
4. Buat AddAdSelectionOverrideRequest dengan objek AdSelectionConfig dan String yang mewakili JavaScript yang ingin Anda gunakan sebagai penggantian.
5. Panggil metode overrideAdSelectionConfigRemoteInfo() asinkron dengan objek AddAdSelectionOverrideRequest dan objek Executor dan OutcomeReceiver yang relevan.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

Lihat bagian Menjalankan pemilihan iklan untuk mengetahui informasi selengkapnya tentang apa yang direpresentasikan oleh setiap kolom dalam AdSelectionConfig. Perbedaan utamanya adalah bahwa decisionLogicUrl dapat ditetapkan ke nilai placeholder karena akan diabaikan.

Untuk mengganti JavaScript yang digunakan selama pemilihan iklan, decisionLogicJs harus berisi tanda tangan fungsi sisi penjual yang sesuai. Untuk contoh cara membaca file JavaScript sebagai string, lihat aplikasi contoh Protected Audience API di GitHub.

Metode overrideAdSelectionConfigRemoteInfo() asinkron menggunakan objek OutcomeReceiver untuk memberi sinyal hasil panggilan API.

Callback onResult() menandakan bahwa penggantian berhasil diterapkan. Panggilan ke selectAds() di masa mendatang akan menggunakan logika pengambilan keputusan dan pelaporan yang Anda teruskan sebagai penggantian.

Callback onError() menandakan adanya dua kemungkinan kondisi:

• Jika penggantian dicoba dengan argumen yang tidak valid, AdServiceException akan menunjukkan IllegalArgumentException sebagai penyebabnya.
• Jika penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug dengan opsi developer yang diaktifkan, AdServiceException akan menunjukkan IllegalStateException sebagai penyebabnya.

Mereset penggantian sisi jual

Bagian ini mengasumsikan bahwa Anda telah mengganti JavaScript sisi jual dan memiliki referensi ke TestAdSelectionManager dan AdSelectionConfig yang digunakan di bagian sebelumnya.

Untuk mereset penggantian bagi semua AdSelectionConfigs:

1. Panggil metode resetAllAdSelectionConfigRemoteOverrides() asinkron dengan objek OutcomeReceiver yang relevan.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

Setelah Anda mereset penggantian sisi jual, panggilan ke selectAds() akan menggunakan decisionLogicUrl apa pun yang disimpan di AdSelectionConfig untuk mencoba mengambil JavaScript yang diperlukan.

Jika panggilan ke resetAllAdSelectionConfigRemoteOverrides() gagal, callback OutComeReceiver.onError() akan memberikan AdServiceException. Jika penghapusan penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug dengan opsi developer yang diaktifkan, AdServiceException akan menunjukkan IllegalStateException sebagai penyebabnya.

Mengganti JavaScript sisi beli

1. Ikuti langkah-langkah untuk bergabung dengan audiens kustom
2. Buat AddCustomAudienceOverrideRequest dengan pembeli dan nama audiens kustom yang ingin Anda ganti, selain logika bidding dan data yang ingin Anda gunakan sebagai penggantian
3. Panggil metode overrideCustomAudienceRemoteInfo() asinkron dengan objek AddCustomAudienceOverrideRequest dan objek Executor dan OutcomeReceiver yang relevan

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

Nilai untuk pembeli dan nama adalah nilai yang sama dengan yang digunakan untuk membuat audiens kustom. Pelajari kolom ini lebih lanjut.

Selain itu, Anda dapat menentukan dua parameter tambahan:

• biddingLogicJs: JavaScript yang menyimpan logika pembeli yang digunakan selama pemilihan iklan. Lihat tanda tangan fungsi yang diperlukan dalam JavaScript ini.
• trustedBiddingSignals: Sinyal bidding yang akan digunakan selama pemilihan iklan. Untuk tujuan pengujian, sinyal ini bisa berupa string kosong.

Metode overrideCustomAudienceRemoteInfo() asinkron menggunakan objek OutcomeReceiver untuk memberi sinyal hasil panggilan API.

Callback onResult() menandakan bahwa penggantian berhasil diterapkan. Panggilan berikutnya ke selectAds() akan menggunakan logika bidding dan pelaporan apa pun yang telah Anda teruskan sebagai penggantian.

Callback onError() menandakan adanya dua kemungkinan kondisi.

• Jika penggantian dicoba dengan argumen yang tidak valid, AdServiceException akan menunjukkan IllegalArgumentException sebagai penyebabnya.
• Jika penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug dengan opsi developer yang diaktifkan, AdServiceException akan menunjukkan IllegalStateException sebagai penyebabnya.

Mereset penggantian sisi beli

Bagian ini mengasumsikan bahwa Anda telah mengganti JavaScript sisi beli dan memiliki referensi ke TestCustomAudienceManager dan yang digunakan di bagian sebelumnya.

Untuk mereset penggantian bagi semua audiens kustom:

1. Panggil metode resetAllCustomAudienceOverrides() asinkron dengan objek Executor dan OutcomeReceiver yang relevan.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Setelah Anda mereset penggantian sisi beli, panggilan berikutnya keselectAds() menggunakan biddingLogicUrl dan trustedBiddingData apa pun disimpan di dalam CustomAudience untuk mencoba mengambil JavaScript yang diperlukan.

Jika panggilan ke resetCustomAudienceRemoteInfoOverride() gagal, callback OutComeReceiver.onError() akan memberikan AdServiceException. Jika penghapusan penggantian dicoba dengan aplikasi yang tidak berjalan dalam mode debug dengan opsi developer yang diaktifkan, AdServiceException akan menunjukkan IllegalStateException sebagai penyebabnya.

Menyiapkan Server Pelaporan

Saat menggunakan penggantian pengambilan jarak jauh, Anda masih harus menyiapkan server yang dapat dijangkau oleh perangkat atau emulator untuk merespons peristiwa pelaporan. Endpoint sederhana yang menampilkan 200 sudah cukup untuk pengujian. Repo GitHub mencakup definisi layanan OpenAPI yang dapat di-deploy ke platform tiruan atau microservice yang didukung. Untuk mengetahui detail selengkapnya, lihat README project.

Saat mencari definisi OpenAPI, cari reporting-server.json. File ini berisi endpoint sederhana yang menampilkan 200, yang mewakili kode respons HTTP. Endpoint ini digunakan selama selectAds() dan memberikan sinyal ke Protected Audience API bahwa pelaporan tayangan berhasil diselesaikan.

Fungsi yang akan diuji

• Melakukan praktik saat bergabung atau keluar dan menyiapkan audiens kustom berdasarkan tindakan pengguna sebelumnya.
• Melakukan praktik inisiasi pemilihan iklan di perangkat melalui JavaScript yang dihosting dari jarak jauh.
• Amati bagaimana pengaitan aplikasi dengan setelan audiens kustom dapat memengaruhi hasil pemilihan iklan.
• Melatih pelaporan tayangan setelah pemilihan iklan.

Batasan

Tabel berikut mencantumkan batasan untuk pemrosesan Protected Audience API. Batas yang ditampilkan dapat berubah berdasarkan masukan. Untuk kemampuan yang sedang berlangsung, baca catatan rilis.

Melaporkan bug dan masalah

Masukan Anda adalah bagian penting dari Privacy Sandbox di Android. Beri tahu kami jika Anda menemukan masalah atau memiliki ide untuk meningkatkan kualitas Privacy Sandbox di Android.