اختيار النظام الأساسي: Android iOS JavaScript

استخدام ميزة "فحص التطبيقات" لتأمين مفتاح واجهة برمجة التطبيقات

توفر ميزة "فحص التطبيقات" من Firebase الحماية للطلبات التي يرسلها تطبيقك إلى "منصة خرائط Google" من خلال حظر الزيارات الواردة من مصادر أخرى غير التطبيقات المشروعة. ويتم ذلك من خلال التحقّق من وجود رمز مميّز من أحد مقدّمي خدمات المصادقة، مثل Play Integrity. يساعد دمج تطبيقاتك مع ميزة "فحص التطبيقات" في الحماية من الطلبات الضارة، وبالتالي لن يتم تحصيل رسوم منك مقابل طلبات واجهة برمجة التطبيقات غير المصرّح بها.

هل ميزة "فحص التطبيقات" مناسبة لي؟

ننصح باستخدام ميزة "فحص التطبيقات" في معظم الحالات، ولكنّها ليست ضرورية أو غير متاحة في الحالات التالية:

• إذا كنت تستخدم حزمة تطوير البرامج الأصلية (SDK) لمنصة الأماكن. لا تتوافق ميزة "فحص التطبيقات" إلا مع حزمة تطوير البرامج (SDK) الجديدة لمنصة الأماكن.
• التطبيقات الخاصة أو التجريبية إذا لم يكن تطبيقك متاحًا للجميع، لن تحتاج إلى ميزة "فحص التطبيقات".
• إذا كان تطبيقك يُستخدم فقط من خادم إلى خادم، لن تحتاج إلى ميزة "فحص التطبيقات". ومع ذلك، إذا كان الخادم الذي يتواصل مع "منصة خرائط Google" يستخدمه عملاء متاحون للجميع (مثل تطبيقات الأجهزة الجوّالة)، ننصحك بـ استخدام ميزة "فحص التطبيقات" لحماية هذا الخادم بدلاً من "منصة خرائط Google".
• لن تعمل خدمات المصادقة المقترَحة في ميزة "فحص التطبيقات" على الأجهزة التي يعتبرها مقدّم خدمة المصادقة غير جديرة بالثقة أو تم اختراقها. إذا كنت بحاجة إلى توفير الدعم لهذه الأجهزة، يمكنك نشر خدمة مصادقة مخصّصة. لمزيد من المعلومات، يُرجى الاطّلاع على الـ تعليمات.

نظرة عامة على خطوات التنفيذ

في ما يلي الخطوات التي يجب اتّباعها لدمج تطبيقك مع ميزة "فحص التطبيقات":

1. إضافة Firebase إلى تطبيقك
2. إضافة مكتبة "فحص التطبيقات" وتهيئتها
3. إضافة مقدّم الرموز المميّزة
4. تفعيل تصحيح الأخطاء
5. مراقبة طلبات تطبيقك وتحديد خيارات الفرض

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

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

ملاحظة: لا يتم تفعيل خيارات الفرض في ميزة "فحص التطبيقات" تلقائيًا.

اعتبارات يجب مراعاتها عند التخطيط لعملية دمج ميزة "فحص التطبيقات"

في ما يلي بعض النقاط التي يجب مراعاتها أثناء التخطيط لعملية الدمج:

• يفرض مقدّم خدمة المصادقة الذي ننصح به، وهو Play Integrity، حدًا أقصى يوميًا لعدد طلبات فئة الاستخدام "واجهة برمجة التطبيقات العادية". لمزيد من المعلومات عن الحدود القصوى لعدد الطلبات، يُرجى الاطّلاع على صفحة الإعداد في مستندات المطوّرين في Google Play Integrity.

  يمكنك أيضًا اختيار استخدام مقدّم خدمة مصادقة مخصّص، على الرغم من أنّ هذه حالة استخدام متقدّمة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تنفيذ مقدّم خدمة مخصّص لميزة "فحص التطبيقات".

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

  تحدّد المدة التي يكون فيها الرمز المميّز من ميزة "فحص التطبيقات" صالحًا (مدة البقاء أو TTL) عدد مرات إعادة المصادقة. يمكن ضبط هذه المدة في وحدة تحكّم Firebase. تحدث عملية إعادة المصادقة عند انقضاء نصف مدة البقاء تقريبًا. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Firebase لمقدّم خدمة المصادقة.

دمج تطبيقك مع ميزة "فحص التطبيقات"

ملاحظة: يمكنك الحصول على المساعدة بشكل أسرع. للحصول على الدعم بشأن الأجزاء المتعلّقة بـ Firebase في هذه العملية، يُرجى الاطّلاع على مقالة دعم Firebase. للحصول على الدعم بشأن حزمة تطوير البرامج (SDK) لمنصة Google Places لأجهزة Android، يُرجى الاطّلاع على مقالة دعم "منصة خرائط Google".

