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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. حمِّل مكتبة "العناصر الأساسية" ومكتبة "خرائط Google" كما هو موضّح في المقتطف التالي. لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات JavaScript لخرائط Google.

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

الخطوة 4: إعداد واجهات برمجة التطبيقات في "خرائط Google" وApp Check

  1. يمكنك إعداد App Check باستخدام الإعدادات المقدَّمة من وحدة تحكُّم Firebase.
  2. تأكَّد من أنّ الطلبات المرسَلة إلى Maps JS API مصحوبة بعلامات App Check:
      import {initializeApp} from 'firebase/app';
      import {
        getToken,
        initializeAppCheck,
        ReCaptchaEnterpriseProvider,
      } from 'firebase/app-check';
        
      async function init() {
        const {Settings} = await google.maps.importLibrary('core');
        const {Map} = await google.maps.importLibrary('maps');
      
        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);
      
        // Load a map
        map = new Map(document.getElementById("map"), {
          center: { lat: 37.4161493, lng: -122.0812166 },
          zoom: 8,
        });
      }  
      

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

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

لاختبار تطبيقك على الجهاز:

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

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

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

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

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

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