सर्वर-साइड से की जाने वाली पुष्टि (SSV) के कॉलबैक की पुष्टि करना

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

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

Java spring-boot का इस्तेमाल करके, इनाम वाले एसएसवी का उदाहरण देखें.

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

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

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

Tink Java ऐप्लिकेशन के 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(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 की कुंजी सर्वर से कनेक्ट करें और कुंजियों को डाउनलोड करें. नीचे दिया गया कोड, यह काम करता है और data वैरिएबल में, कुंजियों के JSON प्रतिनिधित्व को सेव करता है.

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;
}

पुष्टि के लिए कॉन्टेंट पाना

इनाम वाले SSV कॉलबैक के आखिरी दो क्वेरी पैरामीटर हमेशा 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 से आते हैं.