अपने ऐप्लिकेशन में, पीसी के लिए Play Integrity API को इंटिग्रेट करना

Play Integrity for PC की मदद से यह पता किया जा सकता है कि गेम इवेंट और सर्वर के अनुरोध, किसी भरोसेमंद पीसी डिवाइस पर Google Play Games for PC के किसी भरोसेमंद इंस्टेंस से किए गए हैं या नहीं. जोखिम वाले डिवाइसों और अनजान एम्युलेटर का पता लगाकर, आपके गेम का बैकएंड सर्वर सही कार्रवाइयां कर सकता है. इससे, धोखाधड़ी, बिना अनुमति के ऐक्सेस, धोखाधड़ी वाला ट्रैफ़िक, और गलत इस्तेमाल को रोका जा सकता है.

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

• एसडीके टूल का सेटअप पूरा करें.
• Integrity API की सुरक्षा से जुड़ी बातें देखें.
• Integrity API की सेवा की शर्तें और डेटा हैंडलिंग से जुड़ी जानकारी पढ़ें और समझें.
• Google Cloud Console में, Cloud प्रोजेक्ट बनाएं या कोई ऐसा मौजूदा Cloud प्रोजेक्ट चुनें जिसे आपको पीसी के लिए Play Integrity API के साथ इस्तेमाल करना है. एपीआई और सेवाएं पर जाएं और Google Play Integrity API चालू करें.
• अगर आपको हर दिन पीसी के लिए Play Integrity API से 10 हज़ार से ज़्यादा अनुरोध करने हैं, तो आपको हर दिन किए जाने वाले अनुरोधों की संख्या बढ़ाने का अनुरोध करना चाहिए.

पहला चरण: तय करें कि आपको अपने गेम में पीसी के लिए Play Integrity API का इस्तेमाल कैसे करना है

तय करें कि आपको पीसी के लिए Play Integrity API को कब कॉल करना है, ताकि एनवायरमेंट के बारे में इंटिग्रिटी की जांच का नतीजा मिल सके. उदाहरण के लिए, गेम खुलने पर, किसी खिलाड़ी के साइन इन करने पर या किसी खिलाड़ी के मल्टीप्लेयर गेम में शामिल होने पर, फ़ैसले का अनुरोध किया जा सकता है. इसके बाद, तय करें कि आपको सुरक्षा की जांच के अलग-अलग नतीजों को कैसे मैनेज करना है. उदाहरण के लिए, आप ये काम कर सकते हैंः

• नीति उल्लंघन के ख़िलाफ़ कार्रवाई किए बिना जवाब इकट्ठा करें और डेटा का विश्लेषण करें. इससे यह पता चलेगा कि क्या यह दुरुपयोग का कोई काम का सिग्नल है.
• जवाब इकट्ठा करें और अपने बैकएंड सर्वर पर लॉजिक लागू करें, ताकि जिन डिवाइसों पर इंटिग्रिटी के फ़ैसले सही हों वे आपके गेम को सामान्य तरीके से खेल सकें. साथ ही, संदिग्ध एनवायरमेंट से आने वाले ट्रैफ़िक को चुनौती दी जा सके या उसे ऐक्सेस करने से रोका जा सके.
• जवाब इकट्ठा करें और अपने बैकएंड पर लॉजिक लागू करें, ताकि उन डिवाइसों पर खिलाड़ियों को मैच किया जा सके जिन पर इंटेग्रिटी चेक पास हो गए हैं. साथ ही, संदिग्ध एनवायरमेंट से आने वाले ट्रैफ़िक को एक साथ मैच किया जा सके.

दूसरा चरण: अपने गेम में इंटिग्रिटी टोकन का अनुरोध करना

पीसी के लिए Play Integrity को चालू करना

