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

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

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

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

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

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

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

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

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

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

ملاحظة: لا يتم تفعيل إجراءات التنفيذ لميزة "فحص التطبيقات" تلقائيًا.

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

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

• يفرض أحد مقدّمي خدمات المصادقة الذين ننصح بهم، reCAPTCHA Enterprise، رسومًا مقابل أكثر من 10,000 تقييم شهريًا.

  أمّا مقدّم خدمة المصادقة الآخر الذي ننصح به، وهو الإصدار الثالث من خدمة reCAPTCHA، فيتضمّن حصة، وبعدها لن يتم تقييم الزيارات.

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

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

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

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

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

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

• تطبيق تم تحميل أحدث إصدار أسبوعي أو ربع سنوي من Maps JavaScript API ومكتبتَي Core وPlaces فيه.
• مشروع على السحابة الإلكترونية تم تفعيل واجهتَي برمجة التطبيقات Maps JavaScript API وPlaces API (الجديدة) فيه.
• يجب أن تكون مالك التطبيق في Cloud Console.
• ستحتاج إلى رقم تعريف مشروع التطبيق من Cloud Console.

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

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

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

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

• تعليمات reCAPTCHA Enterprise.

• تعليمات الإصدار الثالث من خدمة reCAPTCHA.

  يجب تسجيل موقعك الإلكتروني في الإصدار الثالث من خدمة reCAPTCHA والحصول على مفتاح الموقع الإلكتروني والمفتاح السري للإصدار الثالث من خدمة reCAPTCHA باستخدام أداة تسجيل الموقع الإلكتروني في reCAPTCHA قبل تفعيل واجهة برمجة التطبيقات على Cloud Console. لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات الإصدار الثالث من خدمة reCAPTCHA.

الخطوة 3: تحميل مكتبات Maps JavaScript API

1. حمِّل مكتبات Core وMaps وPlaces كما هو موضّح في المقتطف التالي. لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات فئة المكان في Maps JavaScript API.

   async function init() {
     const {Settings} = await google.maps.importLibrary('core');
     const {Map} = await google.maps.importLibrary('maps');
     const {Place} = await google.maps.importLibrary('places');
   }  

الخطوة 4: تهيئ واجهات برمجة التطبيقات Places API و"فحص التطبيقات"

1. هيئ ميزة "فحص التطبيقات" باستخدام الإعداد الذي توفّره وحدة تحكّم Firebase.
   • تعليمات الإصدار الثالث من خدمة reCAPTCHA.
   • تعليمات reCAPTCHA Enterprise
2. تأكَّد من أنّ الطلبات إلى Maps JavaScript API مصحوبة برموز مميّزة لميزة "فحص التطبيقات":

     async function init() {
       const {Settings} = await google.maps.importLibrary('core');
       const {Map} = await google.maps.importLibrary('maps');
       const {Place} = await google.maps.importLibrary('places');
     
       const app = initializeApp({
         // Your firebase configuration object
       });
     
       // Pass your reCAPTCHA Enterprise site key to initializeAppCheck().
       const appCheck = initializeAppCheck(app, {
         provider: new ReCaptchaEnterpriseProvider(
           'abcdefghijklmnopqrstuvwxy-1234567890abcd',
         ),
     
         // Optional argument. If true, the SDK automatically refreshes App Check
         // tokens as needed.
         isTokenAutoRefreshEnabled: true,
       });
     
       Settings.getInstance().fetchAppCheckToken = () =>
           getToken(appCheck, /* forceRefresh = */ false);
     
       // Make a Places JS request
       const place = new Place({id: 'ChIJN5Nz71W3j4ARhx5bwpTQEGg'});
       await place.fetchFields({fields: ['*']});
     
       // Load a map
       map = new Map(document.getElementById("map"), {
         center: { lat: 37.4161493, lng: -122.0812166 },
         zoom: 8,
       });
     }  
     

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

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

لاختبار تطبيقك محليًا:

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

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

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

الخطوة 6: مراقبة طلبات تطبيقك وتحديد إجراءات التنفيذ

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

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

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