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

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

پیش نیازها

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

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

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

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

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

گرم کردن 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 برای 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();
}

مرحله 3: رمزگشایی و تأیید توکن های یکپارچگی در سرور باطن بازی خود در مرحله بعد

رمز یکپارچگی را رمزگشایی کنید

پس از درخواست حکم یکپارچگی، 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"
    ]
  },
}

رمز یکپارچگی را تأیید کنید

فیلد requestDetails کد یکپارچگی رمزگشایی شده حاوی اطلاعات مربوط به درخواست، از جمله اطلاعات ارائه شده توسط توسعه دهنده در requestHash است.

فیلدهای requestHash و packageName باید با درخواست اصلی مطابقت داشته باشند. بنابراین، همانطور که در قطعه کد زیر نشان داده شده است، با اطمینان از مطابقت requestPackageName و requestHash با آنچه در درخواست اصلی ارسال شده است، قسمت requestDetails از بار JSON را تأیید کنید:

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.

مرحله 4: تصمیم بگیرید که بر اساس حکم یکپارچگی چه اقدامی انجام دهید

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

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

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

MEETS_PC_INTEGRITY

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

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

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

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

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

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

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

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

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

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