ตรวจสอบโค้ดเรียกกลับการยืนยันฝั่งเซิร์ฟเวอร์ (SSV)

Server-side verification callbacks are URL requests, with query parameters expanded by Google, that are sent by Google to an external system to notify it that a user should be rewarded for interacting with a rewarded or rewarded interstitial ad. Rewarded SSV (server-side verification) callbacks provide an extra layer of protection against spoofing of client-side callbacks to reward users.

This guide shows you how to verify rewarded SSV callbacks by using the Tink Java Apps third-party cryptographic library to ensure that the query parameters in the callback are legitimate values. Although Tink is used for the purposes of this guide, you have the option to use any third-party library that supports ECDSA. You can also test your server with the testing tool in the AdMob UI.

Check out this fully working example using Java spring-boot.

Prerequisites

Use RewardedAdsVerifier from the Tink Java Apps library

The Tink Java Apps GitHub repository includes a RewardedAdsVerifier helper class to reduce the code required to verify a rewarded SSV callback. Using this class enables you to verify a callback URL with the following code.

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

If the verify() method executes without raising an exception, the callback URL was successfully verified. The Rewarding the user section details best practices regarding when users should be rewarded. For a breakdown of the steps performed by this class to verify rewarded SSV callbacks, you can read through the Manual verification of rewarded SSV section.

SSV callback parameters

Server-side verification callbacks contain query parameters that describe the rewarded ad interaction. Parameter names, descriptions, and example values are listed below. Parameters are sent in alphabetical order.

Parameter Name Description Example value
ad_network Ad source identifier for the ad source that fulfilled this ad. Ad source names corresponding to ID values are listed in the Ad source identifiers section. 1953547073528090325
ad_unit AdMob ad unit ID that was used to request the rewarded ad. 2747237135
custom_data Custom data string as provided by customRewardString .

If no custom data string is provided by the app, this query parameter value will not be present in the SSV callback.

SAMPLE_CUSTOM_DATA_STRING
key_id Key to be used to verify SSV callback. This value maps to a public key provided by the AdMob key server. 1234567890
reward_amount Reward amount as specified in the ad unit settings. 5
reward_item Reward item as specified in the ad unit settings. coins
signature Signature for SSV callback generated by AdMob. MEUCIQCLJS_s4ia_sN06HqzeW7Wc3nhZi4RlW3qV0oO-6AIYdQIgGJEh-rzKreO-paNDbSCzWGMtmgJHYYW9k2_icM9LFMY
timestamp Timestamp of when the user was rewarded as Epoch time in ms. 1507770365237823
transaction_id Unique hex encoded identifier for each reward grant event generated by AdMob. 18fa792de1bca816048293fc71035638
user_id User identifier as provided by userIdentifier.

If no user identifier is provided by the app, this query parameter will not be present in the SSV callback.

1234567

Ad source identifiers

Ad source names and IDs

