بدء استخدام ميزة "فحص التطبيق" مع ميزة Play Integrity على نظام Android

توضّح هذه الصفحة كيفية تفعيل ميزة App Check في تطبيق Android باستخدام موفّر Play Integrity المضمّن. عند تفعيل ميزة App Check، يمكنك المساعدة في ضمان عدم إمكانية وصول أي تطبيق آخر غير تطبيقك إلى موارد الخلفية في مشروعك. يمكنك الاطّلاع على نظرة عامة حول هذه الميزة.

يتوافق موفّر Play Integrity مع تطبيقات Android المنشورة على Google Play أو خارجه أو كليهما. إذا كانت حالة الاستخدام تتطلّب ميزات Play Integrity غير متوفّرة في App Check، أو إذا كنت تريد استخدام App Check مع موفّر مخصّص، يمكنك الاطّلاع على مقالة تنفيذ موفّر مخصّص لـ App Check.

1. إعداد مشروع Firebase

1. أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك.

2. فعِّل Play Integrity API:

   1. في Google Play Console، اختَر تطبيقك أو أضِفه إذا لم يسبق لك إجراء ذلك.

   2. في قسم الإصدار ، انقر على سلامة التطبيق.

   3. انتقِل إلى قسم Play Integrity API في الصفحة، وانقر على ربط مشروع على السحابة الإلكترونية، ثم اختَر مشروع Firebase الخاص بك من قائمة مشاريع Google Cloud. يجب أن يكون المشروع الذي تختاره هنا هو مشروع Firebase نفسه الذي تسجِّل فيه تطبيقك (راجِع الخطوة التالية).

      يجب أن تكون مالكًا للمشروع الذي تريد ربطه. يُرجى العِلم أنّ كونك عضوًا في مجموعة تم تعيين دور "المالك" لها لا يكفي.

3. في Firebase Console، انتقِل إلى الأمان > فحص التطبيقات.

4. في علامة التبويب التطبيقات ، سجِّل تطبيقاتك لاستخدام App Check مع موفّر Play Integrity. عليك تقديم الملف المرجعي لشهادة توقيع تطبيقك باستخدام معيار SHA-256.

   عليك عادةً تسجيل جميع تطبيقات مشروعك، لأنّه بعد تفعيل التنفيذ لأحد منتجات Firebase، لن تتمكّن سوى التطبيقات المسجّلة من الوصول إلى موارد الخلفية في المنتج.

5. اختياري: في إعدادات تسجيل التطبيق، اضبط مدة بقاء مخصّصة (TTL) لرموز التحقّق من التطبيق التي يصدرها الموفّر.App Check يمكنك ضبط مدة البقاء على أي قيمة تتراوح بين 30 دقيقة و7 أيام. عند تغيير هذه القيمة، يُرجى العِلم بالمقايضات التالية:

   • الأمان: توفّر مدة البقاء الأقصر أمانًا أقوى، لأنّها تقلّل الفترة التي يمكن للمهاجم فيها إساءة استخدام رمز مسرّب أو تم اعتراضه.
   • الأداء: تعني مدة البقاء الأقصر أنّ تطبيقك سيجري عملية إثبات الهوية بشكل متكرّر أكثر. بما أنّ عملية إثبات هوية التطبيق تضيف وقت استجابة لطلبات الشبكة في كل مرة يتم فيها تنفيذها، يمكن أن تؤثّر مدة البقاء القصيرة في أداء تطبيقك.
   • الحصة والتكلفة: تؤدي مدة البقاء الأقصر وعمليات إعادة إثبات الهوية المتكرّرة إلى استنفاد حصتك بشكل أسرع، وقد تزيد التكلفة المحتملة للخدمات المدفوعة. يمكنك الاطّلاع على مقالة الحصص والحدود.

   تُعدّ مدة البقاء التلقائية البالغة ساعة واحدة مناسبة لمعظم التطبيقات. يُرجى العِلم أنّ مكتبة App Check تُجدّد الرموز في نصف مدة البقاء تقريبًا.

ضبط الإعدادات المتقدّمة (اختياري)

