Panduan developer FLEDGE di Android

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

FLEDGE di Android mencakup 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 FLEDGE di Android lebih lanjut dalam proposal desain.

Panduan developer ini menjelaskan cara menggunakan FLEDGE di Android untuk melakukan berbagai 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 FLEDGE 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 API selectAds dan reportImpression 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 di atas.

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 parameter owner, buyer, dan name yang cocok. 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.

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 akan dihapus dari perangkat.
• Sinyal bidding pengguna: String JSON yang berisi sinyal pengguna, seperti lokalitas pilihan pengguna, yang akan 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 akan 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.

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 =
    JoinCustomAudienceRequest.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 JoinCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

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

Seperti halnya memanggil joinCustomAudience(), OutcomeReceiver akan menandakan akhir panggilan API. Untuk membantu melindungi privasi, hasil error tidak akan 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 FLEDGE agar dapat 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)
                .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)
                .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. Lihat tanda tangan fungsi yang diperlukan dalam JavaScript ini.
• 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() dari 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.

Setelah iklan dipilih, hasil, bid, dan sinyal akan dipertahankan secara internal untuk pelaporan di lain waktu. Dari callback OutcomeReceiver.onResult(), Anda akan mendapatkan kembali 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.

Melaporkan tayangan iklan

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 AdSelectionConfig serta objek Executor dan OutcomeReceiver yang relevan.

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

// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
        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 pemilihan iklan telah selesai.
• 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.

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 akan menggunakan URL logika bidding yang ditentukan dalam audiens kustom untuk mengambil JavaScript logika bidding pembeli.
• Panggil fungsi JavaScript reportResult() 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 reportWin() yang diharapkan akan menampilkan URL pelaporan tayangan pembeli.

Upaya terbaik Pelaporan tayangan

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

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 akan mengabaikan kolom yang rusak yang akan mengakibatkan tidak ada update pada kolom tertentu 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
        },
        ...
    ]
}

Biasanya pengambilan latar belakang ini terjadi sekali setiap 24 jam. Saat menguji, Anda dapat memicu tugas ini secara manual dengan menjalankan perintah berikut:

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

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()
• reportResult()

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()
• reportWin()

generateBid()

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

Parameter input:

• ad: objek JSON dengan var format berikut ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: Objek JSON, objek ini ditetapkan dalam objek konfigurasi lelang

• custom_audience_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, dan name adalah string yang diambil dari properti dengan nama Audiens Kustom 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. Saat ini 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

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

Pengujian

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

Prasyarat

FLEDGE 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 FLEDGE 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 FLEDGE 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 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 di bawah:

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 FLEDGE 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 FLEDGE 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 FLEDGE. 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.