Memvalidasi callback verifikasi sisi server (SSV)

Callback verifikasi sisi server adalah permintaan URL, dengan parameter kueri yang diperluas oleh Google, yang dikirim oleh Google ke sistem eksternal untuk memberi tahu bahwa pengguna harus diberi reward karena berinteraksi dengan iklan interstisial reward atau iklan interstisial reward. Callback SSV (verifikasi sisi server) reward memberikan lapisan perlindungan tambahan terhadap pemalsuan callback sisi klien untuk memberi reward kepada pengguna.

Panduan ini menunjukkan cara memverifikasi callback SSV yang diberi reward menggunakan library kriptografi pihak ketiga Tink Java Apps untuk memastikan bahwa parameter kueri dalam callback adalah nilai yang sah. Meskipun Tink digunakan untuk tujuan panduan ini, Anda memiliki opsi untuk menggunakan library pihak ketiga yang mendukung ECDSA. Anda juga dapat menguji server dengan alat pengujian di UI AdMob.

Prasyarat

• Aktifkan verifikasi sisi server iklan reward di unit iklan Anda.

Menggunakan RewardedAdsVerifier dari library Aplikasi Java Tink

Repositori GitHub Tink Java Apps menyertakan class helper RewardedAdsVerifier untuk mengurangi kode yang diperlukan guna memverifikasi callback SSV yang diberi reward. Dengan menggunakan class ini, Anda dapat memverifikasi URL callback dengan kode berikut.

RewardedAdsVerifier verifier = new RewardedAdsVerifier.Builder()
    .fetchVerifyingPublicKeysWith(
        RewardedAdsVerifier.KEYS_DOWNLOADER_INSTANCE_PROD)
    .build();
String rewardUrl = ...;
verifier.verify(rewardUrl);

Jika metode verify() dieksekusi tanpa memunculkan pengecualian, URL callback berhasil diverifikasi. Bagian Memberi penghargaan kepada pengguna menjelaskan praktik terbaik terkait kapan pengguna harus diberi penghargaan. Untuk mengetahui perincian langkah-langkah yang dilakukan oleh class ini untuk memverifikasi callback SSV reward, Anda dapat membaca bagian Verifikasi manual SSV reward.

Parameter callback SSV

Callback verifikasi sisi server berisi parameter kueri yang mendeskripsikan interaksi iklan reward. Nama parameter, deskripsi, dan contoh nilai tercantum di bawah. Parameter dikirim dalam urutan abjad.

ID sumber iklan

Memberi reward kepada pengguna

Penting untuk menyeimbangkan pengalaman pengguna dan validasi reward saat memutuskan kapan harus memberikan reward kepada pengguna. Callback sisi server mungkin mengalami penundaan sebelum mencapai sistem eksternal. Oleh karena itu, praktik terbaik yang direkomendasikan adalah menggunakan callback sisi klien untuk langsung memberikan reward kepada pengguna, sekaligus melakukan validasi pada semua reward setelah menerima callback sisi server. Pendekatan ini memberikan pengalaman pengguna yang baik sekaligus memastikan validitas reward yang diberikan.

Namun, untuk aplikasi yang validitas rewardnya sangat penting (misalnya, reward memengaruhi ekonomi dalam game aplikasi Anda) dan penundaan pemberian reward dapat diterima, menunggu callback sisi server yang terverifikasi mungkin merupakan pendekatan terbaik.

Data kustom

Aplikasi yang memerlukan data tambahan dalam callback verifikasi sisi server harus menggunakan fitur data kustom iklan reward. Nilai string apa pun yang ditetapkan pada objek iklan bersedia ditonton akan diteruskan ke parameter kueri custom_data dari callback SSV. Jika tidak ada nilai data kustom yang ditetapkan, nilai parameter kueri custom_data tidak akan ada dalam callback SSV.

Contoh kode berikut menunjukkan cara menyetel data kustom pada objek iklan reward sebelum meminta iklan.

  firebase::gma::RewardedAd* rewarded_ad;
  rewarded_ad = new firebase::gma::RewardedAd();

  firebase::gma::RewardedAd::ServerSideVerificationOptions options;
  options.custom_data = "SAMPLE_CUSTOM_DATA_STRING";
  rewarded_ad->SetServerSideVerificationOptions(options);

Jika ingin menetapkan string reward kustom, Anda harus melakukannya sebelum menampilkan iklan.