App Check توفّر عددًا من الإعدادات التي تتيح حالات الاستخدام المتقدّمة، بما في ذلك توزيع تطبيقك خارج Google Play. بالنسبة إلى كل تطبيق من تطبيقات Android المسجّلة، يمكنك ضبط هذه الإعدادات في علامة التبويب App Check > التطبيقات في Firebase Console. ننصحك بضبط هذه الإعدادات وفقًا للجدول التالي عند تسجيل تطبيقك لأول مرة .

قناة توزيع تطبيقك	PLAY_RECOGNIZED	LICENSED	الحد الأدنى لمستوى سلامة الجهاز المقبول
حصريًا على Google Play	مطلوب	مطلوب	عدم التحقّق بشكل صريح من مستوى سلامة الجهاز
حصريًا خارج Google Play	غير مطلوب	غير مطلوب	سلامة الجهاز
على Google Play وخارجه	مطلوب	غير مطلوب	عدم التحقّق بشكل صريح من مستوى سلامة الجهاز

التفاصيل

يتوافق كل إعداد متقدّم مع بيان سلامة Play Integrity. يُرجى الرجوع إلى مستندات Play Integrity للحصول على تفاصيل إضافية.

• تتطلّب ميزة "التحقّق من التطبيق" بشكلٍ تلقائي App Checkتصنيف التعرّف على التطبيق.PLAY_RECOGNIZED لا تكون التطبيقات غير المنشورة على Google Play مؤهّلة لتلقّي هذا التصنيف.
• لا تتطلّب ميزة App Check بشكلٍ تلقائي تصنيف ترخيص التطبيق LICENSED. لا يكون مؤهّلاً لتلقّي هذا التصنيف سوى المستخدمين الذين ثبّتوا تطبيقك أو عدّلوا عليه مباشرةً من Google Play.

• لا تتحقّق ميزة App Check بشكلٍ تلقائي من نتيجة سلامة الجهاز. App Check تتيح التحقّق بشكلٍ صريح من مستويات سلامة الجهاز الثلاثة التالية، المدرَجة بترتيب زيادة سلامة الجهاز:

  ملاحظة: قد تجري Play Integrity عمليات تحقّق إضافية من سلامة الجهاز ضمنيًا أثناء تقييم نتائج سلامة أخرى، ولا يمكنك التحكّم مباشرةً في عمليات التحقّق الضمنية هذه، ولا تتأثر بهذا الإعداد.

  • فحص السلامة الأساسي : يؤدي ذلك إلى مطالبة App Check بتصنيف التعرّف على الجهاز.MEETS_BASIC_INTEGRITY لكي يكون تطبيقك مؤهّلاً لتلقّي هذا التصنيف الاختياري، عليك أولاً الموافقة عليه من Google Play Console.

    تحذير: بما أنّ مستخدمي Android 13 والإصدارات الأحدث الذين لا يثبّتون تطبيقك أو يعدّلون عليه من Google Play غير مؤهّلين لتلقّي هذا التصنيف، سيتم رفض وصولهم إذا لم يتمكّنوا من استيفاء متطلبات التصنيف الأقوى MEETS_DEVICE_INTEGRITY. ننصحك باستخدام هذا الإعداد فقط كأداة لتخفيف متطلبات سلامة الجهاز للمستخدمين الذين يثبّتون تطبيقك أو يعدّلون عليه من Google Play. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات Play Integrity.

  • سلامة الجهاز : يؤدي ذلك إلى مطالبة App Check بتصنيف التعرّف على الجهاز MEETS_DEVICE_INTEGRITY. تكون جميع التطبيقات مؤهّلة تلقائيًا لتلقّي هذا التصنيف.

  • سلامة صارمة : يؤدي ذلك إلى مطالبة App Check بتصنيف التعرّف على الجهاز.MEETS_STRONG_INTEGRITY لكي يكون تطبيقك مؤهّلاً لتلقّي هذا التصنيف الاختياري، عليك أولاً الموافقة عليه من Google Play Console.

    تحذير: بما أنّ مستخدمي Android 13 والإصدارات الأحدث الذين لا يثبّتون تطبيقك أو يعدّلون عليه من Google Play غير مؤهّلين لتلقّي هذا التصنيف، ننصحك باستخدام هذا الإعداد فقط إذا كان تطبيقك يتم توزيعه حصريًا باستخدام Google Play. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات Play Integrity.

