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

بازخوان‌های درستی‌سنجی سمت سرور درخواست‌های نشانی وب با پارامترهای پُرسمان هستند که توسط Google گسترش یافته‌اند و 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(with:"AD_UNIT_ID",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedAd = ad
      let options = ServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedAd.serverSideVerificationOptions = options
    }
})

GADRequest *request = [GADRequest request];
[GADRewardedAd loadWithAdUnitID:@"AD_UNIT_ID"
                        request:request
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  // Handle Error
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = 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 منشأ می‌گیرند استفاده کنید.