استخدام App Check لتأمين مفتاح واجهة برمجة التطبيقات
توفّر خدمة فحص التطبيقات من Firebase الحماية للمكالمات من تطبيقك إلى "منصة خرائط Google" من خلال حظر الزيارات الواردة من مصادر أخرى غير التطبيقات المشروعة. ويتم ذلك من خلال البحث عن رمز مميّز من موفّر خدمة شهادات مثل reCAPTCHA Enterprise. يساعد دمج تطبيقاتك مع App Check في الحماية من الطلبات الضارة، وبالتالي لن يتم تحصيل رسوم منك مقابل طلبات البيانات غير المصرّح بها من واجهة برمجة التطبيقات.
هل خدمة App Check مناسبة لي؟
ننصح باستخدام App Check في معظم الحالات، ولكن لا حاجة إلى استخدامها أو لا تتوفّر في الحالات التالية:
التطبيقات الخاصة أو التجريبية إذا لم يكن تطبيقك متاحًا للجميع، لن تحتاج إلى استخدام App Check.
إذا كان تطبيقك يُستخدم فقط من خادم إلى خادم، لن تحتاج إلى App Check. ومع ذلك، إذا كان الخادم الذي يتواصل مع "منصة Google للتسويق" يستخدمه عملاء عامون (مثل تطبيقات الأجهزة الجوّالة)، ننصحك باستخدام App Check لحماية هذا الخادم بدلاً من "منصة Google للتسويق".
نظرة عامة على خطوات التنفيذ
في ما يلي الخطوات التي يجب اتّباعها لدمج تطبيقك مع App Check:
بعد الدمج مع App Check، ستتمكّن من الاطّلاع على مقاييس عدد الزيارات إلى الخلفية في وحدة تحكّم Firebase. تقدّم هذه المقاييس تفصيلاً للطلبات حسب ما إذا كانت مصحوبة برمز مميّز صالح من App Check. لمزيد من المعلومات، يمكنك الاطّلاع على مستندات ميزة "فحص التطبيقات من Firebase".
عند التأكّد من أنّ معظم الطلبات واردة من مصادر مشروعة وأنّ المستخدمين قد ثبّتوا أحدث إصدار من تطبيقك يتضمّن عملية تنفيذ App Check، يمكنك تفعيل فرض استخدام الخدمة. بعد تفعيل ميزة فرض الاستخدام، سترفض خدمة App Check جميع الزيارات التي لا تتضمّن رمزًا مميزًا صالحًا من App Check.
اعتبارات عند التخطيط لعملية دمج App Check
في ما يلي بعض الأمور التي يجب وضعها في الاعتبار أثناء التخطيط لعملية الدمج:
يفرض أحد موفّري شهادات التصديق الذين ننصح بهم، وهو reCAPTCHA Enterprise، رسومًا مقابل أكثر من 10,000 تقييم شهريًا.
تتضمّن خدمة reCAPTCHA v3، وهي مقدّم خدمة آخر ننصح به، حصة يتم بعدها التوقف عن تقييم الزيارات.
يمكنك اختيار استخدام مقدّم خدمة إثبات صحة مخصّص، على الرغم من أنّ هذه حالة استخدام متقدّمة. لمزيد من المعلومات، يمكنك الاطّلاع على مستندات App Check.
سيواجه مستخدمو تطبيقك بعض التأخير عند بدء التشغيل. ومع ذلك، بعد ذلك، سيتم إجراء أي عمليات إعادة إثبات هوية دورية في الخلفية ولن يواجه المستخدمون أي تأخير. يعتمد مقدار وقت الاستجابة الدقيق عند بدء التشغيل على مقدّم خدمة الشهادات الذي تختاره.
يحدّد مقدار الوقت الذي يكون فيه رمز App Check المميّز صالحًا (مدة البقاء أو TTL) معدّل تكرار عمليات إثبات صحة الشهادة. يمكن ضبط هذه المدة في وحدة تحكّم Firebase. تحدث إعادة التصديق عندما ينقضي نصف مدة البقاء على قيد الحياة (TTL) تقريبًا. لمزيد من المعلومات، راجِع مستندات Firebase لمزوّد خدمة التصديق.
يوفّر Firebase تعليمات لكلّ مقدّم خدمة إثبات صحة تلقائي. توضّح لك هذه التعليمات كيفية إعداد مشروع على Firebase وإضافة مكتبة App Check إلى تطبيقك. اتّبِع نماذج الرموز البرمجية المتوفّرة لإعداد App Check.
تأكَّد من أنّ الطلبات إلى Maps JavaScript API مصحوبة برموز App Check المميّزة:
import{initializeApp}from'firebase/app';import{getToken,initializeAppCheck,ReCaptchaEnterpriseProvider,}from'firebase/app-check';asyncfunctioninit(){const{Settings}=awaitgoogle.maps.importLibrary('core');const{Map}=awaitgoogle.maps.importLibrary('maps');constapp=initializeApp({// Your firebase configuration object});// Pass your reCAPTCHA Enterprise site key to initializeAppCheck().constappCheck=initializeAppCheck(app,{provider:newReCaptchaEnterpriseProvider('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 mapmap=newMap(document.getElementById("map"),{center:{lat:37.4161493,lng:-122.0812166},zoom:8,});}
الخطوة 5: تفعيل تصحيح الأخطاء (اختياري)
إذا أردت تطوير تطبيقك واختباره على جهازك أو تشغيله في بيئة دمج مستمر (CI)، يمكنك إنشاء إصدار تصحيح أخطاء من تطبيقك يستخدم سر تصحيح الأخطاء للحصول على رموز مميّزة صالحة من App Check. يتيح لك ذلك تجنُّب استخدام موفّري خدمات تصديق حقيقيين في إصدار التصحيح.
لاختبار تطبيقك على الجهاز فقط، اتّبِع الخطوات التالية:
فعِّل موفّر تصحيح الأخطاء لأغراض التطوير.
ستتلقّى معرّف UUID4 عشوائيًا يتم إنشاؤه تلقائيًا (يُطلق عليه اسم _رمز تصحيح الأخطاء_ في مستندات App Check) من سجلّات تصحيح الأخطاء في حزمة SDK. أضِف هذا الرمز المميّز إلى وحدة تحكّم Firebase.
لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات App Check.
لتشغيل تطبيقك في بيئة دمج متواصل، اتّبِع الخطوات التالية:
إنشاء معرّف فريد عالمي (UUID) عشوائي من الإصدار 4 من وحدة تحكّم Firebase
أضِف UUID4 كرمز تصحيح أخطاء، ثم انسَخه إلى مخزن سري ستصل إليه اختبارات التكامل المستمر في كل عملية اختبار.
لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات App Check.
الخطوة 6: مراقبة طلبات تطبيقك وتحديد إجراء التنفيذ
قبل البدء في فرض استخدام App Check، عليك التأكّد من أنّك لن تعيق المستخدمين الشرعيين لتطبيقك. ولإجراء ذلك، انتقِل إلى شاشة مقاييس App Check لمعرفة النسبة المئوية لعدد الزيارات التي تم التحقّق منها أو التي انتهت صلاحيتها أو غير الشرعية في تطبيقك. بعد التأكّد من أنّ معظم الزيارات تم التحقّق منها، يمكنك تفعيل ميزة "التنفيذ".
تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eFirebase App Check secures your Google Maps Platform API key by verifying app requests and blocking unauthorized traffic.\u003c/p\u003e\n"],["\u003cp\u003eApp Check integrates with attestation providers like reCAPTCHA Enterprise to validate requests, protecting against malicious activity and unnecessary charges.\u003c/p\u003e\n"],["\u003cp\u003eImplementation involves adding Firebase and App Check to your app, initializing with a token provider, and enabling enforcement after monitoring request metrics.\u003c/p\u003e\n"],["\u003cp\u003eConsider potential costs associated with reCAPTCHA Enterprise and temporary latency for users during initial attestation.\u003c/p\u003e\n"],["\u003cp\u003eBefore enforcing App Check, ensure the majority of your app traffic is verified to avoid disrupting legitimate users.\u003c/p\u003e\n"]]],[],null,["Select platform: [Android](/maps/documentation/places/android-sdk/app-check \"View this page for the Android platform docs.\") [iOS](/maps/documentation/places/ios-sdk/app-check \"View this page for the iOS platform docs.\") [JavaScript](/maps/documentation/javascript/maps-app-check \"View this page for the JavaScript platform docs.\")\n\n\u003cbr /\u003e\n\nUse App Check to secure your API key\n====================================\n\n\n[Firebase App Check](https://firebase.google.com/docs/app-check) provides protection for calls from your app to Google Maps Platform by blocking traffic that comes from sources other than legitimate apps. It does this by checking for a token from an attestation provider like [reCAPTCHA Enterprise](https://cloud.google.com/recaptcha-enterprise). Integrating your apps with App Check helps to protect against malicious requests, so you're not charged for unauthorized API calls.\n\nIs App Check right for me?\n--------------------------\n\n\nApp Check is recommended in most cases, however App Check is not needed or is not supported in the following cases:\n\n- Private or experimental apps. If your app is not publicly accessible, App Check is not needed.\n- If your app is only used server-to-server, App Check is not needed. However, if the server that communicates with GMP is used by public clients (such as mobile apps), consider [using App Check to protect that server](https://firebase.google.com/docs/app-check/custom-resource-backend) instead of GMP.\n\nOverview of implementation steps\n--------------------------------\n\nAt a high level, these are the steps you'll follow to integrate your app with App Check:\n\n1. Add Firebase to your app.\n2. Add and initialize the App Check library.\n3. Add the token provider to your app.\n4. Initialize the Maps JS and App Check APIs.\n5. Enable debugging.\n6. Monitor your app requests and decide on enforcement.\n\n\nOnce you've integrated with App Check, you'll be able to see backend traffic metrics on the Firebase console. These metrics provide breakdown of requests by whether they are accompanied by a valid App Check token. See the [Firebase App Check documentation](https://firebase.google.com/docs/app-check/monitor-metrics) for more information.\n\n\nWhen you're sure that most requests are from legitimate sources and that users have updated to the latest version of your app that includes your implementation of App Check, you can turn on enforcement. Once enforcement is on, App Check will reject all traffic without a valid App Check token.\n| **Note:** App check enforcement is not turned on by default.\n\nConsiderations when planning an App Check integration\n-----------------------------------------------------\n\n\nHere are some things to consider as you plan your integration:\n\n- One of the attestation providers we recommend, [reCAPTCHA Enterprise](https://cloud.google.com/recaptcha-enterprise) charges for more than 10,000 assessments per month.\n\n The other attestation provider we recommend, [reCAPTCHA v3](/recaptcha/docs/v3) has a quota, after which traffic won't be evaluated.\n\n You can choose to use a custom attestation provider, though this is an advanced use case. See the [App Check documentation](https://firebase.google.com/docs/app-check/custom-provider) for more information.\n- Users of your app will experience some latency on startup. However, afterwards, any periodic re-attestation will occur in the background and users should no longer experience any latency. The exact amount of latency at startup depends on the attestation provider you choose.\n\n The amount of time that the App Check token is valid (the *time to live* , or TTL) determines the frequency of re-attestations. This duration can be configured in the Firebase console. Re-attestation occurs when approximately halkf of the TTL has elapsed. For more information, see the [Firebase docs](https://firebase.google.com/docs/app-check#get_started) for your attestation provider.\n\nIntegrate your app with App Check\n---------------------------------\n\n| Note: Get help faster! For support regarding the Firebase-related portions of this process, see [Firebase support](https://firebase.google.com/support). For support regarding the Google Places API, see [Google Maps Platform support](/maps/support).\n\n### Prerequisites and requirements\n\n- An app with the [the latest weekly or quarterly version of the Maps JS API](/maps/documentation/javascript/versions) and Core libraries loaded.\n- A Cloud project with the Maps JS API enabled.\n- You must be the owner of the app in Cloud Console.\n- You will need the app's project ID from the Cloud Console\n\n### Step 1: Add Firebase to your app\n\n\nFollow [the instructions in the Firebase developer documentation](https://firebase.google.com/docs/web/setup) to add Firebase to your app.\n\n\n### Step 2: Add the App Check library and initialize App Check\n\nFirebase provides instructions for each default attestation provider. These instructions show you how to set up a Firebase project and add the App Check library to your app. Follow the code samples provided to initialize App Check.\n\n- [Instructions for reCAPTCHA Enterprise](https://firebase.google.com/docs/app-check/web/recaptcha-enterprise-provider).\n- [Instructions for reCAPTCHA v3](https://firebase.google.com/docs/app-check/web/recaptcha-provider).\n\n | You must register your site for reCAPTCHA v3 and get your reCAPTCHA v3 site key and secret key using the reCAPTCHA site registration tool before you enable the API on the Cloud Console. See the [reCAPTCHA v3 documentation](/recaptcha/intro) for more information and instructions.\n\n### Step 3: Load Maps JS API libraries\n\n1. Load the core and Maps libraries as shown in the following snippet. For more information and instructions, see the [Maps JavaScript API documentation](/maps/documentation/javascript/load-maps-js-api).\n\n ```javascript\n async function init() {\n const {Settings} = await google.maps.importLibrary('core');\n const {Map} = await google.maps.importLibrary('maps');\n } \n ```\n\n### Step 4: Initialize the Maps and App Check APIs\n\n1. Initialize App Check using the config provided by the Firebase console.\n - [reCAPTCHA v3 instructions](https://firebase.google.com/docs/app-check/web/recaptcha-provider).\n - [reCAPTCHA Enterprise instructions.](https://firebase.google.com/docs/app-check/web/recaptcha-enterprise-provider)\n2. Ensure that requests to the Maps JS API are accompanied by App Check tokens: \n\n ```javascript\n import {initializeApp} from 'firebase/app';\n import {\n getToken,\n initializeAppCheck,\n ReCaptchaEnterpriseProvider,\n } from 'firebase/app-check';\n \n async function init() {\n const {Settings} = await google.maps.importLibrary('core');\n const {Map} = await google.maps.importLibrary('maps');\n \n const app = initializeApp({\n // Your firebase configuration object\n });\n \n // Pass your reCAPTCHA Enterprise site key to initializeAppCheck().\n const appCheck = initializeAppCheck(app, {\n provider: new ReCaptchaEnterpriseProvider(\n 'abcdefghijklmnopqrstuvwxy-1234567890abcd',\n ),\n \n // Optional argument. If true, the SDK automatically refreshes App Check\n // tokens as needed.\n isTokenAutoRefreshEnabled: true,\n });\n \n Settings.getInstance().fetchAppCheckToken = () =\u003e\n getToken(appCheck, /* forceRefresh = */ false);\n \n // Load a map\n map = new Map(document.getElementById(\"map\"), {\n center: { lat: 37.4161493, lng: -122.0812166 },\n zoom: 8,\n });\n } \n \n ```\n\n### Step 5: Enable debugging (optional)\n\nIf you'd like to develop and test your app locally, or run it in a continuous integration (CI) environment, you can create a debug build of your app that uses a debug secret to obtain valid App Check tokens. This lets you avoid using real attestation providers in your debug build.\n\nTo test your app locally:\n\n- Activate the debug provider for development purposes.\n- You will receive an automatically generated random UUID4 (called the _debug token_ in the App Check documentation) from the SDK's debug logs. Add this token to the Firebase console.\n- For more information and instructions, see the [App Check documentation](https://firebase.google.com/docs/app-check/web/debug-provider#localhost).\n\nTo run your app in a CI environment:\n\n- Generate a random UUID4 from the Firebase console.\n- Add the UUID4 as a debug token, and then copy it into a secret store that the CI tests will access per test run.\n- For more information and instructions, see the [App Check documentation](https://firebase.google.com/docs/app-check/web/debug-provider#ci).\n\n### Step 6: Monitor your app requests and decide on enforcement\n\n\nBefore you begin enforcement, you'll want to make sure that you won't disrupt legitimate users of your app. To do this, visit the App Check metrics screen to see what percentage of your app's traffic is verified, outdated, or illegitimate. Once you see that the majority of your traffic is verified, you can enable enforcement.\n\n\nSee the [Firebase App Check documentation](https://firebase.google.com/docs/app-check/monitor-metrics) for more information and instructions.\n| Before you enforce App Check, make sure any Web Service calls in your Cloud project use [OAuth](/maps/documentation/places/web-service/oauth-token)."]]
