Play Integrity برای رایانه شخصی را در برنامه خود ادغام کنید

Play Integrity برای کامپیوتر به شما کمک می‌کند تا بررسی کنید که رویدادهای بازی و درخواست‌های سرور از یک نمونه واقعی از Google Play Games برای کامپیوتر روی یک دستگاه کامپیوتر واقعی می‌آیند. با شناسایی دستگاه‌های بالقوه خطرناک و شبیه‌سازهای ناشناخته، سرور پشتیبان بازی شما می‌تواند با اقدامات مناسب برای جلوگیری از تقلب، دسترسی غیرمجاز، ترافیک جعلی و سوءاستفاده واکنش نشان دهد.

پیش‌نیازها

• تنظیمات SDK را کامل کنید.
• ملاحظات امنیتی مربوط به یکپارچگی API را بررسی کنید.
• شرایط خدمات و اطلاعات مربوط به مدیریت داده‌ها در رابط برنامه‌نویسی کاربردی Integrity را مطالعه و درک کنید.
• در کنسول گوگل کلود خود، یک پروژه ابری ایجاد کنید یا یک پروژه ابری موجود را که می‌خواهید با Play Integrity برای کامپیوتر استفاده کنید، انتخاب کنید. به APIها و خدمات بروید و Google Play Integrity API را فعال کنید .
• اگر انتظار دارید روزانه بیش از 10 هزار درخواست Play Integrity برای کامپیوتر شخصی داشته باشید، باید درخواست افزایش حداکثر روزانه خود را بدهید.

مرحله ۱: تصمیم بگیرید که چگونه از Play Integrity برای کامپیوتر در بازی خود استفاده خواهید کرد

تصمیم بگیرید چه زمانی با Play Integrity برای کامپیوتر شخصی تماس می‌گیرید تا حکمی در مورد یکپارچگی محیط دریافت کنید. به عنوان مثال، می‌توانید هنگام باز شدن بازی، ورود بازیکن یا پیوستن بازیکن به یک بازی چند نفره، درخواست حکم کنید. سپس تصمیم بگیرید که چگونه پاسخ‌های مختلف یکپارچگی را مدیریت خواهید کرد. به عنوان مثال، می‌توانید:

• پاسخ را بدون هیچ گونه اقدام اجرایی جمع‌آوری کنید و داده‌ها را به صورت داخلی تجزیه و تحلیل کنید تا بفهمید که آیا این یک نشانه مفید از سوءاستفاده است یا خیر.
• پاسخ را جمع‌آوری کنید و منطق را روی سرور backend خود پیاده‌سازی کنید تا به دستگاه‌هایی که حکم‌های یکپارچگی را صادر می‌کنند، اجازه دهید بازی شما را به طور عادی اجرا کنند، در حالی که دسترسی به ترافیکی که از محیط‌های مشکوک می‌آید را به چالش می‌کشند یا رد می‌کنند.
• پاسخ را جمع‌آوری کنید و منطق را در backend خود پیاده‌سازی کنید تا پخش‌کننده‌ها را روی دستگاه‌هایی که بررسی‌های یکپارچگی را با هم پشت سر می‌گذارند، مطابقت دهید، در حالی که ترافیک ورودی از محیط‌های مشکوک را با هم تطبیق می‌دهید.

مرحله ۲: درخواست توکن‌های یکپارچگی در بازی خود

بازی Integrity را برای کامپیوتر گرم کنید

آماده‌سازی (یا «گرم کردن») Play Integrity برای کامپیوتر، که به گوگل پلی اجازه می‌دهد تا به طور هوشمندانه اطلاعات گواهی جزئی را در دستگاه ذخیره کند تا تأخیر در مسیر بحرانی را هنگام درخواست حکم یکپارچگی کاهش دهد. می‌توانید این کار را به صورت غیرهمزمان به محض باز شدن بازی خود انجام دهید تا بتوانید در صورت نیاز درخواست‌های یکپارچگی درخواستی را ارسال کنید.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

در صورت موفقیت، ادامه با یک PrepareIntegrityTokenResultValue حاوی RequestTokenData که باید برای درخواست توکن یکپارچگی استفاده شود، فراخوانی می‌شود. این داده‌ها باید در حافظه پنهان (cache) شوند و در طول جلسه برنامه برای فراخوانی‌های 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 برای کاهش حملات دستکاری استفاده کنید. به عنوان مثال، ممکن است بخواهید امتیاز بازیکن را به سرور backend بازی خود گزارش دهید و سرور شما می‌خواهد تأیید کند که این امتیاز توسط یک سرور پروکسی دستکاری نشده است. Play Integrity برای کامپیوتر می‌تواند مقداری را که در این فیلد تنظیم کرده‌اید، درون پاسخ یکپارچگی امضا شده، برگرداند. بدون requestHash، توکن یکپارچگی فقط به دستگاه متصل می‌شود، اما به درخواست خاص متصل نمی‌شود، که این امر احتمال حمله را افزایش می‌دهد.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

برای کاهش احتمال حمله، هنگام درخواست حکم یکپارچگی:

• خلاصه‌ای از تمام پارامترهای درخواست مربوطه (مثلاً SHA256 مربوط به سریال‌سازی درخواست پایدار) را از اقدام کاربر یا درخواست سرور که در حال رخ دادن است، محاسبه کنید.
• فیلد RequestIntegrityTokenParams::request_hash را روی digest تنظیم کنید.

