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

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

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

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

पहला चरण: तय करें कि आपके गेम में Play Integrity for PC का इस्तेमाल कैसे किया जाएगा

तय करें कि एनवायरमेंट के बारे में पूरी सुरक्षा की जांच का नतीजा पाने के लिए, Play Integrity for PC को कब कॉल किया जाएगा. उदाहरण के लिए, गेम खुलने पर, कोई प्लेयर साइन इन करने पर या कोई प्लेयर मल्टीप्लेयर गेम में शामिल होने पर, नतीजे का अनुरोध किया जा सकता है. इसके बाद, तय करें कि पूरी सुरक्षा की जांच के अलग-अलग नतीजों को कैसे मैनेज किया जाएगा. उदाहरण के लिए, ये काम किए जा सकते हैं:

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

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

Play Integrity for PC को चालू करना

Play Integrity for PC को चालू करें. इससे 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 for PC की मदद से, अपने ऐप्लिकेशन में किसी उपयोगकर्ता की कार्रवाई की जांच करते समय, RequestIntegrityTokenParams::request_hash फ़ील्ड का इस्तेमाल करके, छेड़छाड़ के हमलों को कम किया जा सकता है. उदाहरण के लिए, हो सकता है कि आपको प्लेयर के स्कोर की रिपोर्ट, अपने गेम के बैकएंड सर्वर को भेजनी हो. साथ ही, आपका सर्वर यह पुष्टि करना चाहता हो कि प्रॉक्सी सर्वर ने इस स्कोर से कोई छेड़छाड़ नहीं की है. Play Integrity for PC, इस फ़ील्ड में सेट की गई वैल्यू को, साइन किए गए इंटिग्रिटी रिस्पॉन्स में दिखा सकता है. 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 for PC के लिए अनुरोध करता है और कॉल पूरा नहीं होता है, तो आपके गेम को गड़बड़ी का कोड मिलता है. ये गड़बड़ियां कई वजहों से हो सकती हैं. जैसे, एनवायरमेंट से जुड़ी समस्याएं (जैसे कि नेटवर्क कनेक्शन खराब होना), एपीआई इंटिग्रेशन में समस्याएं या दुर्भावनापूर्ण गतिविधि और चालू हमले.

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

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

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

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

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

अपने ऐप्लिकेशन में, 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. अनुरोध प्रोसेस होने के बाद, आपको सूचना दी जाएगी. साथ ही, टेस्ट करने वाले उपयोगकर्ताओं को, टेस्ट के लिए पहले से तय किए गए इंटिग्रिटी की जांच के नतीजे पाने के लिए, अनुमति वाली सूची में शामिल किया जाएगा.