Menentukan data audiens

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.

Android Protected Audience API dapat digunakan untuk bergabung dan keluar dari audiens kustom di perangkat pengguna. Saat membuat dan bergabung dengan audiens kustom, Anda dapat mendelegasikan ke server tempat Anda akan mengambil beberapa atau semua properti audiens kustom, atau Anda dapat menentukan informasi ini saat memanggil API secara langsung.

Audiens kustom

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.

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

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.

Mengambil dan bergabung dengan audiens kustom

fetchAndJoinCustomAudience API memungkinkan pembeli mendelegasikan cara bergabung dengan audiens kustom dengan memanfaatkan kehadiran MMP atau SSP partner di perangkat.

Agar berfungsi, pemanggil di perangkat (baik itu MMP atau SSP SDK) akan membuat fetchAndJoinCustomAudienceRequest yang terlihat seperti berikut:

KotlinJava
/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

Catatan penting tentang semua parameter opsional adalah jika parameter tersebut ditetapkan di dalam permintaan pengambilan, data mereka tidak dapat diganti oleh parameter yang ditampilkan dari Pembeli, sehingga memberikan kontrol tambahan kepada pemanggil di perangkat atas apa audiens kustom dipertahankan.

fetchUri harus mengarah ke endpoint server yang dioperasikan oleh Pembeli yang akan menampilkan objek JSON Audiens Kustom yang cocok dengan format yang terlihat di sini:

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

Informasi selengkapnya tentang cara menyelesaikan masalah di sisi API dapat ditemukan dalam Proposal Desain untuk Bergabung dengan Delegasi CA.

Pengujian

Setelah menerapkan panggilan Ambil di dalam kode klien dan menyiapkan endpoint di sisi DSP untuk menampilkan Data Audiens Kustom, Anda dapat menguji delegasi untuk bergabung dengan Audiens Kustom. Sebelum menjalankan aplikasi, Anda harus menjalankan perintah di halaman Penyiapan pengujian. Setelah menjalankan perintah ini, seharusnya Anda dapat mulai berhasil melakukan panggilan menggunakan Fetch API.

Untuk melihat contoh alur ini, panggilan pengambilan telah ditambahkan ke repositori Contoh Privacy Sandbox di GitHub.

Bergabung langsung dengan audiens kustom

Jika sudah memiliki semua informasi yang diperlukan untuk membuat dan bergabung dengan audiens kustom, Anda dapat melakukannya secara langsung menggunakan panggilan Protected Audience API asinkron. Untuk membuat atau bergabung dengan audiens kustom secara langsung, 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.
KotlinJava
val customAudienceManager: CustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java)

// Minimal initialization of a CustomAudience object
val audience: 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()

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

// Minimal initialization of a CustomAudience object
CustomAudience audience = 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();

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

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

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.

Berikut adalah contoh penanganan hasil joinCustomAudience():

KotlinJava
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 langsung dengan audiens kustom".
  3. Panggil metode leaveCustomAudience() asinkron dengan objek LeaveCustomAudienceRequest serta objek Executor dan OutcomeReceiver yang relevan.
KotlinJava
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.