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

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

هل خدمة App Check مناسبة لي؟

ننصح باستخدام App Check في معظم الحالات، ولكن لا حاجة إليه أو لا يتوفّر في الحالات التالية:

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

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

في ما يلي الخطوات التي يجب اتّباعها لدمج تطبيقك مع App Check:

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

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

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

ملاحظة: لا يتم تفعيل ميزة "فرض استخدام App Check" تلقائيًا.

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

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

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

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

  يمكنك اختيار استخدام مقدّم خدمة مخصّص لعملية التصديق، على الرغم من أنّ هذه حالة استخدام متقدّمة. لمزيد من المعلومات، يمكنك الاطّلاع على مستندات App Check.

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

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

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

ملاحظة: احصل على المساعدة بشكل أسرع! للحصول على دعم بشأن الأجزاء المتعلّقة بمنصّة 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: إضافة مكتبة App Check وإعدادها

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

• تعليمات حول reCAPTCHA Enterprise

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

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

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

1. حمِّل المكتبات الأساسية و"خرائط Google" و"أماكن Google" كما هو موضّح في المقتطف التالي. لمزيد من المعلومات والإرشادات، يُرجى الاطّلاع على مستندات فئة المكان في 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 وApp Check API

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

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

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

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

لتشغيل تطبيقك في بيئة دمج متواصل، اتّبِع الخطوات التالية:

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

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

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

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

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