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

عمليات معاودة الاتصال لعملية تحقّق من جهة الخادم هي طلبات عناوين URL، مع معلمات طلب البحث التي توسّعها Google، وترسلها Google إلى نظام خارجي لإعلامه بأنّه يجب منح المستخدم مكافأة مقابل التفاعل مع إعلان بيني أو إعلان بيني مقابل مكافأة. توفّر عمليات معاودة الاتصال من جهة الخادم (SSV) للإعلانات التي تضم مكافأة طبقة إضافية من الحماية ضد انتحال عمليات معاودة الاتصال من جهة العميل لمكافأة المستخدمين.

يوضّح لك هذا الدليل كيفية التحقّق من عمليات رد الاتصال من جهة الخادم (SSV) للإعلانات مقابل مكافآت باستخدام مكتبة التشفير التابعة لجهة خارجية Tink Java Apps للتأكّد من أنّ مَعلمات طلب البحث في عملية رد الاتصال هي قيم صالحة. على الرغم من استخدام Tink لأغراض هذا الدليل، يمكنك استخدام أي مكتبة تابعة لجهة خارجية تتوافق مع ECDSA. يمكنك أيضًا اختبار الخادم باستخدام أداة الاختبار في واجهة مستخدم AdMob.

المتطلبات الأساسية

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

استخدام RewardedAdsVerifier من مكتبة تطبيقات Tink Java

يتضمّن مستودع GitHub تطبيقات Tink Java فئة مساعدة RewardedAdsVerifier لتقليل الرمز البرمجي المطلوب للتحقّق من طلب معاودة الاتصال للتحقّق من جانب الخادم (SSV) بمكافأة. يتيح لك استخدام هذه الفئة التحقّق من صحة عنوان URL لردّ الاتصال باستخدام الرمز التالي.

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

إذا تم تنفيذ طريقة verify() بدون حدوث استثناء، يعني ذلك أنّه تم التحقّق من صحة عنوان URL الخاص بوظيفة رد الاتصال بنجاح. يقدّم قسم مكافأة المستخدم تفاصيل عن أفضل الممارسات المتعلّقة بالحالات التي يجب فيها مكافأة المستخدمين. للاطّلاع على تفاصيل الخطوات التي تنفّذها هذه الفئة للتحقّق من عمليات ردّ الاتصال عبر ميزة "إثبات الملكية من جهة الخادم" للإعلانات التي تضم مكافآت، يمكنك قراءة قسم التحقّق اليدوي من ميزة "إثبات الملكية من جهة الخادم" للإعلانات التي تضم مكافآت.

مَعلمات معاودة الاتّصال بالتحقّق من صحة العرض من جهة الخادم

تحتوي عمليات ردّ الاتصال لإثبات الملكية من جانب الخادم على مَعلمات طلب البحث التي تصف التفاعل مع "الإعلانات مقابل مكافأة". في ما يلي أسماء المَعلمات وأوصافها وأمثلة على قيمها. يتم إرسال المَعلمات بترتيب أبجدي.

معرّفات مصادر الإعلانات

مكافأة المستخدم

من المهم تحقيق التوازن بين تجربة المستخدم والتحقّق من صحة المكافأة عند تحديد وقت منح المكافأة للمستخدم. قد يحدث تأخير في عمليات معاودة الاتصال من جهة الخادم قبل وصولها إلى الأنظمة الخارجية. لذلك، فإن أفضل الممارسات الموصى بها هي استخدام عملية الاستدعاء من جهة العميل لمكافأة المستخدم على الفور، أثناء إجراء التحقق من صحة جميع المكافآت عند استلام عمليات الاستدعاء من جهة الخادم. يوفّر هذا النهج تجربة مستخدم جيدة مع ضمان صحة المكافآت الممنوحة.

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

البيانات المخصّصة

يجب أن تستخدم التطبيقات التي تتطلّب بيانات إضافية في عمليات معاودة الاتصال الخاصة بعملية التحقّق من جهة الخادم ميزة البيانات المخصّصة في "الإعلانات مقابل مكافأة". يتم تمرير أي قيمة سلسلة تم ضبطها على عنصر إعلان مقابل مكافأة إلى مَعلمة طلب البحث custom_data في معاودة الاتصال من جهة الخادم. في حال عدم ضبط قيمة بيانات مخصّصة، لن تظهر قيمة مَعلمة طلب البحث custom_data في ردّ الاتصال من جهة الخادم إلى الخادم.

يوضّح نموذج الرمز البرمجي التالي كيفية ضبط خيارات التحقّق من صحة عرض الإعلان من جهة الخادم بعد تحميل "الإعلان مقابل مكافأة":

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

إذا أردت ضبط سلسلة المكافآت المخصّصة، عليك إجراء ذلك قبل عرض الإعلان.

التحقّق يدويًا من ميزة "التحقّق من جهة الخادم" (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();
}

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

بعد استرداد المفاتيح العامة، يجب تحليلها. تتلقّى الطريقة 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. يعرض المقتطف أدناه مثالاً على معاودة الاتصال من جهة الخادم (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 لبرنامج معالجة ردود الاتصال على أنّه مصفوفة بايت 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 مؤقتًا لتقليل عدد العمليات المطلوبة للتحقّق من صحة عمليات ردّ الاتصال الخاصة بالتحقّق من صحة العرض من جهة الخادم (SSV). يُرجى العِلم أنّه يتم تغيير المفاتيح العامة بانتظام ويجب عدم تخزينها مؤقتًا لمدة تزيد عن 24 ساعة.

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

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

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

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

كيف يمكنني التأكّد من أنّ عمليات معاودة الاتصال من جهة خادم التحقّق من صحة العرض (SSV) تأتي من Google؟

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