المتطلّبات الأساسية

• تطبيق تم دمج حزمة تطوير البرامج (SDK) لمنصة الأماكن الإصدار 4.1 أو إصدار أحدث فيه
• بصمة إصبع SHA-256 لتطبيقك
• اسم حزمة تطبيقك
• يجب أن تكون مالك التطبيق في Cloud Console.
• ستحتاج إلى رقم تعريف مشروع التطبيق من Cloud Console

الخطوة 1: إضافة Firebase إلى تطبيقك

يُرجى اتّباع التعليمات الواردة في مستندات المطوّرين في Firebase لإضافة Firebase إلى تطبيقك.

الخطوة 2: إضافة مكتبة "فحص التطبيقات" وتهيئة ميزة "فحص التطبيقات"

للحصول على معلومات عن استخدام Play Integrity، وهو مقدّم خدمة المصادقة التلقائي، يُرجى الاطّلاع على مقالة بدء استخدام ميزة "فحص التطبيقات" مع Play Integrity على Android.

1. يُرجى دمج حزمة تطوير البرامج (SDK) لمنصة الأماكن في تطبيقك إذا لم يسبق لك إجراء ذلك.

2. بعد ذلك، عليك تهيئة ميزة "فحص التطبيقات" وعميل الأماكن.

   // Initialize App Check
   FirebaseApp.initializeApp(/* context= */ this);
   FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
   firebaseAppCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance());
     
   // Initialize Places SDK
   Places.initializeWithNewPlacesApiEnabled(context, API_KEY);
   PlacesClient client = Places.createClient(context);.

الخطوة 3: إضافة مقدّم الرموز المميّزة

بعد تهيئة Places API، عليك استدعاء setPlacesAppCheckTokenProvider() لضبط PlacesAppCheckTokenProvider.

Places.initializeWithNewPlacesApiEnabled(context, API_KEY);
Places.setPlacesAppCheckTokenProvider(new TokenProvider());
PlacesClient client = Places.createClient(context);.

في ما يلي نموذج لتنفيذ واجهة أداة جلب الرموز المميّزة:

  /** Sample client implementation of App Check token fetcher interface. */
  static class TokenProvider implements PlacesAppCheckTokenProvider {
    @Override
    public ListenableFuture<String> fetchAppCheckToken() {
      SettableFuture<String> future = SettableFuture.create();
      FirebaseAppCheck.getInstance()
          .getAppCheckToken(false)
          .addOnSuccessListener(
              appCheckToken -> {
                future.set(appCheckToken.getToken());
              })
          .addOnFailureListener(
              ex -> {
                future.setException(ex);
              });

      return future;
    }
  }

الخطوة 4: تفعيل تصحيح الأخطاء (اختيارية)

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

لتشغيل تطبيقك في محاكي أو على جهاز اختبار:

• أضِف مكتبة "فحص التطبيقات" إلى ملف build.gradle.
• اضبط ميزة "فحص التطبيقات" لاستخدام مصنع مقدّم خدمة تصحيح الأخطاء في إصدار مخصص لتصحيح الأخطاء.
• شغِّل التطبيق الذي سيُنشئ رمزًا مميّزًا محليًا لتصحيح الأخطاء. أضِف هذا الرمز المميّز إلى وحدة تحكّم Firebase.
• لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات".

لتشغيل تطبيقك في بيئة تكامل مستمر:

• أنشئ رمزًا مميّزًا لتصحيح الأخطاء في وحدة تحكّم Firebase وأضِفه إلى مخزن المفاتيح الآمن لنظام التكامل المستمر.
• أضِف مكتبة "فحص التطبيقات" إلى ملف build.gradle.
• اضبط تنويعة تصميم التكامل المستمر لاستخدام الرمز المميّز لتصحيح الأخطاء.
• استخدِم DebugAppCheckTestHelper لتضمين الرمز الذي يحتاج إلى رمز مميّز من ميزة "فحص التطبيقات" في فئات الاختبار.
• لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات".

الخطوة 5: مراقبة طلبات تطبيقك وتحديد خيارات الفرض

قبل البدء في فرض خيارات الفرض، عليك التأكّد من أنّك لن تؤدي إلى إيقاف استخدام تطبيقك من قِبل المستخدمين الشرعيين. للقيام بذلك، انتقِل إلى شاشة مقاييس ميزة "فحص التطبيقات" للاطّلاع على النسبة المئوية للزيارات التي تم التحقّق منها أو التي انتهت صلاحيتها أو غير المشروعة في تطبيقك. بعد التأكّد من أنّ معظم الزيارات تم التحقّق منها، يمكنك تفعيل خيارات الفرض.

لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات" من Firebase.

قبل فرض ميزة "فحص التطبيقات"، تأكَّد من أنّ أي طلبات لخدمة الويب في مشروعك على السحابة الإلكترونية تستخدم OAuth.