1. قبل از شروع
برای اطمینان از مشروعیت کاربرانی که با برنامه وب شما تعامل دارند، Firebase App Check را اجرا میکنید و از نشانههای reCAPTCHA JWT برای تأیید جلسات کاربر استفاده میکنید. این راهاندازی به شما امکان میدهد تا بهطور ایمن درخواستهای برنامه مشتری به Places API (جدید) را رسیدگی کنید.
آنچه خواهید ساخت.
برای نشان دادن این موضوع، یک برنامه وب ایجاد خواهید کرد که پس از بارگیری نقشه را نمایش می دهد. همچنین با استفاده از Firebase SDK به طور محتاطانه یک توکن reCAPTCHA تولید می کند. سپس این توکن به سرور Node.js شما ارسال میشود، جایی که Firebase قبل از انجام هر درخواستی به Places API آن را تأیید میکند.
اگر توکن معتبر باشد، Firebase App Check آن را تا زمان انقضای آن ذخیره میکند و نیاز به ایجاد یک توکن جدید برای هر درخواست مشتری را از بین میبرد. اگر رمز نامعتبر باشد، از کاربر خواسته میشود تا دوباره تأیید reCAPTCHA را تکمیل کند تا یک توکن جدید دریافت کند.
2. پیش نیازها
برای تکمیل این Codelab باید با موارد زیر آشنا شوید.
محصولات Google Cloud مورد نیاز
- بررسی برنامه Google Cloud Firebase : پایگاه داده برای مدیریت توکن ها
- Google reCAPTCHA : ایجاد و تأیید توکن. این ابزاری است که برای تشخیص انسان از ربات ها در وب سایت ها استفاده می شود. با تجزیه و تحلیل رفتار کاربر، ویژگی های مرورگر و اطلاعات شبکه برای ایجاد امتیازی که احتمال ربات بودن کاربر را نشان می دهد، کار می کند. اگر امتیاز به اندازه کافی بالا باشد، کاربر انسان محسوب می شود و نیازی به اقدام بیشتر نیست. اگر امتیاز پایین باشد، ممکن است یک پازل CAPTCHA برای تایید هویت کاربر ارائه شود. این رویکرد نسبت به روشهای سنتی CAPTCHA کمتر سرزده است و تجربه کاربر را روانتر میکند.
- (اختیاری) Google Cloud App Engine : محیط استقرار.
محصولات پلتفرم Google Maps مورد نیاز
در این Codelab، از محصولات پلتفرم Google Maps زیر استفاده خواهید کرد:
- Maps JavaScript API بارگیری و در برنامه وب نمایش داده شد
- Places API (جدید) درخواست صادر شده توسط سرور باطن
سایر الزامات برای این Codelab
برای تکمیل این Codelab، به حسابها، خدمات و ابزارهای زیر نیاز دارید:
- یک حساب Google Cloud Platform با فعال کردن صورتحساب
- یک کلید API پلتفرم Google Maps با فعال بودن Maps JavaScript API و Places
- دانش اولیه جاوا اسکریپت، HTML و CSS
- دانش اولیه Node.js
- یک ویرایشگر متن یا IDE به انتخاب شما
3. راه اندازی کنید
پلتفرم نقشه های گوگل را راه اندازی کنید
اگر قبلاً یک حساب Google Cloud Platform و پروژهای با صورتحساب فعال ندارید، لطفاً راهنمای شروع به کار با Google Maps Platform را برای ایجاد یک حساب صورتحساب و یک پروژه ببینید.
- در Cloud Console ، روی منوی کشویی پروژه کلیک کنید و پروژه ای را که می خواهید برای این کد لبه استفاده کنید انتخاب کنید.
- APIها و SDKهای پلتفرم Google Maps مورد نیاز برای این لبه کد را در Google Cloud Marketplace فعال کنید. برای انجام این کار، مراحل این ویدیو یا این مستند را دنبال کنید.
- یک کلید API در صفحه Credentials در Cloud Console ایجاد کنید. می توانید مراحل این ویدئو یا این مستند را دنبال کنید. همه درخواستها به پلتفرم Google Maps به یک کلید API نیاز دارند.
اعتبار پیش فرض برنامه
شما از Firebase Admin SDK برای تعامل با پروژه Firebase خود و همچنین درخواست برای Places API استفاده خواهید کرد و برای کارکرد آن باید اعتبارنامه معتبری ارائه دهید.
ما از ADC Authentication (Automatic Default Credentials) برای احراز هویت سرور شما برای ارسال درخواست استفاده خواهیم کرد. از طرف دیگر (توصیه نمی شود) می توانید یک حساب کاربری ایجاد کنید و اعتبارنامه ها را در کد خود ذخیره کنید.
تعریف : اعتبار پیش فرض برنامه (ADC) مکانیزمی است که Google Cloud برای احراز هویت خودکار برنامه های شما بدون مدیریت صریح اعتبارنامه ها ارائه می دهد. در مکانهای مختلف (مانند متغیرهای محیط، فایلهای حساب سرویس یا سرور ابرداده Google Cloud) به دنبال اعتبار میگردد و از اولین موردی که پیدا میکند استفاده میکند.
- در ترمینال خود، از دستور زیر استفاده کنید که به برنامههای شما اجازه میدهد بهطور ایمن به منابع Google Cloud از طرف کاربری وارد شده در حال حاضر دسترسی پیدا کنند:
gcloud auth application-default login
- شما یک فایل .env در ریشه ایجاد خواهید کرد که یک متغیر Google Cloud Project را مشخص می کند:
GOOGLE_CLOUD_PROJECT="your-project-id"
اعتبارنامه های جایگزین (توصیه نمی شود)
یک حساب کاربری ایجاد کنید
- تب Google Maps Platform > "+Create Credentials" > حساب خدمات
- نقش مدیریت Firebase AppCheck را اضافه کنید، سپس نام حساب سرویس را که تایپ کردید وارد کنید، به عنوان مثال: firebase-appcheck-codelab@yourproject.iam.gserviceaccount.com
اعتبارنامه
- روی حساب کاربری ایجاد شده کلیک کنید
- به برگه KEYS بروید تا یک کلید ایجاد کنید > JSON > اعتبارنامه های دانلود شده json را ذخیره کنید. فایل xxx.json را که به صورت خودکار دانلود شده است به پوشه ریشه خود منتقل کنید
- (فصل بعدی) آن را به درستی در فایل nodejs server.js نامگذاری کنید (firebase-credentials.json)
4. Firebase AppCheck Integration
جزئیات پیکربندی Firebase و کلیدهای مخفی reCAPTCHA را دریافت خواهید کرد.
آنها را در برنامه آزمایشی قرار داده و سرور را راه اندازی می کنید.
یک برنامه کاربردی در Firebase ایجاد کنید
- به مدیر پروژه https://console.firebase.google.com بروید ( پیوندها را بیابید):
پروژه Google Cloud را که قبلاً ایجاد شده است انتخاب کنید (شاید باید مشخص کنید: "انتخاب منبع والد")"
- افزودن یک برنامه از منوی بالا سمت چپ (دنده)
کد اولیه Firebase
- کد اولیه Firebase را ذخیره کنید تا در script.js (فصل بعدی) برای سمت سرویس گیرنده قرار دهید
- برنامه خود را ثبت کنید تا به Firebase اجازه دهید از رمزهای reCAPTCHA v3 استفاده کند
https://console.firebase.google.com /u/0/project/YOUR_PROJECT/appcheck/apps
- reCAPTCHA را انتخاب کنید → ایجاد یک کلید در وب سایت reCAPTCHA (با دامنه های راست پیکربندی شده: localhost for app dev)
- رمز reCAPTCHA را در Firebase AppCheck جایگذاری کنید
- وضعیت برنامه باید سبز شود
5. برنامه آزمایشی
- برنامه وب مشتری: فایل های HTML، جاوا اسکریپت، CSS
- سرور: فایل Node.js
- Environment (.env): کلیدهای API
- پیکربندی (app.yaml): تنظیمات استقرار موتور برنامه Google
تنظیم Node.js:
- پیمایش : ترمینال خود را باز کنید و به دایرکتوری ریشه پروژه کلون شده خود بروید.
- Node.js را نصب کنید (در صورت نیاز) : نسخه 18 یا بالاتر.
node -v # Check installed version
- Initialize Project: دستور زیر را برای مقداردهی اولیه یک پروژه جدید Node.js اجرا کنید و تمام تنظیمات را به عنوان پیش فرض باقی بگذارید:
npm init
- Install Dependencies: از دستور زیر برای نصب وابستگی های پروژه مورد نیاز استفاده کنید:
npm install @googlemaps/places firebase-admin express axios dotenv
پیکربندی: متغیرهای محیطی برای پروژه Google Cloud
- ایجاد فایل محیطی: در دایرکتوری اصلی پروژه خود، فایلی به نام
.env
ایجاد کنید. این فایل داده های پیکربندی حساس را ذخیره می کند و نباید به کنترل نسخه متعهد شود. - پر کردن متغیرهای محیط: فایل
.env
را باز کنید و متغیرهای زیر را اضافه کنید و مقادیر واقعی پروژه Google Cloud خود را جایگزین متغیرهای مکان کنید:
# Google Cloud Project ID
GOOGLE_CLOUD_PROJECT="your-cloud-project-id"
# reCAPTCHA Keys (obtained in previous steps)
RECAPTCHA_SITE_KEY="your-recaptcha-site-key"
RECAPTCHA_SECRET_KEY="your-recaptcha-secret-key"
# Maps Platform API Keys (obtained in previous steps)
PLACES_API_KEY="your-places-api-key"
MAPS_API_KEY="your-maps-api-key"
6. مروری بر کد
index.html
- کتابخانه های firebase را برای ایجاد نشانه در برنامه بارگیری می کند
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Places API with AppCheck</title>
<style></style> </head>
<body>
<div id="map"></div>
<!-- Firebase services -->
<script src="https://www.gstatic.com/firebasejs/9.15.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.15.0/firebase-app-check-compat.js"></script>
<script type="module" src="./script.js"></script>
<link rel="stylesheet" href="./style.css">
</body>
</html>
script.js
- کلیدهای API را واکشی می کند: کلیدهای API را برای Google Maps و بررسی برنامه Firebase از یک سرور باطن بازیابی می کند.
- Firebase را راه اندازی می کند: Firebase را برای احراز هویت و امنیت تنظیم می کند. (پیکربندی را جایگزین کنید → به فصل 4 مراجعه کنید).
مدت اعتبار نشانه بررسی برنامه Firebase، از 30 دقیقه تا 7 روز، در کنسول Firebase پیکربندی شده است و نمیتوان آن را با تلاش برای تجدید اجباری نشانه تغییر داد.
- بررسی برنامه را فعال میکند: بررسی برنامه Firebase را برای تأیید صحت درخواستهای دریافتی فعال میکند.
- Loads Google Maps API: کتابخانه جاوا اسکریپت Google Maps را به صورت پویا برای نمایش نقشه بارگیری می کند.
- Initializes the Map: یک نقشه گوگل با مرکز یک مکان پیش فرض ایجاد می کند.
- کنترل روی نقشه کلیکها: به کلیکهای روی نقشه گوش میدهد و نقطه مرکزی را متناسب با آن بهروزرسانی میکند.
- Queries Places API: درخواستها را به یک API پشتیبان (
/api/data
) میفرستد تا اطلاعات مکانها (رستورانها، پارکها، بارها) را در نزدیکی مکان کلیکشده، با استفاده از بررسی برنامه Firebase برای مجوز دریافت کند. - نشانگرها را نشان میدهد: دادههای واکشی شده را روی نقشه بهعنوان نشانگر ترسیم میکند و نام و نمادهای آنها را نشان میدهد.
let mapsApiKey, recaptchaKey; // API keys
let currentAppCheckToken = null; // AppCheck token
async function init() {
try {
await fetchConfig(); // Load API keys from .env variable
/////////// REPLACE with your Firebase configuration details
const firebaseConfig = {
apiKey: "AIza.......",
authDomain: "places.......",
projectId: "places.......",
storageBucket: "places.......",
messagingSenderId: "17.......",
appId: "1:175.......",
measurementId: "G-CPQ.......",
};
/////////// REPLACE
// Initialize Firebase and App Check
await firebase.initializeApp(firebaseConfig);
await firebase.appCheck().activate(recaptchaKey);
// Get the initial App Check token
currentAppCheckToken = await firebase.appCheck().getToken();
// Load the Maps JavaScript API dynamically
const scriptMaps = document.createElement("script");
scriptMaps.src = `https://maps.googleapis.com/maps/api/js?key=${mapsApiKey}&libraries=marker,places&v=beta`;
scriptMaps.async = true;
scriptMaps.defer = true;
scriptMaps.onload = initMap; // Create the map after the script loads
document.head.appendChild(scriptMaps);
} catch (error) {
console.error("Firebase initialization error:", error);
// Handle the error appropriately (e.g., display an error message)
}
}
window.onload = init()
// Fetch configuration data from the backend API
async function fetchConfig() {
const url = "/api/config";
try {
const response = await fetch(url);
const config = await response.json();
mapsApiKey = config.mapsApiKey;
recaptchaKey = config.recaptchaKey;
} catch (error) {
console.error("Error fetching configuration:", error);
// Handle the error (e.g., show a user-friendly message)
}
}
// Initialize the map when the Maps API script loads
let map; // Dynamic Map
let center = { lat: 48.85557501, lng: 2.34565006 };
function initMap() {
map = new google.maps.Map(document.getElementById("map"), {
center: center,
zoom: 13,
mapId: "b93f5cef6674c1ff",
zoomControlOptions: {
position: google.maps.ControlPosition.RIGHT_TOP,
},
streetViewControl: false,
mapTypeControl: false,
clickableIcons: false,
fullscreenControlOptions: {
position: google.maps.ControlPosition.LEFT_TOP,
},
});
// Initialize the info window for markers
infoWindow = new google.maps.InfoWindow({});
// Add a click listener to the map
map.addListener("click", async (event) => {
try {
// Get a fresh App Check token on each click
const appCheckToken = await firebase.appCheck().getToken();
currentAppCheckToken = appCheckToken;
// Update the center for the Places API query
center.lat = event.latLng.lat();
center.lng = event.latLng.lng();
// Query for places with the new token and center
queryPlaces();
} catch (error) {
console.error("Error getting App Check token:", error);
}
});
}
function queryPlaces() {
const url = '/api/data'; // "http://localhost:3000/api/data"
const body = {
request: {
includedTypes: ['restaurant', 'park', 'bar'],
excludedTypes: [],
maxResultCount: 20,
locationRestriction: {
circle: {
center: {
latitude: center.lat,
longitude: center.lng,
},
radius: 4000,
},
},
},
};
// Provides token to the backend using header: X-Firebase-AppCheck
fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Firebase-AppCheck': currentAppCheckToken.token,
},
body: JSON.stringify(body),
})
.then((response) => response.json())
.then((data) => {
// display if response successful
displayMarkers(data.places);
})
.catch((error) => {
alert('No places');
// eslint-disable-next-line no-console
console.error('Error:', error);
});
}
//// display places markers on map
...
server.js
- متغیرهای محیطی (کلیدهای API، شناسه پروژه Google) را از یک فایل
.env
بارگیری می کند. - سرور را راه اندازی می کند و به درخواست ها در
http://localhost:3000
گوش می دهد. - Firebase Admin SDK را با استفاده از Application Default Credentials (ADC) راهاندازی میکند .
- یک نشانه reCAPTCHA از
script.js
دریافت می کند. - اعتبار توکن دریافتی را تأیید می کند.
- اگر توکن معتبر باشد، یک درخواست POST به API Google Places با پارامترهای جستجوی گنجانده شده ارائه میکند .
- پاسخ از API Places را پردازش می کند و به مشتری برمی گرداند .
const express = require('express');
const axios = require('axios');
const admin = require('firebase-admin');
// .env variables
require('dotenv').config();
// Store sensitive API keys in environment variables
const recaptchaSite = process.env.RECAPTCHA_SITE_KEY;
const recaptchaSecret = process.env.RECAPTCHA_SECRET_KEY;
const placesApiKey = process.env.PLACES_API_KEY;
const mapsApiKey = process.env.MAPS_API_KEY;
// Verify environment variables loaded (only during development)
console.log('recaptchaSite:', recaptchaSite, '\n');
console.log('recaptchaSecret:', recaptchaSecret, '\n');
const app = express();
app.use(express.json());
// Firebase Admin SDK setup with Application Default Credentials (ADC)
const { GoogleAuth } = require('google-auth-library');
admin.initializeApp({
// credential: admin.credential.applicationDefault(), // optional: explicit ADC
});
// Main API Endpoint
app.post('/api/data', async (req, res) => {
const appCheckToken = req.headers['x-firebase-appcheck'];
console.log("\n", "Token", "\n", "\n", appCheckToken, "\n")
try {
// Verify Firebase App Check token for security
const appCheckResult = await admin.appCheck().verifyToken(appCheckToken);
if (appCheckResult.appId) {
console.log('App Check verification successful!');
placesQuery(req, res);
} else {
console.error('App Check verification failed.');
res.status(403).json({ error: 'App Check verification failed.' });
}
} catch (error) {
console.error('Error verifying App Check token:', error);
res.status(500).json({ error: 'Error verifying App Check token.' });
}
});
// Function to query Google Places API
async function placesQuery(req, res) {
console.log('#################################');
console.log('\n', 'placesApiKey:', placesApiKey, '\n');
const queryObject = req.body.request;
console.log('\n','Request','\n','\n', queryObject, '\n')
const headers = {
'Content-Type': 'application/json',
'X-Goog-FieldMask': '*',
'X-Goog-Api-Key': placesApiKey,
'Referer': 'http://localhost:3000', // Update for production(ie.: req.hostname)
};
const myUrl = 'https://places.googleapis.com/v1/places:searchNearby';
try {
// Authenticate with ADC
const auth = new GoogleAuth();
const { credential } = await auth.getApplicationDefault();
const response = await axios.post(myUrl, queryObject, { headers, auth: credential });
console.log('############### SUCCESS','\n','\n','Response','\n','\n', );
const myBody = response.data;
myBody.places.forEach(place => {
console.log(place.displayName);
});
res.json(myBody); // Use res.json for JSON data
} catch (error) {
console.log('############### ERROR');
// console.error(error); // Log the detailed error for debugging
res.status(error.response.status).json(error.response.data); // Use res.json for errors too
}
}
// Configuration endpoint (send safe config data to the client)
app.get('/api/config', (req, res) => {
res.json({
mapsApiKey: process.env.MAPS_API_KEY,
recaptchaKey: process.env.RECAPTCHA_SITE_KEY,
});
});
// Serve static files
app.use(express.static('static'));
// Start the server
const port = process.env.PORT || 3000;
app.listen(port, () => {
console.log(`Server listening on port ${port}`, '\n');
});
7. برنامه را اجرا کنید
از محیط انتخابی خود، سرور را از ترمینال اجرا کنید و به http://localhost:3000 بروید
npm start
یک توکن به عنوان یک متغیر جهانی ایجاد می شود، از پنجره مرورگر کاربر پنهان می شود و برای پردازش به سرور منتقل می شود. جزئیات توکن را می توان در گزارش های سرور پیدا کرد. | جزئیات مربوط به عملکرد سرور و پاسخ به درخواست Places API Nearby Search را میتوانید در گزارشهای سرور پیدا کنید. |
عیب یابی:
اطمینان حاصل کنید که شناسه پروژه Google در تنظیمات سازگار است:
- در فایل env. (متغیر GOOGLE_CLOUD_PROJECT)
- در پیکربندی ترمینال gcloud:
gcloud config set project your-project-id
- در تنظیم reCaptcha
- در تنظیمات Firebase
دیگر
- یک نشانه اشکال زدایی ایجاد کنید که می تواند به جای کلید سایت reCAPTCHA در
script.js
برای اهداف آزمایش و عیب یابی استفاده شود.
try {
// Initialize Firebase first
await firebase.initializeApp(firebaseConfig);
// Set the debug token
if (window.location.hostname === 'localhost') { // Only in development
await firebase.appCheck().activate(
'YOUR_DEBUG_FIREBASE_TOKEN', // Replace with the token from the console
true // Set to true to indicate it's a debug token
);
} else {
// Activate App Check
await firebase.appCheck().activate(recaptchaKey);
}
- انجام بیش از حد احراز هویت ناموفق، به عنوان مثال: استفاده از کلید سایت recaptcha نادرست، ممکن است باعث ایجاد یک throttling موقت شود.
FirebaseError: AppCheck: Requests throttled due to 403 error. Attempts allowed again after 01d:00m:00s (appCheck/throttled).
اعتبار ADC
- مطمئن شوید که در حساب gcloud مناسب هستید
gcloud auth login
- مطمئن شوید که کتابخانه های لازم نصب شده اند
npm install @googlemaps/places firebase-admin
- مطمئن شوید که کتابخانه Firebase در server.js بارگیری شده است
const {GoogleAuth} = require('google-auth-library');
- توسعه محلی : تنظیم ADC
gcloud auth application-default login
- جعل هویت: اعتبارنامه ADC ذخیره شد
gcloud auth application-default login --impersonate-service-account your_project@appspot.gserviceaccount.com
- در نهایت ADC محلی را آزمایش کنید، اسکریپت زیر را به عنوان test.js ذخیره کنید و در Terminal اجرا کنید:
node test.js
const {GoogleAuth} = require('google-auth-library');
async function requestTestADC() {
try {
// Authenticate using Application Default Credentials (ADC)
const auth = new GoogleAuth();
const {credential} = await auth.getApplicationDefault();
// Check if the credential is successfully obtained
if (credential) {
console.log('Application Default Credentials (ADC) loaded successfully!');
console.log('Credential:', credential); // Log the credential object
} else {
console.error('Error: Could not load Application Default Credentials (ADC).');
}
// ... rest of your code ...
} catch (error) {
console.error('Error:', error);
}
}
requestTestADC();
8. همین، آفرین!
مراحل پیگیری
استقرار در App Engine:
- پروژه خود را برای استقرار در Google App Engine و انجام هرگونه تغییر پیکربندی لازم آماده کنید.
- از ابزار خط فرمان
gcloud
یا کنسول App Engine برای استقرار برنامه خود استفاده کنید.
تقویت احراز هویت Firebase:
- پیشفرض در مقابل توکنهای سفارشی: توکنهای سفارشی Firebase را برای استفاده عمیقتر از خدمات Firebase پیادهسازی کنید.
- طول عمر توکن: طول عمر رمز مناسب را تنظیم کنید، برای عملیات حساس کوتاهتر (توکن Firebase سفارشی تا یک ساعت)، طولانیتر برای جلسات عمومی (ژتون reCAPTCHA: 30 دقیقه تا 7 ساعت).
- جایگزینهای reCAPTCHA را کاوش کنید: بررسی کنید که آیا DeviceCheck (iOS)، SafetyNet (Android)، یا App Attest برای نیازهای امنیتی شما مناسب هستند یا خیر.
ادغام محصولات Firebase:
- پایگاه داده بیدرنگ یا Firestore: اگر برنامه شما به قابلیت های همزمان یا آفلاین داده ها در زمان واقعی نیاز دارد، با پایگاه داده بیدرنگ یا Firestore ادغام کنید.
- Cloud Storage: از Cloud Storage برای ذخیره و ارائه محتوای تولید شده توسط کاربر مانند تصاویر یا ویدیوها استفاده کنید.
- احراز هویت: از Firebase Authentication برای ایجاد حساب های کاربری، مدیریت جلسات ورود و مدیریت بازنشانی رمز عبور استفاده کنید.
گسترش به موبایل:
- Android و iOS: اگر قصد دارید یک اپلیکیشن موبایل داشته باشید، نسخه هایی را برای هر دو پلتفرم اندروید و iOS ایجاد کنید.
- Firebase SDK: از Firebase SDK برای Android و iOS برای ادغام یکپارچه ویژگی های Firebase در برنامه های تلفن همراه خود استفاده کنید.