ชื่อแหล่งที่มาของโฆษณา รหัสแหล่งที่มาของโฆษณา
อาร์คี (การเสนอราคา)5240798063227064260
การสร้างโฆษณา (การเสนอราคา)1477265452970951479
AdColony15586990674969969776
AdColony (ไม่ใช่ SDK) (การเสนอราคา)4600416542059544716
AdColony (การเสนอราคา)6895345910719072481
AdFalcon3528208921554210682
เครือข่าย AdMob5450213213286189855
Waterfall เครือข่าย AdMob1215381445328257950
ADResult10593873382626181482
AMoAd17253994435944008978
แอปโลวิน1063618907739174004
แอปโลวิน (การเสนอราคา)1328079684332308356
Chartboost2873236629771172317
แพลตฟอร์มช็อกโกแลต (การเสนอราคา)6432849193975106527
CrossChannel (MdotM)9372067028804390441
เหตุการณ์ที่กำหนดเอง18351550913290782395
DT Exchange*
* ก่อนวันที่ 21 กันยายน 2022 เครือข่ายนี้มีชื่อว่า "Fyber Marketplace"
2179455223494392917
EMX (การเสนอราคา)8497809869790333482
ผันผวน (การเสนอราคา)8419777862490735710
Flurry3376427960656545613
Fyber*
* แหล่งที่มาของโฆษณานี้ใช้สำหรับการรายงานข้อมูลย้อนหลัง
4839637394546996422
i-mobile5208827440166355534
ปรับปรุงโฆษณาดิจิทัล (การเสนอราคา)159382223051638006
Index Exchange (การเสนอราคา)4100650709078789802
InMobi7681903010231960328
InMobi (การเสนอราคา)6325663098072678541
InMobi Exchange (การเสนอราคา)5264320421916134407
IronSource6925240245545091930
โฆษณา ironSource (การเสนอราคา)1643326773739866623
Leadbolt2899150749497968595
LG U+AD18298738678491729107
เครือข่ายโฆษณา LINE3025503711505004547
Maio7505118203095108657
Maio (การเสนอราคา)1343336733822567166
Media.net (การเสนอราคา)2127936450554446159
โฆษณาเฮาส์แอ็ดที่ใช้สื่อกลาง6060308706800320801
Meta Audience Network*
* ก่อนวันที่ 6 มิถุนายน 2022 เครือข่ายนี้มีชื่อว่า "Facebook Audience Network"
10568273599589928883
Meta Audience Network (การเสนอราคา)*
* ก่อนวันที่ 6 มิถุนายน 2022 เครือข่ายนี้มีชื่อว่า "Facebook Audience Network (การเสนอราคา)"
11198165126854996598
Mintegral1357746574408896200
Mintegral (การเสนอราคา)6250601289653372374
MobFox8079529624516381459
MobFox (การเสนอราคา)3086513548163922365
MoPub (เลิกใช้งานแล้ว)10872986198578383917
myTarget8450873672465271579
Nend9383070032774777750
Nexxen (การเสนอราคา)*

* ก่อนวันที่ 1 พฤษภาคม 2024 เครือข่ายนี้มีชื่อว่า "UnrulyX"

2831998725945605450
ONE by AOL (Millennial Media)6101072188699264581
ONE by AOL (Nexage)3224789793037044399
การแลกเปลี่ยน OneTag (การเสนอราคา)4873891452523427499
OpenX (การเสนอราคา)4918705482605678398
แพลงก์4069896914521993236
Pangle (การเสนอราคา)3525379893916449117
PubMatic (การเสนอราคา)3841544486172445473
แคมเปญแบบจองล่วงหน้า7068401028668408324
RhythmOne (การเสนอราคา)2831998725945605450
Rubicon (การเสนอราคา)3993193775968767067
ดาวเคราะห์ SK734341340207269415
ส่วนแบ่งผ่าน (การเสนอราคา)5247944089976324188
Smaato (การเสนอราคา)3362360112145450544
Equativ (การเสนอราคา)*

* ก่อนวันที่ 12 มกราคม 2023 เครือข่ายนี้มีชื่อว่า "Smart Adserver"

5970199210771591442
Sonobi (การเสนอราคา)3270984106996027150
Tapjoy7295217276740746030
TapJoy (การเสนอราคา)4692500501762622178
Tencent GDT7007906637038700218
TripleLift (การเสนอราคา)8332676245392738510
โฆษณา Unity4970775877303683148
โฆษณา Unity (การเสนอราคา)7069338991535737586
สื่อ Verizon7360851262951344112
กลุ่ม Verve (การเสนอราคา)5013176581647059185
Vpon1940957084538325905
Liftoff Monetize*

* ก่อนวันที่ 30 มกราคม 2023 เครือข่ายนี้มีชื่อว่า "Vungle"

1953547073528090325
Liftoff Monetize (การเสนอราคา)*

* ก่อนวันที่ 30 มกราคม 2023 เครือข่ายนี้มีชื่อว่า "Vungle (การเสนอราคา)"

4692500501762622185
Yieldmo (การเสนอราคา)4193081836471107579
YieldOne (การเสนอราคา)3154533971590234104
ซุค5506531810221735863

