التحقّق من صحة عمليات معاودة الاتصال في ميزة "إثبات الملكية من جهة الخادم"

التحقّق اليدوي من معاودة الاتصال لعملية إثبات الملكية من جهة الخادم للإعلانات مقابل مكافأة

في ما يلي الخطوات التي تتّبعها فئة RewardedAdsVerifier للتحقّق من معاودة الاتصال لعملية إثبات الملكية من جهة الخادم للإعلانات مقابل مكافأة. على الرغم من أنّ مقتطفات الرموز البرمجية المضمّنة مكتوبة بلغة Java و تستخدِم مكتبة Tink التابعة لجهة خارجية، يمكنك تنفيذ هذه الخطوات باللغة التي تختارها، باستخدام أي مكتبة تابعة لجهة خارجية تتوافق مع ECDSA.

جلب المفاتيح العامة

للتحقّق من معاودة الاتصال لعملية إثبات الملكية من جهة الخادم للإعلانات مقابل مكافأة، تحتاج إلى مفتاح عام يوفّره AdMob.

يمكن جلب قائمة بالمفاتيح العامة التي سيتم استخدامها للتحقّق من معاودات الاتصال لعملية إثبات الملكية من جهة الخادم للإعلانات مقابل مكافأة من خادم مفاتيح 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;
}

الحصول على المحتوى الذي سيتم التحقّق منه

آخر معلَمتَي طلب بحث لمعاودات الاتصال لعملية إثبات الملكية من جهة الخادم للإعلانات مقابل مكافأة هما دائمًا signature و key_id,، بهذا الترتيب. تحدّد معامِلات طلب البحث المتبقية المحتوى الذي سيتم التحقّق منه. لنفترض أنّك ضبطت AdMob لإرسال معاودات الاتصال للمكافأة إلى https://www.myserver.com/mypath. يعرض المقتطف أدناه مثالاً على معاودة الاتصال لعملية إثبات الملكية من جهة الخادم للإعلانات مقابل مكافأة مع تمييز المحتوى الذي سيتم التحقّق منه.

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 لمعاودة الاتصال

باستخدام قيمة 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 لمعاودة الاتصال باستخدام المفتاح العام المناسب. استخدِم عملية الربط التي تم عرضها من طريقة 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 لمعاودة الاتصال بنجاح.

الأسئلة الشائعة

هل يمكنني تخزين المفتاح العام الذي يوفّره خادم مفاتيح AdMob مؤقتًا؟

ننصحك بتخزين المفتاح العام الذي يوفّره خادم مفاتيح AdMob مؤقتًا لتقليل عدد العمليات المطلوبة للتحقّق من معاودات الاتصال لعملية إثبات الملكية من جهة الخادم. مع ذلك، يُرجى العِلم أنّه يتم تدوير المفاتيح العامة بانتظام ويجب عدم تخزينها مؤقتًا لأكثر من 24 ساعة.

ما هو معدّل تدوير المفاتيح العامة التي يوفّرها خادم مفاتيح AdMob؟

يتم تدوير المفاتيح العامة التي يوفّرها خادم مفاتيح AdMob وفقًا لجدول زمني متغيّر. لضمان استمرار عمل التحقّق من معاودات الاتصال لعملية إثبات الملكية من جهة الخادم على النحو المطلوب، يجب عدم تخزين المفاتيح العامة مؤقتًا لأكثر من 24 ساعة.

ماذا يحدث إذا تعذّر الوصول إلى الخادم؟

تتوقّع Google رمز استجابة لحالة النجاح HTTP 200 OK لمعاودات الاتصال لعملية إثبات الملكية من جهة الخادم. إذا تعذّر الوصول إلى الخادم أو لم يقدّم الاستجابة المتوقّعة، ستعيد Google محاولة إرسال معاودات الاتصال لعملية إثبات الملكية من جهة الخادم حتى خمس مرات على فترات زمنية مدتها ثانية واحدة.

كيف يمكنني التأكّد من أنّ معاودات الاتصال لعملية إثبات الملكية من جهة الخادم واردة من Google؟

استخدِم بحث نظام أسماء النطاقات العكسي للتأكّد من أنّ معاودات الاتصال لعملية إثبات الملكية من جهة الخادم واردة من Google.