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

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

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

يمكنك الاطّلاع على مثال على التحقّق من صحة العرض من جهة الخادم مقابل مكافأة باستخدام Java spring-boot.

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

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

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

يتضمّن مستودع تطبيقات Java في Tink على 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(MainActivity.this, "AD_UNIT_ID",
    new AdRequest.Builder().build(),  new RewardedAdLoadCallback() {
  @Override
  public void onAdLoaded(RewardedAd ad) {
    Log.d(TAG, "Ad was loaded.");
    rewardedAd = ad;
    ServerSideVerificationOptions options = new ServerSideVerificationOptions
        .Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build();
    rewardedAd.setServerSideVerificationOptions(options);
  }
  @Override
  public void onAdFailedToLoad(LoadAdError loadAdError) {
    Log.d(TAG, loadAdError.toString());
    rewardedAd = null;
  }
});

RewardedAd.load(this, "AD_UNIT_ID",
    AdRequest.Builder().build(), object : RewardedAdLoadCallback() {
  override fun onAdLoaded(ad: RewardedAd) {
    Log.d(TAG, "Ad was loaded.")
    rewardedInterstitialAd = ad
    val options = ServerSideVerificationOptions.Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build()
    rewardedAd.setServerSideVerificationOptions(options)
  }

  override fun onAdFailedToLoad(adError: LoadAdError) {
    Log.d(TAG, adError?.toString())
    rewardedAd = null
  }
})

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

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

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

يتم تدوير المفاتيح العامة التي يوفّرها خادم مفاتيح AdMob وفقًا لجدول زمني متغيّر.

لضمان استمرار عمل عمليات التحقّق من عمليات ردّ الاتصال من جهة خادم التحقّق من صحة الإعلانات (SSV) على النحو المنشود، يجب عدم تخزين المفاتيح العامة مؤقتًا لمدة تزيد عن 24 ساعة.

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

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

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

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