بدء استخدام ميزة "التحقّق من التطبيقات" مع الإصدار الثالث من خدمة reCAPTCHA في تطبيقات الويب

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

يُرجى العِلم أنّ reCAPTCHA v3 غير مرئي للمستخدمين. لن يطلب موفّر الإصدار الثالث من خدمة reCAPTCHA من المستخدمين حلّ أي تحدٍ في أي وقت. الاطّلاع على مستندات الإصدار الثالث من خدمة reCAPTCHA.

إذا كنت تريد استخدام App Check مع موفّر مخصّص، يمكنك الاطّلاع على مقالة تنفيذ موفّر مخصّص لـ App Check.

1. إعداد مشروع Firebase

  1. أضِف Firebase إلى مشروع JavaScript إذا لم يسبق لك إجراء ذلك.

  2. سجِّل موقعك الإلكتروني في الإصدار الثالث من خدمة reCAPTCHA واحصل على مفتاح الموقع الإلكتروني والمفتاح السرّي في الإصدار الثالث من خدمة reCAPTCHA.

  3. في وحدة تحكّم Firebase، انتقِل إلى الأمان > فحص التطبيقات.

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

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

  5. اختياري: في إعدادات تسجيل التطبيق، اضبط مدة بقاء مخصّصة (TTL) للرموز المميّزة التي يصدرها الموفّر.App Check يمكنك ضبط مدة البقاء على أي قيمة تتراوح بين 30 دقيقة و7 أيام. عند تغيير هذه القيمة، يُرجى مراعاة المقايضات التالية:

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

    تُعدّ مدة البقاء التلقائية البالغة يومًا واحدًا مناسبة لمعظم التطبيقات. يُرجى العِلم أنّ مكتبة App Check تُجدّد الرموز المميّزة في نصف مدة البقاء تقريبًا.

ضبط الإعدادات المتقدّمة (اختياري)

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

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

التفاصيل

App Check تستخدم حدّ مخاطر التطبيق الذي تم ضبطه كأقل نتيجة مطلوبة في reCAPTCHA v3 ليتم اعتبار تفاعل المستخدم مشروعًا. سيتم رفض جميع نتائج reCAPTCHA v3 الأقل من حدّ مخاطر التطبيق الذي تم ضبطه. عند تعديل حدّ مخاطر التطبيق، يُرجى مراعاة ما يلي:

  • لمراقبة توزيع نتائج الإصدار الثالث من خدمة reCAPTCHA لتطبيق الويب، انتقِل إلى وحدة تحكّم مشرف reCAPTCHA و اختَر الموقع الإلكتروني الذي يتطابق مع تطبيق الويب.

  • إذا كان لديك مدى تحمّل منخفض لمخاطر التطبيق، حرِّك شريط التمرير إلى اليسار لزيادة حدّ مخاطر التطبيق.

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

  • إذا كان لديك مدى تحمّل عالي لمخاطر التطبيق، حرِّك شريط التمرير إلى اليمين لتقليل حدّ مخاطر التطبيق.

    • لا ننصح باستخدام القيمة 0.0، لأنّ هذا الإعداد يؤدي إلى إيقاف ميزة الحماية من إساءة الاستخدام.

يُرجى الاطّلاع على مستندات الإصدار الثالث من خدمة reCAPTCHA للحصول على تفاصيل إضافية.

2. إضافة مكتبة App Check إلى تطبيقك

أضِف Firebase إلى تطبيق الويب إذا لم يسبق لك إجراء ذلك. احرص على استيراد مكتبة App Check.

3. إعداد App Check

أضِف رمز الإعداد التالي إلى تطبيقك قبل الوصول إلى أي من خدمات Firebase. عليك تمرير مفتاح الموقع الإلكتروني في reCAPTCHA، الذي أنشأته في وحدة تحكّم reCAPTCHA، إلى activate().

Web

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaV3Provider } from "firebase/app-check";

const app = initializeApp({
  // Your firebase configuration object
});

// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaV3Provider('abcdefghijklmnopqrstuvwxy-1234567890abcd'),

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  isTokenAutoRefreshEnabled: true
});

Web

firebase.initializeApp({
  // Your firebase configuration object
});

const appCheck = firebase.appCheck();
// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
appCheck.activate(
  'abcdefghijklmnopqrstuvwxy-1234567890abcd',

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  true);

الخطوات التالية

بعد تثبيت مكتبة App Check في تطبيقك، عليك نشره.

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

مراقبة المقاييس وتفعيل عملية الفرض

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

للمساعدة في اتّخاذ هذا القرار، يمكنك الاطّلاع على App Check مقاييس للـ خدمات التي تستخدمها:

تفعيل عملية الفرض في App Check

عندما تفهم كيف ستؤثّر ميزة App Check في المستخدمين وتكون مستعدًا للمتابعة، يمكنك تفعيل عملية الفرض في ميزة App Check:

استخدام App Check في بيئات تصحيح الأخطاء

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

الاطّلاع على مقالة استخدام App Check مع موفّر تصحيح الأخطاء في تطبيقات الويب.