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

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

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

רוצה לראות איך זה עובד? דוגמה באמצעות Spring-boot.

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

• שילוב מודעות מתגמלות אפליקציה לנייד עם גרסה 11.6.0 ואילך של Google Mobile Ads SDK.

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

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

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

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

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

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

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

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

תגמול למשתמשים

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

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

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

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

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

RewardedAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379",
    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, "ca-app-pub-3940256099942544/5354046379",
    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
  }
})

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

אימות ידני של אימות דו-שלבי (SSV) מתגמל

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

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

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

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

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

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

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

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

אם ה-method פועלת מבלי להקפיץ הודעת שגיאה, כתובת ה-URL של הקריאה החוזרת (callback) הייתה אומת בהצלחה.

שאלות נפוצות

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

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

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

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

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

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

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

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