از App Check برای ایمن کردن کلید API خود استفاده کنید
Firebase App Check با مسدود کردن ترافیکی که از منابعی غیر از برنامه‌های قانونی می‌آید، از تماس‌های برنامه شما به پلتفرم Google Maps محافظت می‌کند. این کار را با بررسی نشانه ای از یک ارائه دهنده گواهی مانند reCAPTCHA Enterprise انجام می دهد. ادغام برنامه‌هایتان با App Check به محافظت در برابر درخواست‌های مخرب کمک می‌کند، بنابراین برای تماس‌های API غیرمجاز هزینه‌ای از شما دریافت نمی‌شود.
آیا App Check برای من مناسب است؟
App Check در اکثر موارد توصیه می شود، اما در موارد زیر به بررسی برنامه نیازی نیست یا پشتیبانی نمی شود:
برنامه های خصوصی یا آزمایشی اگر برنامه شما برای عموم قابل دسترسی نیست، برنامه بررسی لازم نیست.
اگر برنامه شما فقط از سرور به سرور استفاده می شود، بررسی برنامه مورد نیاز نیست. با این حال، اگر سروری که با GMP ارتباط برقرار می کند توسط مشتریان عمومی (مانند برنامه های تلفن همراه) استفاده می شود، برای محافظت از آن سرور به جای GMP از App Check استفاده کنید.
مروری بر مراحل اجرا
در سطح بالا، این مراحلی هستند که برای یکپارچه کردن برنامه خود با App Check دنبال خواهید کرد:
Firebase را به برنامه خود اضافه کنید.
کتابخانه App Check را اضافه و مقداردهی اولیه کنید.
ارائه دهنده توکن را به برنامه خود اضافه کنید.
API های Maps JS و App Check را راه اندازی کنید.
اشکال زدایی را فعال کنید.
درخواست های برنامه خود را نظارت کنید و در مورد اجرا تصمیم بگیرید.
پس از ادغام با App Check، می‌توانید معیارهای ترافیک باطن را در کنسول Firebase ببینید. این معیارها به تفکیک درخواست‌ها بر اساس همراهی آنها با یک نشانه معتبر App Check ارائه می‌کنند. برای اطلاعات بیشتر به مستندات بررسی برنامه Firebase مراجعه کنید.
وقتی مطمئن شدید که اکثر درخواست‌ها از منابع قانونی هستند و کاربران به آخرین نسخه برنامه شما که شامل اجرای بررسی برنامه شما می‌شود، به‌روزرسانی کرده‌اند، می‌توانید اجرای آن را روشن کنید. پس از فعال شدن اجرای، بررسی برنامه تمام ترافیک بدون نشانه معتبر بررسی برنامه را رد می کند.
ملاحظات هنگام برنامه ریزی یکپارچه سازی App Check
در اینجا مواردی وجود دارد که باید هنگام برنامه ریزی ادغام خود در نظر بگیرید:
یکی از ارائه دهندگان گواهی که ما توصیه می کنیم، reCAPTCHA Enterprise برای بیش از 10000 ارزیابی در ماه هزینه دریافت می کند.
ارائه‌دهنده گواهینامه دیگری که توصیه می‌کنیم، reCAPTCHA v3 دارای یک سهمیه است که پس از آن ترافیک ارزیابی نمی‌شود.
شما می توانید انتخاب کنید که از یک ارائه دهنده گواهی سفارشی استفاده کنید، اگرچه این یک مورد استفاده پیشرفته است. برای اطلاعات بیشتر به اسناد App Check مراجعه کنید.
کاربران برنامه شما در هنگام راه اندازی با تاخیر مواجه می شوند. با این حال، پس از آن، هر گونه تأیید مجدد دوره ای در پس زمینه رخ می دهد و کاربران دیگر نباید تاخیری را تجربه کنند. میزان دقیق تاخیر در راه اندازی به ارائه دهنده گواهی انتخابی شما بستگی دارد.
مدت زمانی که کد App Check معتبر است ( زمان زندگی یا TTL) تعداد دفعات تأیید مجدد را تعیین می کند. این مدت زمان را می توان در کنسول Firebase پیکربندی کرد. تأیید مجدد زمانی اتفاق می افتد که تقریباً نیمی از TTL سپری شده باشد. برای اطلاعات بیشتر، به اسناد Firebase برای ارائه دهنده گواهی خود مراجعه کنید.
مرحله 2: کتابخانه App Check را اضافه کنید و App Check را مقداردهی اولیه کنید
Firebase دستورالعمل هایی را برای هر ارائه دهنده گواهی پیش فرض ارائه می دهد. این دستورالعمل ها به شما نشان می دهد که چگونه یک پروژه Firebase را راه اندازی کنید و کتابخانه App Check را به برنامه خود اضافه کنید. نمونه کدهای ارائه شده را برای مقداردهی اولیه بررسی برنامه دنبال کنید.
همانطور که در قطعه زیر نشان داده شده است، کتابخانه هسته و Maps را بارگیری کنید. برای اطلاعات بیشتر و دستورالعمل‌ها، به مستندات Maps JavaScript API مراجعه کنید.
اطمینان حاصل کنید که درخواست‌های Maps JS 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 تصادفی تولید شده به صورت خودکار (که در مستندات بررسی برنامه به نام _debug token_ نامیده می شود) از گزارش های اشکال زدایی SDK دریافت خواهید کرد. این توکن را به کنسول Firebase اضافه کنید.
مرحله 6: درخواست های برنامه خود را نظارت کنید و در مورد اجرا تصمیم بگیرید
قبل از شروع اجرای، باید مطمئن شوید که کاربران قانونی برنامه خود را مختل نخواهید کرد. برای انجام این کار، از صفحه معیارهای بررسی برنامه دیدن کنید تا ببینید چند درصد از ترافیک برنامه شما تأیید شده، قدیمی یا نامشروع است. وقتی دیدید که اکثر ترافیک شما تأیید شده است، می توانید اجرای آن را فعال کنید.
تاریخ آخرین به‌روزرسانی 2025-08-27 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین به‌روزرسانی 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)."]]