2. إضافة مكتبة App Check إلى تطبيقك

في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً ما يكون <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة App Check لنظام Android. ننصحك باستخدام الـ Firebase Android BoM للتحكّم في تحديد إصدار المكتبة.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.12.0"))

    // Add the dependencies for the App Check libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-playintegrity")
}

باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام Android.

(بديل)  إضافة اعتماديات مكتبة Firebase بدون استخدام BoM

إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر الاعتمادية الخاص بها.

يُرجى العِلم أنّه إذا كنت تستخدم مكتبات متعددة من Firebase في تطبيقك، ننصحك بشدة باستخدام BoM لإدارة إصدارات المكتبة، ما يضمن توافق جميع الإصدارات.

dependencies {
    // Add the dependencies for the App Check libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-playintegrity:19.0.2")
}

3. تهيئة App Check

أضِف رمز التهيئة التالي إلى تطبيقك بحيث يتم تشغيله قبل استخدام أي حزمة تطوير برامج (SDK) أخرى من Firebase:

Kotlin

Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance(),
)
MainActivity.kt

Java

FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance());
MainActivity.java

الخطوات التالية

بعد تثبيت مكتبة App Check في تطبيقك، ابدأ بتوزيع التطبيق المعدَّل على المستخدمين.

سيبدأ تطبيق العميل المعدَّل بإرسال App Check رموز مميزة مع كل طلب يرسله إلى Firebase، ولكن لن تتطلّب منتجات Firebase أن تكون الرموز صالحة إلى أن تفعِّل التنفيذ في قسم App Check من وحدة تحكُّم Firebase.

مراقبة المقاييس وتفعيل التنفيذ

قبل تفعيل التنفيذ، عليك التأكّد من أنّ ذلك لن يؤدي إلى مقاطعة المستخدمين الشرعيين الحاليين. من ناحية أخرى، إذا كنت تلاحظ استخدامًا مشبوهًا لموارد تطبيقك، قد يكون من الأفضل تفعيل التنفيذ في وقت أقرب.

للمساعدة في اتخاذ هذا القرار، يمكنك الاطّلاع على مقاييس App Check للخدمات التي تستخدمها:

• مراقبة App Checkمقاييس الطلبات لـ Firebase AI Logic وSQL Connect وRealtime Database وCloud Firestore وCloud Storage وAuthentication وGoogle Identity for iOS وMaps JavaScript API وPlaces API (الجديدة).
• يمكنك مراقبة مقاييس طلبات App Check لـ Cloud Functions.

تفعيل التنفيذ في ميزة "App Check"

عندما تفهم كيف ستؤثر ميزة App Check في المستخدمين وتكون مستعدًا للمتابعة، يمكنك تفعيل التنفيذ في ميزة App Check:

• يمكنك تفعيل App Checkالتنفيذ لـ Firebase AI Logic وSQL Connect وRealtime Database وCloud Firestore وCloud Storage وAuthentication وGoogle Identity for iOS و‫Maps JavaScript API وPlaces API (الجديدة).
• يمكنك تفعيل App Check التنفيذ لـ Cloud Functions.

استخدام App Check في بيئات تصحيح الأخطاء

إذا أردت تشغيل تطبيقك في بيئة لا تصنّفها ميزة App Check عادةً على أنّها صالحة، مثل المحاكي أثناء التطوير أو من بيئة التكامل المستمر (CI)، يمكنك إنشاء إصدار مخصص لتصحيح الأخطاء من تطبيقك يستخدم موفّر تصحيح الأخطاء في ميزة App Check بدلاً من موفّر إثبات الهوية الحقيقي، وذلك بعد تسجيل تطبيقك في ميزة App Check.

يمكنك الاطّلاع على مقالة استخدام App Check مع موفّر تصحيح الأخطاء على Android.