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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    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 للحصول على مزيد من المعلومات والتعليمات.