सर्वर-साइड की पुष्टि

सर्वर साइड से की जाने वाली पुष्टि के कॉलबैक, यूआरएल अनुरोध होते हैं. इनमें क्वेरी पैरामीटर होते हैं जिन्हें Google बड़ा करता है. Google इन्हें किसी बाहरी सिस्टम को भेजता है, ताकि उसे यह सूचना दी जा सके कि इनाम वाले विज्ञापन या इनाम वाले इंटरस्टीशियल विज्ञापन के साथ इंटरैक्ट करने पर, उपयोगकर्ता को इनाम दिया जाना चाहिए. इनाम वाले विज्ञापन के लिए एसएसवी (सर्वर साइड से की जाने वाली पुष्टि) कॉलबैक, उपयोगकर्ताओं को इनाम देने के लिए क्लाइंट-साइड कॉलबैक की स्पूफ़िंग से सुरक्षा की एक अतिरिक्त लेयर उपलब्ध कराते हैं.

इस गाइड में, इनाम वाले एसएसवी कॉलबैक की पुष्टि करने का तरीका बताया गया है. इसके लिए, तीसरे पक्ष की क्रिप्टोग्राफ़िक लाइब्रेरी, Tink Java Apps का इस्तेमाल किया जाता है. इससे यह पक्का किया जाता है कि कॉलबैक में मौजूद क्वेरी पैरामीटर की वैल्यू मान्य हों. इस गाइड में Tink का इस्तेमाल किया गया है. हालांकि, आपके पास तीसरे पक्ष की ऐसी किसी भी लाइब्रेरी का इस्तेमाल करने का विकल्प है जो ECDSA के साथ काम करती हो. AdMob के यूज़र इंटरफ़ेस (यूआई) में मौजूद टेस्टिंग टूल की मदद से भी अपने सर्वर की जांच की जा सकती है.

ज़रूरी शर्तें

• अपनी विज्ञापन यूनिट पर, इनाम वाले विज्ञापन के लिए सर्वर साइड से की जाने वाली पुष्टि की सुविधा चालू करें.

Tink Java ऐप्लिकेशन की लाइब्रेरी से RewardedAdsVerifier का इस्तेमाल करना

Tink Java Apps GitHub रिपॉज़िटरी में, RewardedAdsVerifier हेल्पर क्लास शामिल है. इससे, इनाम वाले एसएसवी कॉलबैक की पुष्टि करने के लिए ज़रूरी कोड को कम किया जा सकता है. इस क्लास का इस्तेमाल करके, यहां दिए गए कोड की मदद से कॉलबैक यूआरएल की पुष्टि की जा सकती है.

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

अगर verify() तरीका, बिना किसी गड़बड़ी के लागू होता है, तो कॉलबैक यूआरएल की पुष्टि हो जाती है. उपयोगकर्ता को इनाम देना सेक्शन में, उपयोगकर्ताओं को इनाम देने के सबसे सही तरीकों के बारे में बताया गया है. इनाम वाले एसएसवी कॉलबैक की पुष्टि करने के लिए, इस क्लास में किए गए चरणों की जानकारी के लिए, इनाम वाले एसएसवी की मैन्युअल तरीके से पुष्टि सेक्शन को पढ़ें.

एसएसवी कॉलबैक पैरामीटर

सर्वर साइड से की जाने वाली पुष्टि के कॉलबैक में, क्वेरी पैरामीटर होते हैं. इनसे इनाम वाले विज्ञापन इंटरैक्शन के बारे में जानकारी मिलती है. पैरामीटर के नाम, ब्यौरे, और उदाहरण के तौर पर दी गई वैल्यू यहां दी गई हैं. पैरामीटर, वर्णमाला के क्रम में भेजे जाते हैं.

विज्ञापन स्रोत के आइडेंटिफ़ायर

उपयोगकर्ता को इनाम देना

उपयोगकर्ता को इनाम देने का समय तय करते समय, उपयोगकर्ता अनुभव और इनाम की पुष्टि के बीच संतुलन बनाना ज़रूरी है. सर्वर-साइड कॉलबैक को बाहरी सिस्टम तक पहुंचने में देरी हो सकती है. इसलिए, हमारा सुझाव है कि उपयोगकर्ता को तुरंत इनाम देने के लिए, क्लाइंट-साइड कॉलबैक का इस्तेमाल करें. साथ ही, सर्वर-साइड कॉलबैक मिलने पर सभी इनामों की पुष्टि करें. इस तरीके से, उपयोगकर्ताओं को बेहतर अनुभव मिलता है. साथ ही, यह पक्का किया जाता है कि दिए गए इनाम मान्य हों.

हालांकि, ऐसे ऐप्लिकेशन के लिए जहां इनाम की वैधता ज़रूरी है (उदाहरण के लिए, इनाम से आपके ऐप्लिकेशन के इन-गेम इकॉनमी पर असर पड़ता है) और इनाम देने में देरी स्वीकार की जा सकती है, वहां पुष्टि किए गए सर्वर-साइड कॉलबैक का इंतज़ार करना सबसे सही तरीका हो सकता है.