Rewarding the user

It is important to balance user experience and reward validation when deciding when to reward a user. Server-side callbacks may experience delays before reaching external systems. Therefore, the recommended best practice is to use the client-side callback to reward the user immediately, while performing validation on all rewards upon the receipt of server-side callbacks. This approach provides a good user experience while ensuring the validity of granted rewards.

However, for applications where reward validity is critical (for example, the reward affects your app's in-game economy) and delays in granting rewards are acceptable, waiting for the verified server-side callback may be the best approach.

Custom data

Apps that require extra data in server-side verification callbacks should use the custom data feature of rewarded ads. Any string value set on a rewarded ad object is passed to the custom_data query parameter of the SSV callback. If no custom data value is set, the custom_data query parameter value won't be present in the SSV callback.

The following code sample demonstrates how to set the SSV options after the rewarded ad is loaded.

Swift

GADRewardedAd.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedAd = ad
      let options = GADServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedAd.serverSideVerificationOptions = options
    }

Objective-C

GADRequest *request = [GADRequest request];
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                        request:request
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  // Handle Error
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];

Manual verification of rewarded SSV

The steps performed by the RewardedAdsVerifier class to verify a rewarded SSV are outlined below. Although the included code snippets are in Java and leverage the Tink third-party library, these steps can be implemented by you in the language of your choice, using any third-party library that supports ECDSA.

Fetch public keys

To verify a rewarded SSV callback, you need a public key provided by AdMob.

A list of public keys to be used to validate the rewarded SSV callbacks can be fetched from the AdMob key server. The list of public keys is provided as a JSON representation with a format similar to the following:

{
 "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=="
    },
  ],
}

To retrieve the public keys, connect to the AdMob key server and download the keys. The following code accomplishes this task and saves the JSON representation of the keys to the data variable.

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();
}

Note that public keys are regularly rotated. You will receive an email to inform you of an upcoming rotation. If you're caching public keys, you should update the keys upon receiving this email.

Once the public keys have been fetched, they must be parsed. The parsePublicKeysJson method below takes a JSON string, such as the example above, as input, and creates a mapping from key_id values to public keys, which are encapsulated as ECPublicKey objects from the Tink library.

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;
}

Get content to be verified

The last two query parameters of rewarded SSV callbacks are always signature and key_id, in that order. The remaining query parameters specify the content to be verified. Let's assume you configured AdMob to send reward callbacks to https://www.myserver.com/mypath. The snippet below shows an example rewarded SSV callback with the content to be verified highlighted.

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

The code below demonstrates how to parse the content to be verified from a callback URL as a UTF-8 byte array.

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

Get signature and key_id from callback URL

Using the queryString value from the previous step, parse the signature and key_id query parameters from the callback URL as shown below:

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

Perform verification

The final step is to verify the content of the callback URL with the appropriate public key. Take the mapping returned from the parsePublicKeysJson method and use the key_id parameter from the callback URL to get the public key from that mapping. Then verify the signature with that public key. These steps are demonstrated below in the verify method.

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

If the method executes without throwing an exception, the callback URL was successfully verified.

FAQ

Can I cache the public key provided by the AdMob key server?
We recommend that you cache the public key provided by the AdMob key server to reduce the number of operations required to validate SSV callbacks. However, note that public keys are regularly rotated and should not be cached for longer than 24 hours.
How frequently are the public keys provided by the AdMob key server rotated?
Public keys provided by the AdMob key server are rotated on a variable schedule. To ensure that verification of SSV callbacks continues to work as intended, public keys should not be cached for longer than 24 hours.
What happens if my server can't be reached?
Google expects an HTTP 200 OK success status response code for SSV callbacks. If your server cannot be reached or does not provide the expected response, Google will re-attempt to send SSV callbacks up to five times in one-second intervals.
How can I verify that SSV callbacks are coming from Google?
Use reverse DNS lookup to verify that SSV callbacks originate from Google.