Verifikasi manual SSV reward

Langkah-langkah yang dilakukan oleh class RewardedAdsVerifier untuk memverifikasi SSV reward diuraikan di bawah. Meskipun cuplikan kode yang disertakan ada di Java dan memanfaatkan library pihak ketiga Tink, langkah-langkah ini dapat diterapkan oleh Anda dalam bahasa pilihan Anda, menggunakan library pihak ketiga yang mendukung ECDSA.

Mengambil kunci publik

Untuk memverifikasi callback SSV yang diberi reward, Anda memerlukan kunci publik yang disediakan oleh AdMob.

Daftar kunci publik yang akan digunakan untuk memvalidasi callback SSV yang diberi reward dapat diambil dari server kunci AdMob. Daftar kunci publik diberikan sebagai representasi JSON dengan format yang mirip dengan berikut:

{
 "keys": [
    {
      keyId: 1916455855,
      pem: "-----BEGIN PUBLIC KEY-----\nMF...YTPcw==\n-----END PUBLIC KEY-----"
      base64: "MFkwEwYHKoZIzj0CAQYI...ltS4nzc9yjmhgVQOlmSS6unqvN9t8sqajRTPcw=="
    },
    {
      keyId: 3901585526,
      pem: "-----BEGIN PUBLIC KEY-----\nMF...aDUsw==\n-----END PUBLIC KEY-----"
      base64: "MFYwEAYHKoZIzj0CAQYF...4akdWbWDCUrMMGIV27/3/e7UuKSEonjGvaDUsw=="
    },
  ],
}

Untuk mengambil kunci publik, hubungkan ke server kunci AdMob dan download kunci. Kode berikut menyelesaikan tugas ini dan menyimpan representasi JSON kunci ke variabel data.

String url = ...;
NetHttpTransport httpTransport = new NetHttpTransport.Builder().build();
HttpRequest httpRequest =
    httpTransport.createRequestFactory().buildGetRequest(new GenericUrl(url));
HttpResponse httpResponse = httpRequest.execute();
if (httpResponse.getStatusCode() != HttpStatusCodes.STATUS_CODE_OK) {
  throw new IOException("Unexpected status code = " + httpResponse.getStatusCode());
}
String data;
InputStream contentStream = httpResponse.getContent();
try {
  InputStreamReader reader = new InputStreamReader(contentStream, UTF_8);
  data = readerToString(reader);
} finally {
  contentStream.close();
}

Perhatikan bahwa kunci publik dirotasi secara rutin. Anda akan menerima email untuk memberi tahu Anda tentang rotasi yang akan datang. Jika Anda menyimpan kunci publik dalam cache, Anda harus memperbarui kunci tersebut setelah menerima email ini.

Setelah diambil, kunci publik harus diuraikan. Metode parsePublicKeysJson di bawah menggunakan string JSON, seperti contoh di atas, sebagai input, dan membuat pemetaan dari nilai key_id ke kunci publik, yang dienkapsulasi sebagai objek ECPublicKey dari library Tink.

private static Map<Integer, ECPublicKey> parsePublicKeysJson(String publicKeysJson)
    throws GeneralSecurityException {
  Map<Integer, ECPublicKey> publicKeys = new HashMap<>();
  try {
    JSONArray keys = new JSONObject(publicKeysJson).getJSONArray("keys");
    for (int i = 0; i < keys.length(); i++) {
      JSONObject key = keys.getJSONObject(i);
      publicKeys.put(
          key.getInt("keyId"),
          EllipticCurves.getEcPublicKey(Base64.decode(key.getString("base64"))));
    }
  } catch (JSONException e) {
    throw new GeneralSecurityException("failed to extract trusted signing public keys", e);
  }
  if (publicKeys.isEmpty()) {
    throw new GeneralSecurityException("No trusted keys are available.");
  }
  return publicKeys;
}

Mendapatkan konten yang akan diverifikasi

Dua parameter kueri terakhir dari callback SSV reward selalu signature dan key_id, dalam urutan tersebut. Parameter kueri yang tersisa menentukan konten yang akan diverifikasi. Misalkan Anda mengonfigurasi AdMob untuk mengirim callback reward ke https://www.myserver.com/mypath. Cuplikan di bawah menampilkan contoh callback SSV reward dengan konten yang akan diverifikasi ditandai.