कस्टम डेटा

जिन ऐप्लिकेशन को सर्वर साइड से की जाने वाली पुष्टि के कॉलबैक में अतिरिक्त डेटा की ज़रूरत होती है उन्हें इनाम वाले विज्ञापनों के कस्टम डेटा की सुविधा का इस्तेमाल करना चाहिए. इनाम वाले विज्ञापन ऑब्जेक्ट पर सेट की गई कोई भी स्ट्रिंग वैल्यू, एसएसवी कॉलबैक के custom_data क्वेरी पैरामीटर को पास की जाती है. अगर कस्टम डेटा की कोई वैल्यू सेट नहीं की गई है, तो एसएसवी कॉलबैक में custom_data क्वेरी पैरामीटर की वैल्यू मौजूद नहीं होगी.

यहां दिए गए उदाहरण में, इनाम वाला विज्ञापन लोड होने के बाद एसएसवी के विकल्प सेट किए गए हैं:

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 क्लास ने जो तरीका अपनाया है उसके बारे में यहां बताया गया है. हालांकि, शामिल किए गए कोड स्निपेट 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 वैल्यू से सार्वजनिक पासकोड तक की मैपिंग बनाता है. इन्हें Tink लाइब्रेरी से ECPublicKey ऑब्जेक्ट के तौर पर एन्कैप्सुलेट किया जाता है.

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

यहां दिए गए कोड से पता चलता है कि कॉलबैक यूआरएल से पुष्टि किए जाने वाले कॉन्टेंट को 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 पाना

पिछले चरण से मिली queryString वैल्यू का इस्तेमाल करके, कॉलबैक यूआरएल से signature और key_id क्वेरी पैरामीटर को पार्स करें. इसके लिए, यहां दिया गया तरीका अपनाएं:

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

पुष्टि करना

आखिरी चरण में, सही सार्वजनिक पासकोड का इस्तेमाल करके, कॉलबैक यूआरएल के कॉन्टेंट की पुष्टि की जाती है. parsePublicKeysJson वाले तरीके से मिली मैपिंग लें. इसके बाद, कॉलबैक यूआरएल से key_id पैरामीटर का इस्तेमाल करके, उस मैपिंग से सार्वजनिक पासकोड पाएं. इसके बाद, उस सार्वजनिक पासकोड से हस्ताक्षर की पुष्टि करें. इन चरणों को यहां 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);
  }
}

अगर यह तरीका बिना किसी गड़बड़ी के काम करता है, तो इसका मतलब है कि कॉलबैक यूआरएल की पुष्टि हो गई है.

अक्सर पूछे जाने वाले सवाल

क्या AdMob के पासकोड सर्वर से मिले सार्वजनिक पासकोड को कैश मेमोरी में सेव किया जा सकता है?

हमारा सुझाव है कि आप AdMob कुंजी सर्वर से मिली सार्वजनिक कुंजी को कैश मेमोरी में सेव करें. इससे, एसएसवी कॉलबैक की पुष्टि करने के लिए ज़रूरी कार्रवाइयों की संख्या कम हो जाएगी. हालांकि, ध्यान दें कि सार्वजनिक पासकोड नियमित तौर पर बदले जाते हैं. इसलिए, उन्हें 24 घंटे से ज़्यादा समय तक कैश मेमोरी में सेव नहीं किया जाना चाहिए.

AdMob के पासकोड सर्वर से मिलने वाले सार्वजनिक पासकोड कितनी बार बदले जाते हैं?

AdMob के पासकोड सर्वर से मिलने वाले सार्वजनिक पासकोड, अलग-अलग शेड्यूल के हिसाब से बदलते रहते हैं. यह पक्का करने के लिए कि एसएसवी कॉलबैक की पुष्टि सही तरीके से होती रहे, सार्वजनिक कुंजियों को 24 घंटे से ज़्यादा समय तक कैश मेमोरी में सेव नहीं किया जाना चाहिए.

अगर मेरे सर्वर से संपर्क नहीं हो पाता है, तो क्या होगा?

Google को उम्मीद है कि एसएसवी कॉलबैक के लिए, HTTP 200 OK सक्सेस स्टेटस रिस्पॉन्स कोड मिलेगा. अगर आपके सर्वर से संपर्क नहीं हो पाता है या वह उम्मीद के मुताबिक जवाब नहीं देता है, तो Google एक सेकंड के अंतराल पर, एसएसवी कॉलबैक भेजने की कोशिश फिर से करेगा. ऐसा पांच बार किया जाएगा.

मैं यह कैसे पुष्टि करूं कि एसएसवी कॉलबैक, Google से आ रहे हैं?

रिवर्स डीएनएस लुकअप का इस्तेमाल करके, यह पुष्टि करें कि एसएसवी कॉलबैक, Google से ही आ रहे हैं.