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

اختيار المنصّة: Android (إصدار تجريبي) Android iOS Unity Flutter

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

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

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

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

استخدام فئة RewardedAdsVerifier من مكتبة Tink Java Apps

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

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

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

مَعلمات معاودة الاتصال لإثبات الملكية من جهة الخادم

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

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

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

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

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

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

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

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

RewardedAd.load(
    AdRequest.Builder("AD_UNIT_ID").build(),
    object : AdLoadCallback<RewardedAd> {
      override fun onAdLoaded(ad: RewardedAd) {
        // Rewarded ad loaded.
        rewardedAd = ad;
        rewardedAd.setServerSideVerificationOptions(
          ServerSideVerificationOptions("userId", "customData")
        )
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        // Rewarded ad failed to load.
        rewardedAd = null
      }
    },
  )

RewardedAd.load(
      new AdRequest.Builder("AD_UNIT_ID").build(),
      new AdLoadCallback<RewardedAd>() {
        @Override
        public void onAdLoaded(@NonNull RewardedAd ad) {
          // Rewarded ad loaded.
          rewardedAd = ad;
          rewardedAd.setServerSideVerificationOptions(
              new ServerSideVerificationOptions("userId", "customData")
          );
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          // Rewarded ad failed to load.
          rewardedAd = null;
        }
      }
  );

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

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

في ما يلي الخطوات التي تتّبعها فئة 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.