إثبات الملكية من جهة الخادم

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

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

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

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

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

يتضمّن مستودع تطبيقات Java في Tink على GitHub فئة مساعدة 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 في ردّ الاتصال من جهة الخادم إلى الخادم.

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

RewardedAd.load(with:"AD_UNIT_ID",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedAd = ad
      let options = ServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedAd.serverSideVerificationOptions = options
    }
})

GADRequest *request = [GADRequest request];
[GADRewardedAd loadWithAdUnitID:@"AD_UNIT_ID"
                        request:request
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  // Handle Error
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];

التحقّق يدويًا من صحة مكافآت "التحقّق من صحة العرض من جهة الخادم"

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

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

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

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