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

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

این راهنما به شما نشان می‌دهد که چگونه بااستفاده از کتابخانه رمزنگاری شخص ثالث Tink Java Apps، فراخوان‌های برگشتی SSV پاداش‌دار را درستی‌سنجی کنید تا مطمئن شوید که پارامترهای پُرسمان در فراخوان برگشتی مقادیر قانونی هستند. اگرچه از 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 را پس‌از بار شدن آگهی پاداش‌دار تنظیم می‌کند:

RewardedAd.load(
  adUnitId: "_adUnitId",
  request: AdRequest(),
  rewardedAdLoadCallback: RewardedAdLoadCallback(
    onAdLoaded: (ad) {
      ServerSideVerificationOptions _options =
          ServerSideVerificationOptions(
            customData: 'SAMPLE_CUSTOM_DATA_STRING',
          );
      ad.setServerSideOptions(_options);
      _rewardedAd = ad;
    },
    onAdFailedToLoad: (error) {},
  ),
);
rewarded_ad_snippets.dart

‫SAMPLE_CUSTOM_DATA_STRING را با داده‌های سفارشی خودتان جایگزین کنید.

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

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

مراحل انجام‌شده توسط کلاس 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 منشأ می‌گیرند استفاده کنید.