पीसी के लिए Play Integrity को तैयार करें (या "वार्म अप" करें). इससे Google Play को डिवाइस पर, पुष्टि करने से जुड़ी कुछ जानकारी को स्मार्ट तरीके से कैश मेमोरी में सेव करने की अनुमति मिलती है. ऐसा इसलिए किया जाता है, ताकि जब आप इंटिग्रिटी के फ़ैसले का अनुरोध करें, तो अहम पाथ पर लेटेन्सी कम हो. गेम खुलते ही, इस तरीके का इस्तेमाल किया जा सकता है. इससे, जब भी ज़रूरत हो, मांग के हिसाब से इंटिग्रिटी के अनुरोध किए जा सकते हैं.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

अनुरोध पूरा होने पर, जारी रखने की प्रोसेस को PrepareIntegrityTokenResultValue के साथ कॉल किया जाएगा. इसमें RequestTokenData शामिल होगा. इसका इस्तेमाल, इंटिग्रिटी टोकन का अनुरोध करने के लिए किया जाना चाहिए. इस डेटा को इन-मेमोरी में कैश मेमोरी में सेव किया जाना चाहिए. साथ ही, RequestIntegrityToken को कॉल करने के लिए, ऐप्लिकेशन के सेशन की अवधि के दौरान इसका फिर से इस्तेमाल किया जाना चाहिए.

PrepareIntegrityToken को सिर्फ़ तब कॉल किया जाना चाहिए, जब आपके ऐप्लिकेशन को यह पता चले कि पूरी सुरक्षा की जांच के नतीजे का फिर से आकलन करना ज़रूरी है.

PrepareIntegrityToken कार्रवाई को कैसे कॉल किया जाना चाहिए, यह दिखाने वाला कोड स्निपेट यहां दिया गया है:

google::play::integrity::IntegrityClient client_;

