אימות קריאות חוזרות (callbacks) של אימות בצד השרת (SSV)

קריאות חוזרות (callbacks) במסגרת אימות בצד השרת הן בקשות לכתובות URL, עם פרמטרים של שאילתה שמורחבים על ידי Google, שנשלחות על ידי Google למערכת חיצונית כדי להודיע לה שצריך לתגמל משתמש על אינטראקציה עם מודעה מתגמלת או עם מודעה מתגמלת מסוג מודעה מעברון. קריאות חוזרות (callbacks) של SSV (אימות בצד השרת) עם תגמול מספקות שכבת הגנה נוספת מפני זיוף של קריאות חוזרות בצד הלקוח כדי לתגמל משתמשים.

במדריך הזה מוסבר איך לאמת קריאות חוזרות (callbacks) של SSV עם תגמול באמצעות ספריית הצפנה של צד שלישי, Tink Java Apps, כדי לוודא שפרמטרים של שאילתות בקריאה החוזרת הם ערכים חוקיים. למרות שנעשה שימוש ב-Tink למטרות המדריך הזה, יש לכם אפשרות להשתמש בכל ספרייה של צד שלישי שתומכת ב-ECDSA. אפשר גם לבדוק את השרת באמצעות כלי הבדיקה בממשק המשתמש של AdMob.

כדאי לעיין בדוגמה ל-SSV עם פרסים באמצעות Java spring-boot.

דרישות מוקדמות

• מפעילים את אימות המודעות המתגמלות בצד השרת ביחידת המודעות.

שימוש ב-RewardedAdsVerifier מספריית האפליקציות של Tink ל-Java

המאגר ב-GitHub של Tink Java Apps כולל את הכיתה המסייעת RewardedAdsVerifier כדי לצמצם את הקוד הנדרש לאימות קריאה חוזרת מסוג SSV עם פרס. השימוש בכיתה הזו מאפשר לאמת כתובת URL להודעת חזרה באמצעות הקוד הבא.

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

אם השיטה verify() פועלת בלי להעלות חריגה, המשמעות היא שהכתובת של ה-callback אומתה בהצלחה. בקטע מתן פרסים למשתמשים מפורטות שיטות מומלצות לגבי הזמנים שבהם כדאי לתת למשתמשים פרסים. בקטע אימות ידני של קריאות חוזרות (callbacks) מסוג SSV עם תגמול מפורט פירוט של השלבים שבהם מבצעת הכיתה הזו את האימות של קריאות חוזרות מסוג SSV עם תגמול.

פרמטרים של קריאה חוזרת (callback) של SSV

קריאות חוזרות (callbacks) במסגרת האימות בצד השרת מכילות פרמטרים של שאילתות שמתארים את האינטראקציה של המשתמש עם מודעת הפרסום המניבה תגמול. בהמשך מפורטים השמות, התיאורים והערכים לדוגמה של הפרמטרים. הפרמטרים נשלחים בסדר אלפביתי.

מזהים של מקורות למודעות

מתגמלים את המשתמש

חשוב לאזן בין חוויית המשתמש לבין אימות התגמול כשמחליטים מתי לתגמל משתמש. יכול להיות שיחולו עיכובים לפני שהקריאות החוזרות (callbacks) בצד השרת יגיעו למערכות חיצוניות. לכן, השיטה המומלצת היא להשתמש בקריאה החוזרת (callback) בצד הלקוח כדי לתגמל את המשתמש באופן מיידי, ולבצע אימות של כל התגמולים עם קבלת הקריאות החוזרות בצד השרת. הגישה הזו מספקת חוויית משתמש טובה תוך שמירה על תקינות התגמולים.

עם זאת, באפליקציות שבהן תקינות הפרס קריטית (לדוגמה, הפרס משפיע על הכלכלה במשחק של האפליקציה) ועיכובים במתן הפרסים מקובלים, ייתכן שהגישה הטובה ביותר היא להמתין להודעת החזרה (callback) המאומתת בצד השרת.

נתונים בהתאמה אישית

באפליקציות שדורשות נתונים נוספים בקריאות חוזרות (callbacks) לאימות בצד השרת, צריך להשתמש בתכונה 'נתונים מותאמים אישית' של מודעות מתגמלות. כל ערך מחרוזת שמוגדר באובייקט של מודעה עם תגמול מועבר לפרמטר השאילתה custom_data של קריאה חוזרת (callback) של SSV. אם לא מגדירים ערך נתונים מותאם אישית, ערך פרמטר השאילתה custom_data לא יופיע בקריאה החוזרת של SSV.

בדוגמה הבאה מגדירים את האפשרויות של SSV אחרי הטעינה של המודעה המתגמלת:

RewardedAd.load(MainActivity.this, "AD_UNIT_ID",
    new AdRequest.Builder().build(),  new RewardedAdLoadCallback() {
  @Override
  public void onAdLoaded(RewardedAd ad) {
    Log.d(TAG, "Ad was loaded.");
    rewardedAd = ad;
    ServerSideVerificationOptions options = new ServerSideVerificationOptions
        .Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build();
    rewardedAd.setServerSideVerificationOptions(options);
  }
  @Override
  public void onAdFailedToLoad(LoadAdError loadAdError) {
    Log.d(TAG, loadAdError.toString());
    rewardedAd = null;
  }
});

RewardedAd.load(this, "AD_UNIT_ID",
    AdRequest.Builder().build(), object : RewardedAdLoadCallback() {
  override fun onAdLoaded(ad: RewardedAd) {
    Log.d(TAG, "Ad was loaded.")
    rewardedInterstitialAd = ad
    val options = ServerSideVerificationOptions.Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build()
    rewardedAd.setServerSideVerificationOptions(options)
  }

  override fun onAdFailedToLoad(adError: LoadAdError) {
    Log.d(TAG, adError?.toString())
    rewardedAd = null
  }
})