قطعه کدی که نحوه فراخوانی اکشن 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 یک توکن پاسخ رمزگذاری شده ارائه می‌دهد. برای دریافت احکام یکپارچگی دستگاه، باید توکن یکپارچگی را در سرورهای گوگل رمزگشایی کنید:

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 باید با فیلدهای درخواست اصلی مطابقت داشته باشند. بنابراین، با اطمینان از اینکه requestPackageName و requestHash با آنچه در درخواست اصلی ارسال شده است، مطابقت دارند، بخش requestDetails از JSON payload را بررسی کنید، همانطور که در قطعه کد زیر نشان داده شده است:

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 مجوز دریافت کرده است یا خیر، استفاده کنید. سرور backend بازی شما می‌تواند این اطلاعات را جمع‌آوری کرده و از آن برای تعیین اینکه بازی شما چه اقدامی باید انجام دهد، مانند اجازه دادن به ادامه یک رویداد بازی یا عدم دسترسی به ترافیک پرخطر، استفاده کند.

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

احکام مربوط به سلامت دستگاه

deviceRecognitionVerdict می‌تواند مقادیر زیر را داشته باشد:

MEETS_PC_INTEGRITY

این بازی بر روی یک محیط واقعی کامپیوتر شخصی اجرا می‌شود، که در آن هیچ دستکاری روی دستگاه شناسایی نشده است.

خالی (یک مقدار خالی)

بازی روی دستگاهی اجرا می‌شود که نشانه‌هایی از حمله (مانند اتصال API) یا نفوذ به سیستم (مانند دستگاهی که نسخه دستکاری‌شده سرویس‌های دسکتاپ گوگل را اجرا می‌کند) دارد، یا برنامه روی دستگاه فیزیکی اجرا نمی‌شود (مانند شبیه‌ساز که از بررسی‌های یکپارچگی گوگل پلی سربلند بیرون نمی‌آید).

احکام مربوط به جزئیات حساب

appLicensingVerdict می‌تواند مقادیر زیر را داشته باشد:

LICENSED

کاربر دارای حق استفاده از برنامه است. به عبارت دیگر، کاربر برنامه شما را از گوگل پلی روی دستگاه خود نصب یا به‌روزرسانی کرده است.

UNLICENSED

کاربر مجوز برنامه ندارد. این اتفاق زمانی می‌افتد که، برای مثال، کاربر برنامه شما را از طریق دانلود جانبی دانلود می‌کند یا آن را از گوگل پلی دریافت نمی‌کند.

UNEVALUATED

جزئیات مجوز ارزیابی نشد زیرا یک الزام ضروری از قلم افتاده بود. این امر می‌تواند به دلایل مختلفی از جمله موارد زیر اتفاق بیفتد:

• دستگاه به اندازه کافی قابل اعتماد نیست.
• نسخه برنامه نصب شده روی دستگاه شما برای گوگل پلی ناشناخته است.
• کاربر وارد گوگل پلی نشده است.

مرحله ۵: مدیریت کدهای خطا

اگر بازی شما درخواست Play Integrity for PC را ارسال کند و درخواست با شکست مواجه شود، بازی شما یک کد خطا دریافت می‌کند. این خطاها می‌توانند به دلایل مختلفی مانند مشکلات محیطی مانند اتصال ضعیف شبکه، مشکلات مربوط به ادغام API شما یا فعالیت‌های مخرب و حملات فعال رخ دهند.

کدهای خطای قابل امتحان مجدد

علت این خطاها گاهی اوقات به دلیل شرایط گذرا است و بنابراین باید فراخوانی را با یک استراتژی بازگشت نمایی دوباره امتحان کنید.

برای توصیه‌های بیشتر در مورد استراتژی‌های تلاش مجدد ، اینجا را ببینید.

کدهای خطای غیرقابل تکرار

بعید است که تلاش‌های مجدد خودکار در این موارد کمکی کنند. با این حال، اگر کاربر شرایطی را که باعث ایجاد مشکل شده است، برطرف کند، یک تلاش مجدد دستی ممکن است مفید باشد.

پاسخ‌های مختلف Play Integrity API را در برنامه خود آزمایش کنید

شما می‌توانید تست‌هایی برای ارزیابی نحوه تعامل Play Integrity API با برنامه خود ایجاد کنید.

1. یک گروه گوگل (یا هر تعداد که می‌خواهید) با آدرس‌های ایمیل کاربران ایجاد کنید. می‌توانید احکام مربوط به یکپارچگی یا کد خطایی را که این کاربران باید از سرورهای گوگل پلی در برنامه شما دریافت کنند، انتخاب کنید. این به شما امکان می‌دهد نحوه واکنش برنامه خود را به همه پاسخ‌ها و خطاهای ممکن آزمایش کنید.

2. اینجا یک تیکت ایجاد کنید و گزارش دهید که کدام گروه گوگل، کدام پاسخ API را دریافت خواهد کرد. هر گروه برای دریافت یکی از گزینه‌های زیر تعیین شده است:

   	صدور حکم صدور مجوز	صدور حکم عدم صدور مجوز	قادر به ارزیابی حکم صدور مجوز نیست
   عبور از یکپارچگی دستگاه	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

   اگر در صدور حکم یکپارچگی دستگاه رد شوید، حکم صدور مجوز همیشه «ارزیابی نشده» (UNEVALUATE) را برمی‌گرداند.

3. پس از پردازش درخواست و قرار گرفتن کاربران آزمایشی در لیست مجاز برای دریافت احکام از پیش تعریف شده برای تست، به شما اطلاع داده خواهد شد.