https://www.myserver.com/path?ad_network=54...55&ad_unit=12345678&reward_amount=10&reward_item=coins
&timestamp=150777823&transaction_id=12...DEF&user_id=1234567&signature=ME...Z1c&key_id=1268887

Kode di bawah menunjukkan cara mem-parsing konten yang akan diverifikasi dari URL panggilan balik sebagai array byte UTF-8.

public static final String SIGNATURE_PARAM_NAME = "signature=";
...
URI uri;
try {
  uri = new URI(rewardUrl);
} catch (URISyntaxException ex) {
  throw new GeneralSecurityException(ex);
}
String queryString = uri.getQuery();
int i = queryString.indexOf(SIGNATURE_PARAM_NAME);
if (i == -1) {
  throw new GeneralSecurityException("needs a signature query parameter");
}
byte[] queryParamContentData =
    queryString
        .substring(0, i - 1)
        // i - 1 instead of i because of & in the query string
        .getBytes(Charset.forName("UTF-8"));

Mendapatkan tanda tangan dan key_id dari URL callback

Dengan menggunakan nilai queryString dari langkah sebelumnya, parsing parameter kueri signature dan key_id dari URL callback seperti yang ditunjukkan di bawah ini:

public static final String KEY_ID_PARAM_NAME = "key_id=";
...
String sigAndKeyId = queryString.substring(i);
i = sigAndKeyId.indexOf(KEY_ID_PARAM_NAME);
if (i == -1) {
  throw new GeneralSecurityException("needs a key_id query parameter");
}
String sig =
    sigAndKeyId.substring(
        SIGNATURE_PARAM_NAME.length(), i - 1 /* i - 1 instead of i because of & */);
int keyId = Integer.valueOf(sigAndKeyId.substring(i + KEY_ID_PARAM_NAME.length()));

Lakukan verifikasi

Langkah terakhir adalah memverifikasi konten URL callback dengan kunci publik yang sesuai. Ambil pemetaan yang ditampilkan dari metode parsePublicKeysJson dan gunakan parameter key_id dari URL callback untuk mendapatkan kunci publik dari pemetaan tersebut. Kemudian, verifikasi tanda tangan dengan kunci publik tersebut. Langkah-langkah ini ditunjukkan di bawah dalam metode verify.

private void verify(final byte[] dataToVerify, int keyId, final byte[] signature)
    throws GeneralSecurityException {
  Map<Integer, ECPublicKey> publicKeys = parsePublicKeysJson();
  if (publicKeys.containsKey(keyId)) {
    foundKeyId = true;
    ECPublicKey publicKey = publicKeys.get(keyId);
    EcdsaVerifyJce verifier = new EcdsaVerifyJce(publicKey, HashType.SHA256, EcdsaEncoding.DER);
    verifier.verify(signature, dataToVerify);
  } else {
    throw new GeneralSecurityException("cannot find verifying key with key ID: " + keyId);
  }
}

Jika metode dijalankan tanpa menampilkan pengecualian, URL callback telah berhasil diverifikasi.

FAQ

Dapatkah saya menyimpan dalam cache kunci publik yang disediakan oleh server kunci AdMob?

Sebaiknya Anda meng-cache kunci publik yang disediakan oleh server kunci AdMob untuk mengurangi jumlah operasi yang diperlukan untuk memvalidasi callback SSV. Namun, perhatikan bahwa kunci publik dirotasi secara rutin dan tidak boleh di-cache lebih dari 24 jam.

Seberapa sering kunci publik yang disediakan oleh server kunci AdMob dirotasi?

Kunci publik yang disediakan oleh server kunci AdMob dirotasi menurut jadwal yang bervariasi. Untuk memastikan bahwa verifikasi callback SSV terus berfungsi sebagaimana mestinya, kunci publik tidak boleh di-cache selama lebih dari 24 jam.

Apa yang terjadi jika server saya tidak dapat dijangkau?

Google mengharapkan kode respons status berhasil HTTP 200 OK untuk callback SSV. Jika server Anda tidak dapat dijangkau atau tidak memberikan respons yang diharapkan, Google akan mencoba lagi mengirimkan callback SSV hingga lima kali dalam interval satu detik.

Bagaimana cara memverifikasi bahwa panggilan balik SSV berasal dari Google?

Gunakan pencarian DNS terbalik untuk memverifikasi bahwa panggilan balik SSV berasal dari Google.