אם רוצים להגדיר מחרוזת תגמול בהתאמה אישית, צריך לעשות זאת לפני הצגת המודעה.

אימות ידני של מודעות מתגמלות עם מודעות וידאו

בהמשך מפורטים השלבים שבהם מבצעת הכיתה RewardedAdsVerifier את האימות של SSV עם פרס. קטעי הקוד שכלולים כאן הם ב-Java ומשתמשים בספריית הצד השלישי Tink, אבל אפשר להטמיע את השלבים האלה בשפה שבוחרים, באמצעות כל ספריית צד שלישי שתומכת ב-ECDSA.

אחזור מפתחות ציבוריים

כדי לאמת קריאה חוזרת (callback) מסוג SSV עם תגמול, צריך מפתח ציבורי שמסופק על ידי AdMob.

אפשר לאחזר רשימה של מפתחות ציבוריים שישמשו לאימות הקריאות החוזרות (callbacks) של SSV עם תגמול משרת המפתחות של AdMob. רשימת המפתחות הציבוריים מסופקת כמייצג JSON בפורמט דומה לזה:

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

כדי לאחזר את המפתחות הציבוריים, צריך להתחבר לשרת המפתחות של AdMob ולהוריד את המפתחות. הקוד הבא מבצע את המשימה הזו ושומר את הייצוג של המפתחות בפורמט JSON במשתנה 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();
}

חשוב לזכור שמתבצעת רוטציה של מפתחות ציבוריים באופן קבוע. נודיע לכם באימייל על רוטציה קרובה. אם אתם שומרים במטמון מפתחות ציבוריים, עליכם לעדכן את המפתחות לאחר קבלת האימייל הזה.

אחרי שאחזור המפתחות הציבוריים, צריך לנתח אותם. השיטה parsePublicKeysJson שבהמשך מקבלת מחרוזת JSON, כמו הדוגמה שלמעלה, כקלט, ויוצרת מיפוי מערכי key_id למפתחות ציבוריים, שמקובצים כאובייקטים מסוג ECPublicKey מספריית 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;
}

איך מקבלים תוכן לאימות

שני הפרמטרים האחרונים של השאילתה של קריאות חזרה מסוג SSV עם פרסים הם תמיד signature ו-key_id, בסדר הזה. הפרמטרים הנותרים של השאילתה מציינים את התוכן שצריך לאמת. נניח שהגדרתם את AdMob לשלוח קריאות חוזרות לגבי תגמולים אל https://www.myserver.com/mypath. קטע הקוד הבא מציג דוגמה לשיחה חוזרת מסוג SSV עם פרס, כאשר התוכן שצריך לאמת מודגש.

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

הקוד הבא מדגים איך לנתח את התוכן שצריך לאמת מכתובת URL של קריאה חוזרת (callback) כמערך בייטים של 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"));

אחזור החתימה וה-key_id מכתובת ה-URL של הקריאה החוזרת (callback)

בעזרת הערך queryString מהשלב הקודם, מנתחים את פרמטרי השאילתה signature ו-key_id מכתובת ה-URL של הקריאה החוזרת, כפי שמתואר בהמשך:

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

ביצוע האימות

השלב האחרון הוא אימות התוכן של כתובת ה-URL לקריאה חוזרת באמצעות המפתח הציבורי המתאים. לוקחים את המיפוי שהוחזר מהשיטה parsePublicKeysJson ומשתמשים בפרמטר key_id מכתובת ה-URL של קריאת החזרה (callback) כדי לקבל את המפתח הציבורי מהמיפוי הזה. לאחר מכן מאמתים את החתימה באמצעות המפתח הציבורי הזה. השלבים האלה מוצגים בהמשך בשיטה 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);
  }
}

אם השיטה פועלת בלי להפעיל חריג, סימן שכתובת ה-URL לקריאה חוזרת אומתה.

שאלות נפוצות

האם אפשר לשמור במטמון את המפתח הציבורי שסופק על ידי שרת המפתחות של AdMob?

מומלץ לשמור במטמון את המפתח הציבורי שסופק על ידי שרת המפתחות של AdMob כדי לצמצם את מספר הפעולות הנדרשות לאימות קריאות חזרה מסוג SSV. עם זאת, חשוב לזכור שמפתחות ציבוריים עוברים רוטציה באופן קבוע, ואין לשמור אותם במטמון למשך יותר מ-24 שעות.

באיזו תדירות מתבצעת רוטציה של המפתחות הציבוריים שסופקו על ידי שרת המפתחות של AdMob?

הרוטציה של המפתחות הציבוריים שסופקו על ידי שרת המפתחות של AdMob מתבצעת לפי לוח זמנים משתנה. כדי לוודא שהאימות של קריאות החזרה (callbacks) של SSV ימשיך לפעול כמצופה, אסור לשמור במטמון מפתחות ציבוריים למשך יותר מ-24 שעות.

מה קורה אם לא ניתן לגשת לשרת?

Google מצפה לקוד תגובה עם סטטוס הצלחה HTTP 200 OK בקריאות חזרה של SSV. אם אי אפשר ליצור קשר עם השרת או שהוא לא מספק את התשובה הצפויה, Google תנסה שוב לשלוח קריאות חזרה מסוג SSV עד חמש פעמים במרווחי זמן של שנייה אחת.

איך אפשר לוודא שהשיחות החוזרות של SSV מגיעות מ-Google?

משתמשים בשאילתת DNS הפוכה כדי לוודא שההחזרות של קריאות SSV מגיעות מ-Google.