اعتبارسنجی کردن برگشتی‌های درستی‌سنجی سمت سرور (SSV)

«بازخوان‌های درستی‌سنجی سمت سرور» درخواست‌های نشانی وب با پارامترهای پُرسمان هستند که Google آن‌ها را ازهم باز می‌کند و برای سیستم خارجی ارسال می‌کند تا به آن اطلاع دهد که کاربر باید برای تعامل با آگهی ویدیویی پاداش‌دار یا آگهی بینابینی پاداش‌دار پاداش دریافت کند. بازخوان‌های «درستی‌سنجی سمت سرور» پاداش‌دار لایه محافظتی اضافه‌ای دربرابر جعل بازخوان‌های سمت کارخواه برای پاداش دادن به کاربران ارائه می‌دهند.

این راهنما نحوه درستی‌سنجی کردن برگشتی‌های SSV پاداش‌دار را بااستفاده از برنامه‌های جاوا Tink کتابخانه رمزنگاری شخص ثالث نشان می‌دهد تا مطمئن شوید که پارامترهای پُرسمان در برگشتی مقادیر قانونی هستند. اگرچه از Tink برای اهداف این راهنما استفاده می‌شود، این گزینه را دارید که از هر کتابخانه طرف سومی که از ECDSA پشتیبانی می‌کند استفاده کنید. همچنین می‌توانید سرورتان را با ابزار آزمایش در واسط کاربر AdMob آزمایش کنید.

پیش‌نیازها

• درستی‌سنجی پاداش‌دار سمت سرور را در واحد آگهی‌تان فعال کنید.

از RewardedAdsVerifier از کتابخانه Tink Java Apps استفاده کنید

مخزن GitHub برنامه‌های Tink Java شامل RewardedAdsVerifier کلاس کمکی برای کاهش کد موردنیاز برای درستی‌سنجی کردن برگشتی SSV پاداش‌دار است. استفاده از این کلاس به شما امکان می‌دهد نشانی وب برگشتی را با کد زیر درستی‌سنجی کنید.

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

اگر روش verify() بدون ایجاد استثنا اجرا شود، نشانی وب پاسخ‌به‌تماس باموفقیت درستی‌سنجی شده است. بخش پاداش دادن به کاربر روال‌های مطلوب را درباره زمان پاداش دادن به کاربران شرح می‌دهد. برای جزئیات مراحل انجام‌شده توسط این کلاس برای درستی‌سنجی تماس‌های برگشتی SSV پاداش‌دار، می‌توانید بخش درستی‌سنجی دستی SSV پاداش‌دار را بخوانید.

پارامترهای فراخوانی SSV

کاربردهای درستی‌سنجی سمت سرور حاوی پارامترهای پُرسمانی است که تعامل آگهی پاداش‌دار را توصیف می‌کند. نام‌های پارامتر، شرح‌ها، و مقادیر نمونه در زیر فهرست شده است. پارامترها به‌ترتیب حروف الفبا ارسال می‌شوند.

شناسه‌های منبع آگهی

درحال پاداش دادن به کاربر

هنگام تصمیم‌گیری درباره زمان پاداش دادن به کاربر، مهم است که بین تجربه کاربری و اعتبارسنجی پاداش تعادل برقرار کنید. کاربرگ‌های سمت سرور ممکن است قبل‌از رسیدن به سیستم‌های خارجی با تأخیر مواجه شوند. بنابراین، بهترین روش توصیه‌شده این است که از فراخوانی برگشتی سمت کارخواه برای پاداش دادن فوری به کاربر استفاده کنید، و درعین‌حال اعتبارسنجی همه پاداش‌ها را پس‌از دریافت فراخوانی‌های برگشتی سمت سرور انجام دهید. این رویکرد تجربه کاربری خوبی ارائه می‌دهد و درعین‌حال اعتبار پاداش‌های اعطاشده را تضمین می‌کند.

بااین‌حال، برای برنامه‌هایی که اعتبار پاداش در آن‌ها حیاتی است (برای مثال، پاداش بر اقتصاد درون‌بازی برنامه شما تأثیر می‌گذارد) و تأخیر در اعطای پاداش قابل‌قبول است، ممکن است بهترین رویکرد انتظار برای تماس برگشتی سمت سرور تأییدشده باشد.

داده‌های سفارشی

برنامه‌هایی که در تماس‌های برگشتی درستی‌سنجی سمت سرور به داده‌های اضافی نیاز دارند باید از ویژگی داده‌های سفارشی آگهی‌های پاداش‌دار استفاده کنند. هر مقدار رشته‌ای که روی یک شیء آگهی پاداش‌دار تنظیم شده باشد، به پارامتر پُرسمان custom_data در برگشت تماس SSV منتقل می‌شود. اگر مقدار داده سفارشی تنظیم نشده باشد، مقدار پارامتر پُرسمان custom_data در بازخوانی SSV وجود نخواهد داشت.

