Play Integrity API را اضافه کنید

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

API احکامی را برمی‌گرداند که به شما در شناسایی تهدیدهای بالقوه کمک می‌کند، از جمله:

  • دستگاه‌ها و محیط‌های مخاطره‌آمیز: حکم deviceIntegrity به شما کمک می‌کند تعیین کنید که آیا برنامه شما روی یک دستگاه رایانه شخصی واقعی اجرا می‌شود یا یک نمونه واقعی از بازی‌های Google Play برای رایانه شخصی.

ادغام با API

برای ادغام Play Integrity API برای رایانه شخصی در برنامه خود، ابتدا باید تنظیمات اولیه را در Google Cloud Console انجام دهید. پس از آن، برای هر بررسی یکپارچگی باید مراحل زیر را دنبال کنید:

  1. نشانه صداقت خود را آماده کنید
  2. رمز صداقت خود را درخواست کنید
  3. اطلاعات رمز را درخواست کنید

راه اندازی اولیه در Google Cloud Console

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

در Google Cloud Console خود، یک پروژه Cloud جدید ایجاد کنید یا یک پروژه Cloud موجود را انتخاب کنید که می‌خواهید با Play Integrity API برای رایانه شخصی استفاده کنید. به API ها و سرویس ها بروید. فعال کردن API ها و خدمات را انتخاب کنید. Play Integrity API را جستجو کنید و سپس آن را فعال کنید . اکنون می توانید Play Integrity API را در برنامه خود ادغام کنید.

مرحله 1: توکن یکپارچگی خود را آماده کنید 

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

قبل از درخواست رمز یکپارچگی (به RequestIntegrityToken مراجعه کنید)، باید Play Integrity API را آماده کنید (یا "گرم کنید"). این به Google Play اجازه می‌دهد تا به‌طور هوشمندانه اطلاعات گواهی جزئی را در دستگاه ذخیره کند تا در هنگام درخواست حکم یکپارچگی، تأخیر را در مسیر بحرانی کاهش دهد.

در صورت موفقیت، ادامه با یک PrepareIntegrityTokenResultValue شامل RequestTokenData فراخوانی می‌شود که باید برای درخواست توکن یکپارچگی استفاده شود. این داده ها باید در حافظه پنهان شوند و در طول جلسه برنامه برای تماس با RequestIntegrityToken مجددا استفاده شوند. فقط در صورتی که درخواست شما تشخیص دهد که ارزیابی مجدد کامل حکم یکپارچگی ضروری است، باید با PrepareIntegrityToken تماس بگیرید.

جزئیات
پارامترها params : پارامترهای حاوی شماره پروژه Google Cloud.
continuation : پاسخ تماس غیرهمگام برای بازگرداندن ارائه‌دهنده توکن یکپارچگی به.

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

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

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

  • دستگاه اصلی: تعیین کنید که آیا برنامه شما روی دستگاه اصلی اجرا می‌شود که حاوی نمونه‌ای از بازی‌های Google Play برای رایانه شخصی است و دستکاری نشده است.

هنگامی که در حال بررسی یک عملکرد کاربر در برنامه خود با Play Integrity API برای رایانه شخصی هستید، می توانید از قسمت RequestIntegrityTokenParams::request_hash برای کاهش حملات دستکاری استفاده کنید. برای مثال، ممکن است یک بازی بخواهد امتیاز بازیکن را به سرور باطن بازی گزارش کند و سرور شما بخواهد تأیید کند که این امتیاز توسط یک سرور پراکسی دستکاری نشده است. Play Integrity API مقداری را که در این قسمت تنظیم کرده‌اید، در داخل پاسخ یکپارچگی امضا شده برمی‌گرداند. بدون requestHash ، توکن یکپارچگی فقط به دستگاه محدود می شود، اما نه به درخواست خاص، که امکان حمله را باز می کند.

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

  • خلاصه ای از تمام پارامترهای درخواست مربوطه (به عنوان مثال SHA256 یک سریال سازی درخواست پایدار) را از اقدام کاربر یا درخواست سرور که در حال انجام است، محاسبه کنید.
  • قسمت RequestIntegrityTokenParams::request_hash را روی خلاصه تنظیم کنید.
جزئیات
پارامترها params : پارامترهای حاوی RequestTokenData آماده شده و هش درخواست بررسی یکپارچگی.
continuation : پاسخ تماس غیرهمگام برای بازگشت داده ها به.

مرحله 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": { ... },
  "deviceIntegrity": { ... },
}

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

فیلد جزئیات درخواست

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

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

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

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

فیلد deviceIntegrity می‌تواند حاوی یک مقدار واحد باشد، deviceRecognitionVerdict ، که دارای یک یا چند برچسب است که نشان می‌دهد دستگاه چقدر می‌تواند یکپارچگی برنامه را اعمال کند. اگر دستگاهی با معیارهای هیچ یک از برچسب ها مطابقت نداشته باشد، فیلد deviceIntegrity deviceRecognitionVerdict حذف می کند.

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