google::play::integrity::PrepareIntegrityTokenResult
IntegrityInterface::PrepareIntegrityToken(int64_t cloud_project_number) {
  google::play::integrity::PrepareIntegrityTokenParams params;
  params.cloud_project_number = cloud_project_number;

  auto promise = std::make_shared<
      std::promise<google::play::integrity::PrepareIntegrityTokenResult>>();
  client_.PrepareIntegrityToken(
      params,
      [promise](
          google::play::integrity::PrepareIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

इंटिग्रिटी टोकन का अनुरोध करना

इंटिग्रिटी टोकन, आपके गेम के लिए एक ऐसा तरीका है जिससे यह पुष्टि की जा सकती है कि डिवाइस से कोई छेड़छाड़ नहीं की गई है. जब भी आपका गेम कोई ऐसा सर्वर अनुरोध करता है जिसकी आपको पुष्टि करनी है, तब इंटिग्रिटी टोकन का अनुरोध किया जा सकता है. इसके बाद, इसे डिक्रिप्ट करने और पुष्टि करने के लिए, अपने गेम के बैकएंड सर्वर पर भेजा जा सकता है.

अगर आपको पीसी पर Play Integrity API की मदद से, अपने ऐप्लिकेशन में किसी उपयोगकर्ता की कार्रवाई की जांच करनी है, तो छेड़छाड़ वाले हमलों से बचने के लिए, RequestIntegrityTokenParams::request_hash फ़ील्ड का इस्तेमाल किया जा सकता है. उदाहरण के लिए, हो सकता है कि आपको खिलाड़ी के स्कोर की जानकारी अपने गेम के बैकएंड सर्वर को देनी हो. साथ ही, आपका सर्वर यह पुष्टि करना चाहता हो कि इस स्कोर में किसी प्रॉक्सी सर्वर ने कोई बदलाव नहीं किया है. पीसी के लिए Play Integrity, इस फ़ील्ड में सेट की गई वैल्यू को, हस्ताक्षर की गई इंटिग्रिटी रिस्पॉन्स में दिखा सकता है. requestHash के बिना, इंटिग्रिटी टोकन सिर्फ़ डिवाइस से जुड़ा होगा. हालांकि, यह किसी खास अनुरोध से नहीं जुड़ा होगा. इससे हमला होने की आशंका बढ़ जाती है.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

सुरक्षा की जांच के नतीजे का अनुरोध करते समय, हमले की आशंका को कम करने के लिए:

• उपयोगकर्ता की कार्रवाई या सर्वर के अनुरोध से, सभी काम के अनुरोध पैरामीटर (जैसे, अनुरोध के स्टेबल सीरियलाइज़ेशन का SHA256) का डाइजेस्ट कंप्यूट करें.
• RequestIntegrityTokenParams::request_hash फ़ील्ड को डाइजेस्ट पर सेट करें.

RequestIntegrityToken ऐक्शन को कॉल करने का तरीका दिखाने वाला कोड स्निपेट यहां दिया गया है:

absl::StatusOr<google::play::integrity::RequestIntegrityTokenResult>
IntegrityInterface::RequestIntegrityToken(
    const google::play::integrity::PrepareIntegrityTokenResult&
        prepare_integrity_token_result,
    const std::string& request_hash) {
  // Check if the prepare_integrity_token_result is OK
  if (!prepare_integrity_token_result.ok()) {
    return absl::FailedPreconditionError(
        absl::StrCat("PrepareIntegrityTokenResult is not OK. Error code: ",
                     prepare_integrity_token_result.error_code));
  }

  google::play::integrity::RequestIntegrityTokenParams params{
      .request_token_data =
          prepare_integrity_token_result.request_token_data,
      .request_hash = request_hash};

  auto promise = std::make_shared<std::promise<
      google::play::integrity::RequestIntegrityTokenResult>>();
  client_.RequestIntegrityToken(
      params,
      [promise](google::play::integrity::RequestIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

तीसरा चरण: इसके बाद, अपने गेम के बैकएंड सर्वर पर इंटेग्रिटी टोकन को डिक्रिप्ट करें और उनकी पुष्टि करें

इंटिग्रिटी टोकन को डिक्रिप्ट करना

पूरी सुरक्षा की जांच के नतीजे का अनुरोध करने के बाद, Play Integrity API एन्क्रिप्ट (सुरक्षित) किया गया रिस्पॉन्स टोकन उपलब्ध कराता है. डिवाइस इंटिग्रिटी के नतीजे पाने के लिए, आपको Google के सर्वर पर इंटिग्रिटी टोकन को डिक्रिप्ट करना होगा:

1. अपने ऐप्लिकेशन से लिंक किए गए Google Cloud प्रोजेक्ट में, एक सेवा खाता बनाएं.

2. अपने ऐप्लिकेशन के सर्वर पर, playintegrity स्कोप का इस्तेमाल करके, अपने सेवा खाते के क्रेडेंशियल से ऐक्सेस टोकन फ़ेच करें. इसके बाद, यह अनुरोध करें:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. JSON फ़ॉर्मैट में मिले जवाब को पढ़ें.

इसके बाद मिलने वाला पेलोड, सादा टेक्स्ट वाला एक टोकन होता है. इसमें सुरक्षा की जांच के नतीजे और जानकारी शामिल होती है. साथ ही, इसमें डेवलपर की दी गई जानकारी भी शामिल होती है. डिक्रिप्ट किया गया इंटिग्रिटी टोकन ऐसा दिखता है:

{
  "requestDetails": {
    "requestPackageName": "com.your.package.name",
    "requestTime": "2025-08-29T13:10:37.285Z",
    "requestHash": "your_request_hash_string"
  },
  "deviceIntegrity": {
    "deviceRecognitionVerdict": [
      "MEETS_PC_INTEGRITY"
    ]
  },
  "accountDetails": {
    "appLicensingVerdict": "LICENSED"
  }
}

इंटिग्रिटी टोकन की पुष्टि करना

डिकोड किए गए इंटिग्रिटी टोकन के requestDetails फ़ील्ड में अनुरोध के बारे में जानकारी होती है. इसमें डेवलपर की ओर से दी गई जानकारी भी शामिल होती है. यह जानकारी requestHash में मौजूद होती है.

requestHash और packageName फ़ील्ड की वैल्यू, ओरिजनल अनुरोध में दी गई वैल्यू से मेल खानी चाहिए. इसलिए, JSON पेलोड के requestDetails हिस्से की पुष्टि करें. इसके लिए, यह पक्का करें कि requestPackageName और requestHash, ओरिजनल अनुरोध में भेजे गए डेटा से मेल खाते हों. जैसा कि यहां दिए गए कोड स्निपेट में दिखाया गया है:

const auto& request_details = json_payload["requestDetails"];

if (request_details.value("requestPackageName", "") != <YOUR_PACKAGE_NAME>) {
  // Don't trust the verdicts.
}

// Check for the existence of the request_hash.
// If you set a request hash in the request and it's not present, you shouldn't
// trust the verdicts.
if (!request_details.contains("requestHash")) {
    // Don't trust the verdicts.
}


// The requestHash from request_details needs to match the request hash your
// app provided.
if (request_details.value("requestHash", "") != <PROVIDED_REQUEST_HASH>) {
    // Don't trust the verdicts.
}

// You can read the rest of payload's fields.

चौथा चरण: इंटिग्रिटी के नतीजे के आधार पर, कार्रवाई तय करना

deviceIntegrity फ़ील्ड में सिर्फ़ एक वैल्यू हो सकती हैdeviceRecognitionVerdict. इस वैल्यू का इस्तेमाल करके, यह पता लगाया जा सकता है कि आपका गेम ऐसे पीसी पर चल रहा है या नहीं जिस पर Play की इंटिग्रिटी जांच पास हो गई है. यह MEETS_PC_INTEGRITY रिस्पॉन्स है. accountDetails फ़ील्ड में एक वैल्यू, appLicensingVerdict मौजूद है. इस वैल्यू का इस्तेमाल करके यह पता लगाया जा सकता है कि उपयोगकर्ता को Play से लाइसेंस मिला है या नहीं. आपके गेम का बैकएंड सर्वर यह जानकारी इकट्ठा कर सकता है. साथ ही, इसका इस्तेमाल यह तय करने के लिए कर सकता है कि आपके गेम को कौनसी कार्रवाई करनी चाहिए. जैसे, किसी गेम इवेंट को आगे बढ़ने की अनुमति देना या जोखिम भरे ट्रैफ़िक को ऐक्सेस करने से रोकना.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
"accountDetails": {
  "appLicensingVerdict": "LICENSED"
}

डिवाइस इंटिग्रिटी के नतीजे

deviceRecognitionVerdict में ये वैल्यू हो सकती हैं:

MEETS_PC_INTEGRITY

यह गेम, पीसी के भरोसेमंद एनवायरमेंट पर चल रहा है. इसमें डिवाइस पर किसी तरह की छेड़छाड़ का पता नहीं चला है.

खाली (वैल्यू खाली है)

गेम किसी ऐसे डिवाइस पर चल रहा है जिस पर हमला होने (जैसे कि एपीआई हुकिंग) या सिस्टम से छेड़छाड़ (जैसे कि डिवाइस पर Google Desktop Services का ऐसा वर्शन चल रहा है जिसमें छेड़छाड़ की गई है) के संकेत मिले हैं. ऐसा भी हो सकता है कि गेम किसी फ़िज़िकल डिवाइस पर न चल रहा हो. उदाहरण के लिए, किसी ऐसे एम्युलेटर पर चल रहा हो जिसमें पूरी सुरक्षा देने वाला Google Play Integrity मौजूद नहीं है.

खाते की जानकारी से जुड़े नतीजे

appLicensingVerdict में ये वैल्यू हो सकती हैं:

LICENSED

उपयोगकर्ता के पास ऐप्लिकेशन का अधिकार है. इसका मतलब है कि उपयोगकर्ता ने अपने डिवाइस पर Google Play से आपका ऐप्लिकेशन इंस्टॉल किया है या अपडेट किया है.

UNLICENSED

उपयोगकर्ता के पास ऐप्लिकेशन का एनटाइटलमेंट नहीं है. ऐसा तब होता है, जब कोई व्यक्ति ऐप्लिकेशन को अलग से लोड करता है या उसे Google Play से डाउनलोड नहीं करता.

UNEVALUATED

लाइसेंस से जुड़ी जानकारी की जांच नहीं की गई, क्योंकि एक ज़रूरी शर्त पूरी नहीं हुई. ऐसा कई वजहों से हो सकता है. जैसे:

• डिवाइस भरोसेमंद नहीं है.
• डिवाइस पर इंस्टॉल किए गए आपके ऐप्लिकेशन के वर्शन की जानकारी Google Play को नहीं है.
• उपयोगकर्ता ने Google Play में साइन इन नहीं किया है.

पांचवां चरण: गड़बड़ी के कोड मैनेज करना

अगर आपका गेम, पीसी के लिए Play Integrity API का अनुरोध करता है और कॉल पूरा नहीं होता है, तो आपके गेम को गड़बड़ी का कोड मिलता है. ये गड़बड़ियां कई वजहों से हो सकती हैं. जैसे, खराब नेटवर्क कनेक्शन जैसी पर्यावरण से जुड़ी समस्याएं, एपीआई इंटिग्रेशन से जुड़ी समस्याएं या नुकसान पहुंचाने वाली गतिविधि और सक्रिय हमले.

फिर से कोशिश करने पर ठीक हो सकने वाली गड़बड़ियों के कोड

ये गड़बड़ियां कभी-कभी कुछ समय के लिए होती हैं. इसलिए, आपको एक्स्पोनेंशियल बैक-ऑफ़ रणनीति के साथ कॉल को फिर से आज़माना चाहिए.

फिर से कोशिश करने की रणनीतियों के बारे में ज़्यादा सुझाव यहां देखें.

फिर से कोशिश न की जा सकने वाली गड़बड़ी के कोड

इन मामलों में, अपने-आप फिर से कोशिश करने की सुविधा से मदद नहीं मिलेगी. हालांकि, अगर उपयोगकर्ता उस समस्या को ठीक कर लेता है जिसकी वजह से यह गड़बड़ी हुई थी, तो मैन्युअल तरीके से फिर से कोशिश करने पर गड़बड़ी ठीक हो सकती है.

अपने ऐप्लिकेशन में, Play Integrity API से मिले अलग-अलग जवाबों को टेस्ट करना

Play Integrity API आपके ऐप्लिकेशन के साथ कैसे इंटरैक्ट करता है, यह जानने के लिए टेस्ट बनाए जा सकते हैं.

1. उपयोगकर्ताओं के ईमेल पतों से एक Google ग्रुप (या जितने चाहें उतने) सेट अप करें. Google Play के सर्वर से, इन उपयोगकर्ताओं को आपके ऐप्लिकेशन में इंटिग्रिटी के फ़ैसले या गड़बड़ी का कोड मिलना चाहिए. इसके लिए, आपको इंटिग्रिटी के फ़ैसले या गड़बड़ी का कोड चुनना होगा. इससे यह जांच की जा सकती है कि आपका ऐप्लिकेशन, सभी संभावित जवाबों और गड़बड़ियों पर कैसे प्रतिक्रिया करता है.

2. यहां टिकट बनाएं और बताएं कि किस Google ग्रुप को एपीआई का कौन-सा जवाब मिलेगा. हर ग्रुप को इनमें से कोई एक विकल्प दिया जाता है:

   	लाइसेंस की पुष्टि करने से जुड़ा फ़ैसला	लाइसेंसिंग के फ़ैसले में गड़बड़ी हुई	लाइसेंस की स्थिति के नतीजे का आकलन नहीं किया जा सका
   डिवाइस इंटिग्रिटी की जांच पास करना	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED
   डिवाइस इंटिग्रिटी की जांच में फ़ेल होना	लागू नहीं	लागू नहीं	ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED

   अगर डिवाइस इंटिग्रिटी की जांच का नतीजा 'फ़ेल' होता है, तो लाइसेंस की जांच का नतीजा हमेशा UNEVALUATED दिखेगा.

3. अनुरोध प्रोसेस होने के बाद, आपको इसकी सूचना दी जाएगी. साथ ही, जांच करने वाले उपयोगकर्ताओं को अनुमति वाली सूची में शामिल कर लिया जाएगा, ताकि वे जांच के लिए पहले से तय किए गए इंटिग्रिटी वर्डक पा सकें.