نمونه کد زیر نشان می‌دهد که چگونه گزینه‌های SSV را پس‌از بار شدن آگهی پاداش‌دار تنظیم کنید:

private void LoadRewardedAd(string adUnitId)
{
  // Send the request to load the ad.
  AdRequest adRequest = new AdRequest();
  RewardedAd.Load(adUnitId, adRequest, (RewardedAd rewardedAd, LoadAdError error) =>
  {
    // If the operation failed with a reason.
    if (error != null)
    {
        Debug.LogError("Rewarded ad failed to load an ad with error : " + error);
        return;
    }

    var options = new ServerSideVerificationOptions
                          .Builder()
                          .SetCustomData("SAMPLE_CUSTOM_DATA_STRING")
                          .Build()
    rewardedAd.SetServerSideVerificationOptions(options);
  });
}

اگر می‌خواهید رشته پاداش سفارشی را تنظیم کنید، باید این کار را قبل‌از نمایش آگهی انجام دهید.

درستی‌سنجی دستی «درستی‌سنجی سمت سرور» پاداش‌دار

مراحل انجام‌شده توسط کلاس 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();
}

توجه داشته باشید که کلیدهای عمومی به‌طور منظم چرخش می‌کنند. ایمیلی دریافت خواهید کرد که شما را از چرخش آتی مطلع می‌کند. اگر کلیدهای عمومی را ذخیره می‌کنید، باید کلیدها را پس‌از دریافت این ایمیل به‌روز کنید.

وقتی کلیدهای عمومی واکشی شدند، باید تجزیه شوند. روش 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

کد زیر نشان می‌دهد که چگونه محتوای موردتأیید را از نشانی وب فراخوان به‌عنوان آرایه بایت 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 از نشانی وب پاسخ تماس

بااستفاده از مقدار queryString از مرحله قبلی، پارامترهای پُرسمان signature و key_id را از نشانی وب بازگشت تماس تجزیه کنید، همان‌طور که در زیر نشان داده شده است:

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

انجام درستی‌سنجی

مرحله نهایی درستی‌سنجی محتوای نشانی وب فراخوانی با کلید عمومی مناسب است. نگاشت برگشتی از روش parsePublicKeysJson را بگیرید و از پارامتر key_id از نشانی وب بازخوان برای دریافت کلید عمومی از آن نگاشت استفاده کنید. سپس امضا را با آن کلید عمومی به‌تأیید برسانید. این مراحل در زیر در روش 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);
  }
}

اگر روش بدون ایجاد استثنا اجرا شود، نشانی وب فراخوانی با موفقیت درستی‌سنجی شده است.

پرسشگان

آیا می‌توانم کلید عمومی ارائه‌شده توسط سرور کلید AdMob را در حافظه نهان ذخیره کنم؟

توصیه می‌کنیم کلید عمومی ارائه‌شده توسط سرور کلید AdMob را ذخیره کنید تا تعداد عملیات لازم برای اعتبارسنجی تماس‌های برگشتی SSV کاهش یابد. بااین‌حال، توجه داشته باشید که کلیدهای عمومی به‌طور منظم چرخش می‌کنند و نباید بیشتر از ۲۴ ساعت ذخیره شوند.

کلیدهای عمومی ارائه‌شده توسط سرور کلید AdMob هر چند وقت یک‌بار چرخش می‌کنند؟

کلیدهای عمومی ارائه‌شده توسط سرور کلید AdMob در یک برنامه زمانی متغیر چرخانده می‌شوند. برای اطمینان از اینکه درستی‌سنجی فراخوانی‌های SSV همچنان طبق انتظار کار می‌کند، کلیدهای عمومی نباید بیشتر از ۲۴ ساعت ذخیره موقت شوند.

اگر سرورم دردسترس نباشد چه اتفاقی می‌افتد؟

‫Google انتظار دارد کد پاسخ وضعیت موفقیت HTTP 200 OK برای بازخوان‌های SSV دریافت کند. اگر سرورتان دردسترس نباشد یا پاسخ موردانتظار را ارائه ندهد، Google تا پنج بار در فواصل یک ثانیه‌ای برای ارسال فراخوان‌های SSV تلاش مجدد خواهد کرد.

چگونه می‌توانم درستی‌سنجی کنم که بازخوان‌های SSV از Google می‌آیند؟

از جستجوی ساناد معکوس برای تأیید اینکه تماس‌های برگشتی SSV از Google منشأ می‌گیرند استفاده کنید.