به طور پیش فرض، deviceRecognitionVerdict می تواند شامل موارد زیر باشد:

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

محدودیت های استفاده

Play Integrity API Usage Limits

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

اقدام سهمیه روزانه در هر برنامه یادداشت ها
درخواست های توکن 10000 بین Play Integrity API برای رایانه شخصی و همچنین Play Integrity API برای درخواست های کلاسیک و استاندارد به اشتراک گذاشته شده است
رمزگشایی توکن در سرورهای گوگل 10000 بین Play Integrity API برای رایانه شخصی و همچنین Play Integrity API برای درخواست های کلاسیک و استاندارد به اشتراک گذاشته شده است

حداکثر تعداد درخواست های روزانه خود را افزایش دهید

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

برای درخواست افزایش حداکثر تعداد درخواست‌های روزانه، موارد زیر را انجام دهید:

  1. پروژه Google Cloud را که برای Play Integrity API در Play Console استفاده می‌کنید پیوند دهید.
  2. بررسی کنید که منطق API را به درستی اجرا می کنید، از جمله استراتژی توصیه شده برای امتحان مجدد.
  3. با استفاده از این فرم درخواست افزایش سهمیه کنید.

افزایش سهمیه Play Integrity API ممکن است تا یک هفته طول بکشد، بنابراین ما قویاً توصیه می‌کنیم استفاده از Play Integrity API خود را در کنسول Google Play یا کنسول Google Cloud خود نظارت کنید، جایی که می‌توانید هشدارهای سهمیه را نیز تنظیم کنید تا از وقفه در سرویس خود جلوگیری کنید.

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

ملاحظات امنیتی

Play Integrity API بیشترین ارزش را برای برنامه شما فراهم می کند که این روش های توصیه شده را دنبال کنید:

یک استراتژی ضد سوء استفاده داشته باشید

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

قبل از اقدام، تله متری را جمع آوری کنید و مخاطبان خود را درک کنید

قبل از اینکه نحوه رفتار برنامه خود را بر اساس احکام Play Integrity API تغییر دهید، می‌توانید با اجرای API بدون اعمال، وضعیت فعلی مخاطبان فعلی خود را درک کنید. هنگامی که بدانید پایگاه نصب فعلی شما چه احکامی را برمی‌گرداند، می‌توانید تأثیر هر اجرایی را که در حال برنامه‌ریزی هستید تخمین بزنید و استراتژی ضد سوء استفاده خود را بر اساس آن تنظیم کنید.

در یک لحظه مناسب حکم صداقت را درخواست کنید

شما باید درخواست های API را تا حد امکان به زمان اقدام یا درخواست سروری که می خواهید از آن دفاع کنید نزدیک کنید.

درخواست های API خود را به سختی تکرار کنید

درخواست های API دارای فیلدی به نام requestHash هستند که برای محافظت در برابر دستکاری و حملات مشابه استفاده می شود. در این فیلد، باید خلاصه ای از تمام مقادیر مربوطه را از درخواست برنامه خود وارد کنید. دستورالعمل نحوه استفاده از محتوای الزام آور برای محافظت از درخواست های استاندارد برنامه خود را دنبال کنید.

از ذخیره کردن احکام یکپارچگی خودداری کنید

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

طیف وسیعی از پاسخ ها را از سرور خود به برنامه خود ارسال کنید

تکرار کردن طیف وسیعی از نتایج تصمیم دشوارتر از ارسال پاسخ باینری Allow / Deny از سرور به برنامه برای هر پاسخ است. برای مثال، می‌توانید از یک سری پاسخ‌های مرتبط مانند Allow، Allow with limits، Allow with limits پس از تکمیل CAPTCHA و Deny استفاده کنید.

نمایش پیام های خطای قابل اجرا

در صورت امکان، پیام های خطای مفیدی را به کاربر ارائه دهید و به او اطلاع دهید که برای رفع آن چه کاری می تواند انجام دهد.

برای مسائل غیر منتظره یا قطعی برنامه داشته باشید

داشبورد وضعیت Play اطلاعاتی درباره وضعیت سرویس Play Integrity API به همراه اطلاعاتی درباره هرگونه اختلال و قطعی نشان می‌دهد. شما باید از قبل برنامه‌ریزی کنید که می‌خواهید سرور باطن شما در مواقع غیر محتمل قطع شدن Play Integrity API در مقیاس بزرگ چگونه کار کند.

شرایط خدمات و ایمنی داده ها

با دسترسی یا استفاده از Play Integrity API برای رایانه شخصی، با شرایط خدمات Play Integrity API موافقت می کنید. قبل از دسترسی به API همه شرایط و خط مشی های قابل اجرا را بخوانید و درک کنید.

Google Play یک بخش ایمنی داده برای توسعه دهندگان دارد تا جمع‌آوری داده‌ها، اشتراک‌گذاری و شیوه‌های امنیتی برنامه‌های خود را افشا کنند تا کاربران شما را مطلع کنند. برای کمک به تکمیل فرم داده خود، این اطلاعات را در مورد نحوه مدیریت API Play Integrity مشاهده کنید.