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

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

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

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

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

שימוש ב-RewardedAdsVerifier מספריית Tink Java Apps

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

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

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

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

תגמול המשתמש

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

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

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

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

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

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

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

אימות ידני של אימות בצד השרת לצפייה במודעות מתגמלות

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

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

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

אפשר לאחזר רשימה של מפתחות ציבוריים שמשמשים לאימות הקריאות החוזרות (callback) של אימות בצד השרת (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;
}

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

שני הפרמטרים האחרונים של שאילתות בקריאות חוזרות (callback) של SSV עם תגמול הם תמיד signature ו-key_id,, בסדר הזה. בשאר הפרמטרים של השאילתה מצוין התוכן שצריך לאמת. נניח שהגדרתם את AdMob לשליחת קריאות חוזרות (callback) על תגמולים אל https://www.myserver.com/mypath. קטע הקוד שלמטה מציג דוגמה לקריאה חוזרת (callback) של 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 של קריאה חוזרת כמערך בייטים בקידוד 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 לקריאה חוזרת (callback) באמצעות המפתח הציבורי המתאים. לוקחים את המיפוי שמוחזר מהשיטה parsePublicKeysJson ומשתמשים בפרמטר key_id מכתובת ה-URL של הקריאה החוזרת כדי לקבל את המפתח הציבורי מהמיפוי הזה. לאחר מכן מאמתים את החתימה באמצעות המפתח הציבורי הזה. השלבים האלה מודגמים בהמשך בשיטה 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 לקריאה חוזרת (callback) אומתה בהצלחה.

שאלות נפוצות

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

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

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

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

מה קורה אם אי אפשר להגיע לשרת שלי?

‫

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

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

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