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

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

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

اطّلِع على مثال على نموذج SSV للإعلانات التي تضم مكافآت باستخدام Java spring-boot.

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

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

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

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

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

مَعلمات ردّ الاتصال في SSV

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

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

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

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

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

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

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

يحدِّد المثال التالي خيارات SSV بعد تحميل الإعلان الذي يقدّم مكافأة:

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 للتحقّق من صحة ملف تعريف الارتباط لعرض الإعلانات أثناء التشغيل الذي يتضمّن مكافأة. على الرغم من أنّ مقتطفات الرموز البرمجية المضمّنة مكتوبة بلغة 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. يعرض المقتطف أدناه مثالاً على طلب تأكيد هوية العميل في عملية شراء مدعومة بالإعلانات مع تمييز المحتوى المطلوب إثبات ملكيته.

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

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

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

كيف يمكنني التأكّد من أنّ عمليات تسجيل المكالمات في SSV تأتي من Google؟

استخدِم بحث نظام أسماء النطاقات العكسي للتحقّق من أنّ عمليات استدعاء SSV تأتي من Google.