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

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

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

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

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

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

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

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

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

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

ملاحظة: لا يكون فرض فحص التطبيقات مفعّلاً تلقائيًا.

اعتبارات عند التخطيط لدمج App Check

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

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

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

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

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

دمج تطبيقك مع App Check

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

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

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

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

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

الخطوة 2: إضافة مكتبة App Check وبدء تشغيل App Check

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

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

2. بعد ذلك، عليك إعداد App Check وبرنامج Places العميل.

   // 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)، يمكنك إنشاء إصدار لتصحيح أخطاء تطبيقك يستخدم مفتاح سر لتصحيح الأخطاء من أجل الحصول على رموز مميّزة صالحة لفحص التطبيق. يتيح لك ذلك تجنُّب استخدام مقدّمي بيانات اعتماد حقيقيين في إصدار تصحيح الأخطاء.

لتنفيذ تطبيقك في محاكي أو على جهاز اختبار، اتّبِع الخطوات التالية:

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

لتشغيل تطبيقك في بيئة تطوير متكامل (CI)، اتّبِع الخطوات التالية:

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

الخطوة 5: مراقبة طلبات تطبيقك واتخاذ قرار بشأن التنفيذ

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

يمكنك الاطّلاع على مستندات فحص التطبيقات من Firebase للحصول على مزيد من المعلومات والتعليمات.

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