تساعدك واجهة برمجة التطبيقات Play Integrity API لأجهزة الكمبيوتر في التحقّق من أنّ مصدر التفاعلات وطلبات الخادم هو جهاز كمبيوتر حقيقي. ومن خلال رصد عمليات التفاعل الخطيرة والاحتيالية المحتمَلة، يمكن لخادم الخلفية في تطبيقك الاستجابة من خلال اتّخاذ الإجراءات المناسبة لمنع الهجمات والحدّ من إساءة الاستخدام.
تعرض واجهة برمجة التطبيقات بيانات سلامة تساعدك في رصد التهديدات المحتملة، بما في ذلك:
- الأجهزة والبيئات الخطيرة: تساعدك
deviceIntegrityفي تحديد ما إذا كان تطبيقك يعمل على جهاز كمبيوتر حقيقي أو نسخة حقيقية من برنامج "ألعاب Google Play" على الكمبيوتر.
دمج واجهة برمجة التطبيقات
لدمج واجهة برمجة التطبيقات Play Integrity API للحاسوب في تطبيقك، عليك أولاً إجراء عملية الإعداد الأوّلية في Google Cloud Console. بعد ذلك، عليك اتّباع الخطوات التالية لكل عملية تحقّق من السلامة:
- تجهيز الرمز المميّز الخاص بالسلامة
- طلب رمز مميّز للتحقّق من السلامة
- طلب بيانات الرمز المميّز
الإعداد الأولي في Google Cloud Console
يجب أن يستخدم كل تطبيق أو حزمة SDK يستدعيان واجهة برمجة التطبيقات Play Integrity API مشروعًا على Google Cloud للمصادقة على طلباتهما وتتبُّع استخدام واجهة برمجة التطبيقات. إذا أردت إنشاء مشروع جديد على Cloud أو إذا كان تطبيقك متاحًا حصريًا خارج Google Play، يمكنك تفعيل ميزة الردود من Play Integrity API من Google Cloud Console.
في Google Cloud Console، أنشِئ مشروعًا جديدًا على Cloud أو اختَر مشروعًا حاليًا على Cloud تريد استخدامه مع Play Integrity 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. لإجراء ذلك، يُرجى إكمال الخطوات التالية:
- أنشئ حساب خدمة ضمن مشروع Google Cloud المرتبط بتطبيقك.
على خادم تطبيقك، اجلب رمز الدخول من بيانات اعتماد حساب الخدمة باستخدام نطاق playintegrity، وقدِّم الطلب التالي:
playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \ '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'قراءة استجابة 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",
}
ويجب أن تتطابق هذه القيم مع قيم الطلب الأصلي. لذلك، تحقَّق من الجزء
requestDetails من حمولة JSON من خلال التأكّد من أنّ
requestPackageName وrequestHash يتطابقان مع ما تم إرساله في الطلب الأصلي.
حقل سلامة الجهاز
يمكن أن يحتوي الحقل deviceIntegrity على قيمة واحدة،
deviceRecognitionVerdict، تتضمّن تصنيفًا واحدًا أو أكثر يوضّح مدى قدرة الجهاز على فرض سلامة التطبيق. إذا لم يستوفِ الجهاز معايير أي من التصنيفات، سيتم حذف deviceRecognitionVerdict من الحقل deviceIntegrity.
"deviceIntegrity": {
"deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
يمكن أن يتضمّن deviceRecognitionVerdict تلقائيًا ما يلي:
MEETS_PC_INTEGRITY- تعرض هذه الطريقة نتيجة إذا كان التطبيق يعمل في بيئة كمبيوتر حقيقية ولم يتم رصد أي تلاعب على الجهاز.
- فارغ (قيمة فارغة)
- يعمل التطبيق على جهاز يتضمّن علامات تشير إلى تعرُّضه للهجوم (مثل اعتراض طلبات البيانات من واجهة برمجة التطبيقات) أو اختراق نظامه (مثل تزويده بإذن الوصول إلى الجذر)، أو لا يعمل التطبيق على جهاز فعلي (مثل المحاكي الذي لا يجتاز عمليات التأكّد من السلامة في Google Play).
حدود الاستخدام
حدود استخدام Play Integrity API
سيخضع تطبيقك لحد أقصى يبلغ 10,000 طلب إجمالي لكل تطبيق في اليوم. يمكنك طلب زيادة هذا الحد الأقصى اليومي باتّباع التعليمات التالية إذا كان تطبيقك بحاجة إلى استيعاب عدد أكبر من المستخدمين.
| الإجراء | الحصة اليومية لكل تطبيق | Notes |
|---|---|---|
| طلبات الرموز المميزة | 10,000 | تتم مشاركتها بين واجهة برمجة التطبيقات Play Integrity API لأجهزة الكمبيوتر وواجهة برمجة التطبيقات Play Integrity API للطلبات الكلاسيكية والعادية. |
| فك تشفير الرموز المميزة على خوادم Google | 10,000 | تتم مشاركتها بين واجهة برمجة التطبيقات Play Integrity API على الكمبيوتر وواجهة برمجة التطبيقات Play Integrity API للطلبات الكلاسيكية والعادية. |
زيادة الحد الأقصى لعدد الطلبات اليومية
لكي يكون تطبيقك مؤهَّلاً لزيادة الحد الأقصى لعدد الطلبات اليومية، يجب أن يكون متاحًا على Google Play بالإضافة إلى أي قنوات توزيع أخرى.
لطلب زيادة الحد الأقصى لعدد الطلبات اليومية، اتّبِع الخطوات التالية:
- اربط مشروع Google Cloud الذي تستخدمه مع Play Integrity API في Play Console.
- تأكَّد من أنّك تنفّذ منطق واجهة برمجة التطبيقات بشكل صحيح، بما في ذلك إستراتيجية إعادة المحاولة المقترَحة.
- يمكنك طلب زيادة الحصة باستخدام هذا النموذج.
قد يستغرق رفع حصة واجهة برمجة التطبيقات Play Integrity API مدة تصل إلى أسبوع، لذا ننصحك بشدة بمراقبة استخدامك لواجهة برمجة التطبيقات Play Integrity API في Google Play Console أو في Google Cloud Console، حيث يمكنك أيضًا إعداد تنبيهات بشأن الحصة لتجنُّب حدوث انقطاعات في الخدمة.
يتم تطبيق الزيادات في الحصة تلقائيًا على كلّ من طلب العميل لإنشاء رموز مميّزة خاصة بالسلامة وطلب الخادم لفك تشفير الرموز المميّزة الخاصة بالسلامة والتحقّق منها.
اعتبارات الأمان
توفّر واجهة برمجة التطبيقات Play Integrity API أكبر قيمة لتطبيقك عند اتّباع الممارسات المقترَحة التالية:
وضع استراتيجية لمكافحة إساءة الاستخدام
تعمل واجهة برمجة التطبيقات Play Integrity API على أفضل نحو عند استخدامها إلى جانب إشارات أخرى كجزء من استراتيجيتك الشاملة لمكافحة إساءة الاستخدام، وليس كآلية وحيدة لمكافحة إساءة الاستخدام. استخدِم واجهة برمجة التطبيقات هذه مع أفضل ممارسات الأمان المناسبة الأخرى لتطبيقك. يمكن لتطبيقك تلقائيًا إرسال ما يصل إلى 10,000 طلب إجمالي يوميًا على مستوى جميع عمليات التثبيت. يمكنك طلب زيادة الحد الأقصى اليومي.
جمع بيانات القياس عن بُعد وفهم جمهورك قبل اتّخاذ أي إجراء
قبل تغيير طريقة عمل تطبيقك استنادًا إلى بيانات السلامة التي تقدّمها واجهة برمجة التطبيقات Play Integrity API، يمكنك التعرّف على الوضع الحالي لجمهورك الحالي من خلال تنفيذ واجهة برمجة التطبيقات بدون فرض أي قيود. بعد معرفة النتائج التي تحقّقها قاعدة التثبيت الحالية، يمكنك تقدير تأثير أي إجراء تنفيذي تخطّط له وتعديل استراتيجيتك لمكافحة إساءة الاستخدام وفقًا لذلك.
طلب بيان السلامة في الوقت المناسب
يجب تقديم طلبات إلى واجهة برمجة التطبيقات في أقرب وقت ممكن من وقت الإجراء أو طلب الخادم الذي تريد حمايته.
جعل طلبات البيانات من واجهة برمجة التطبيقات صعبة التكرار
تتضمّن طلبات البيانات من واجهة برمجة التطبيقات حقل requestHash يُستخدَم للحماية من التلاعب والهجمات المشابهة. في هذا الحقل، يجب تضمين ملخّص لجميع القيم ذات الصلة من طلب تطبيقك. اتّبِع الإرشادات حول كيفية استخدام ربط المحتوى لحماية الطلبات العادية في تطبيقك.
تجنُّب تخزين بيانات السلامة مؤقتًا
تزيد بيانات سلامة الجهاز المخزَّنة مؤقتًا من خطر استخدام الخوادم الوكيلة، وهو نوع من الهجمات يعيد فيه المخترق استخدام بيانات من جهاز سليم لأغراض مسيئة في بيئة أخرى.
إرسال مجموعة من الردود من الخادم إلى تطبيقك
من الصعب تكرار مجموعة من نتائج القرارات مقارنةً بإرسال ردّ ثنائي (سماح أو رفض) من الخادم إلى التطبيق لكل ردّ. على سبيل المثال، يمكنك استخدام سلسلة من الردود ذات الصلة، مثل "السماح" و"السماح مع فرض قيود" و"السماح مع فرض قيود بعد إكمال اختبار CAPTCHA" و"الرفض".
عرض رسائل الخطأ التي تتضمّن إجراءات
عند الإمكان، قدِّم رسائل خطأ مفيدة للمستخدم وأخبِره بالإجراءات التي يمكنه اتّخاذها لحلّ المشكلة.
وضع خطة للمشاكل أو الانقطاعات غير المتوقّعة
تعرض لوحة البيانات الخاصة بالحالة في Play معلومات حول حالة خدمة Play Integrity API، بالإضافة إلى معلومات حول أي أعطال أو انقطاعات. عليك التخطيط مسبقًا لطريقة عمل خادم الخلفية في حال حدوث انقطاع واسع النطاق في واجهة برمجة التطبيقات Play Integrity API، وهو أمر غير محتمل.
بنود الخدمة وأمان البيانات
يعني وصولك إلى واجهة برمجة التطبيقات Play Integrity API للحاسوب أو استخدامك لها أنّك توافق على بنود خدمة واجهة برمجة التطبيقات Play Integrity API. يجب قراءة جميع الأحكام والسياسات السارية وفهمها قبل استخدام واجهة برمجة التطبيقات.
يتضمّن Google Play قسم "أمان البيانات" الذي يتيح للمطوّرين الإفصاح عن ممارسات جمع البيانات ومشاركتها والحفاظ على أمانها في تطبيقاتهم لإبقاء المستخدمين على اطّلاع دائم. لمساعدتك في إكمال نموذج البيانات، يمكنك الاطّلاع على هذه المعلومات حول طريقة تعامل واجهة برمجة التطبيقات Play Integrity API مع البيانات.