Membuat adaptor sinyal aman

Penting: Sinyal aman masih dalam versi beta. Dokumen ini hanya ditujukan untuk partner tertentu. Jangan mendistribusikan dokumen ini tanpa izin dari Google.

Sinyal aman adalah data yang dienkode yang dikumpulkan dan dibagikan oleh perangkat klien kepada bidder tertentu. Halaman ini memandu Anda mengumpulkan dan mengirim sinyal aman ke Google Ad Manager menggunakan Interactive Media Ads (IMA) SDK.

Sebelum memulai

Sebelum melanjutkan, pastikan Anda memiliki IMA SDK untuk Android v3.29.0 atau yang lebih tinggi.

Membuat antarmuka adaptor sinyal aman

Untuk mengumpulkan dan memberikan sinyal yang aman, buat class yang mengimplementasikan antarmuka:

Catatan: IMA SDK memuat class adaptor Anda menggunakan refleksi. Untuk mencegah penghapusan kode yang diminifikasi pada waktu build, tambahkan anotasi Android @Keep ke class Anda.

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
}

Melakukan inisialisasi adaptor

IMA SDK melakukan inisialisasi setiap adaptor satu kali dengan memanggil metode inisialisasi adaptor. Terapkan metode ini untuk memulai dependensi enkripsi, menyiapkan cache, atau melakukan pra-penghitungan sinyal apa pun yang tetap sama di semua panggilan pengumpulan sinyal.

Contoh berikut menginisialisasi adaptor:

  ...
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    // Initialize your SDK and any dependencies.
    ...

    // Notify IMA SDK of initialization success.
    callback.onSuccess();

    // If signal collection fails, call callback.onFailure();
    // callback.onFailure(new Exception("Signal collection failed."));
  }
  ...

Pengumpulan sinyal

Sebelum permintaan iklan dimulai, IMA SDK memanggil metode pengumpulan sinyal secara asinkron. Metode pengumpul sinyal ini berisi fungsi callback untuk meneruskan sinyal terenkripsi atau melaporkan error.

Catatan: Dalam waktu 500 milidetik, Anda harus menyelesaikan pengumpulan sinyal, enkripsi, dan meneruskan sinyal terenkripsi ke fungsi callback. Setelah 500 milidetik, IMA SDK akan menghapus semua pengumpulan sinyal.

Contoh berikut mengumpulkan sinyal aman melalui fungsi callback:

  ...
  /**
   * Invokes your SDK to collect, encrypt and pass the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {

    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  ...

Melaporkan error

Untuk berkomunikasi dengan pengguna yang menggunakan class adaptor Anda, laporkan semua error selama pengumpulan sinyal dan teruskan ke callback pengumpulan sinyal. Proses ini memecahkan masalah yang terjadi selama integrasi adaptor ke aplikasi.

Error yang mungkin muncul adalah sebagai berikut:

• SDK atau dependensi tidak ditemukan dalam aplikasi.
• SDK atau dependensi tidak memiliki izin yang diperlukan atau izin pengguna untuk berfungsi.

Menentukan versi adaptor

Dalam alur kerja, pastikan Anda menetapkan versi adaptor. IMA SDK menyertakan versi adaptor Anda di setiap permintaan iklan dan meneruskannya dengan sinyal aman dalam permintaan bid.

Dalam permintaan bid, berdasarkan versi adaptor, Anda dapat mengidentifikasi detail enkripsi, encoding, dan pemformatan yang digunakan adaptor untuk membuat sinyal aman.

Contoh berikut menentukan versi adaptor:

  ...
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  ...
  /**
   * @return The version of this adapter.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  ...

Menampilkan versi runtime SDK

Anda dapat mendesain adaptor agar berfungsi dengan beberapa versi SDK. Agar adaptor berfungsi dengan beberapa versi, pastikan Anda menampilkan versi runtime SDK. Dalam setiap permintaan iklan, IMA SDK menyertakan versi runtime dengan versi adaptor.

Contoh berikut meminta dan menampilkan versi runtime SDK:

  ...
  /**
   * @return The version of your SDK that this adapter is depending on.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;

    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
  ...

Daftarkan adaptor ke Google

Agar Google dapat mengizinkan adaptor pengumpulan sinyal, Anda harus mendaftarkan nama paket Android atau ke Google. IMA SDK hanya melakukan inisialisasi pada adaptor yang Anda daftarkan ke Google.

Memvalidasi adaptor

Untuk memvalidasi adaptor, selesaikan bagian berikut:

Mengonfigurasi aplikasi pengujian

Sebelum memvalidasi adaptor, konfigurasikan aplikasi pengujian. Selesaikan langkah-langkah berikut:

1. Tambahkan dependensi untuk IMA SDK ke file Gradle level aplikasi modul Anda, seperti app/build.gradle:

   dependencies {
     implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
   }
   

2. Tambahkan dependensi build seperti adaptor dan SDK.

Memverifikasi sinyal

Untuk memverifikasi bahwa adaptor Anda mengirim sinyal, gunakan proxy jaringan untuk memantau traffic permintaan iklan aplikasi Anda. Jika berhasil, Anda akan melihat sinyal di setiap permintaan iklan.

Meninjau contoh lengkap

Bagian ini berisi contoh lengkap dari semua langkah dan tersedia untuk referensi Anda.

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.VersionInfo;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsCollectSignalsCallback;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsInitializeCallback;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    try {
      // Initialize your SDK and any dependencies.
      ...

      // Notify IMA SDK of initialization success.
      callback.onSuccess();
    } catch (Exception e) {
      // Pass initialization failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * Invokes your SDK to collect, encrypt and send the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {
    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * @return The version of this adapter.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  /**
   * @return The version of your SDK that this adapter is depending on.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;
    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
}