मकसद
इस दस्तावेज़ में, Google Maps Platform का इस्तेमाल करके, इंटरैक्टिव स्टोर फ़ाइंडर ऐप्लिकेशन बनाने के मुख्य चरणों के बारे में बताया गया है. खास तौर पर, Maps JavaScript API और जगहों की जानकारी देने वाली यूआई किट: Place Details एलिमेंट का इस्तेमाल करके. आपको स्टोर की जगहें दिखाने वाला मैप बनाने का तरीका पता चलेगा. साथ ही, आपको यह भी पता चलेगा कि दिखने वाले स्टोर की सूची को डाइनैमिक तरीके से कैसे अपडेट किया जाता है और हर स्टोर के लिए जगह की ज़्यादा जानकारी कैसे दिखाई जाती है.
ज़रूरी शर्तें
हमारा सुझाव है कि आपको इनके बारे में जानकारी हो:
- Maps JavaScript API - इसका इस्तेमाल, आपके पेज पर मैप दिखाने और जगहों की जानकारी देने वाली यूआई किट को इंपोर्ट करने के लिए किया जाता है.
- ऐडवांस मार्कर - इसका इस्तेमाल, मैप पर मार्कर दिखाने के लिए किया जाता है.
- जगहों की जानकारी देने वाली यूआई किट - इसका इस्तेमाल, यूज़र इंटरफ़ेस (यूआई) में आपके स्टोर की जानकारी दिखाने के लिए किया जाता है.
अपने प्रोजेक्ट पर, Maps JavaScript API और जगहों की जानकारी देने वाली यूआई किट चालू करें.
शुरू करने से पहले, पक्का करें कि आपने Maps JavaScript API लोड किया हो. साथ ही, ऐडवांस मार्कर और जगहों की जानकारी देने वाली यूआई किट के लिए ज़रूरी लाइब्रेरी इंपोर्ट की हों. इस दस्तावेज़ में यह भी माना गया है कि आपको वेब डेवलपमेंट की जानकारी है. इसमें एचटीएमएल, सीएसएस, और JavaScript शामिल हैं.
शुरुआती सेट अप
सबसे पहले, पेज पर मैप जोड़ें. इस मैप का इस्तेमाल, आपके स्टोर की जगहों से जुड़ी पिन दिखाने के लिए किया जाएगा.
किसी पेज पर मैप जोड़ने के दो तरीके हैं:
- gmp-map एचटीएमएल वेब कॉम्पोनेंट का इस्तेमाल करना
- JavaScript का इस्तेमाल करना
अपने इस्तेमाल के हिसाब से सबसे सही तरीका चुनें. मैप को लागू करने के दोनों तरीके, इस गाइड के साथ काम करेंगे.
स्टोर की जगहों की जानकारी लोड करना और दिखाना
इस सेक्शन में, हम आपके स्टोर का डेटा लोड करेंगे और उसे मैप पर दिखाएंगे. इस गाइड में यह माना गया है कि आपके पास अपने मौजूदा स्टोर की जानकारी का डेटाबेस है, जिससे जानकारी ली जा सकती है. आपके स्टोर का डेटा, आपके डेटाबेस जैसे अलग-अलग सोर्स से मिल सकता है.
इस उदाहरण के लिए, हम स्टोर ऑब्जेक्ट के कलेक्शन वाली एक स्थानीय JSON फ़ाइल (stores.json) मान लेते हैं. इसमें हर ऑब्जेक्ट, स्टोर की एक जगह को दिखाता है. हर ऑब्जेक्ट में कम से कम एक name, location (lat और lng के साथ), और एक place_id होना चाहिए.
अगर आपके पास अपने स्टोर की जगहों के आईडी नहीं हैं, तो उन्हें पाने के कई तरीके हैं. ज़्यादा जानकारी के लिए, जगह के आईडी का दस्तावेज़ देखें.
आपकी stores.json फ़ाइल में, स्टोर की जानकारी की एंट्री का उदाहरण कुछ ऐसा दिख सकता है.
इसमें नाम, जगह (अक्षांश/देशांतर), और जगह के आईडी के लिए फ़ील्ड होते हैं. स्टोर के खुले होने का समय (कम किया गया) दिखाने के लिए, एक ऑब्जेक्ट है. स्टोर की जगह की खास सुविधाओं के बारे में बताने के लिए, दो बूलियन वैल्यू भी होती हैं.
{
"name": "Example Store Alpha",
"location": { "lat": 51.51, "lng": -0.12 },
"place_id": "YOUR_STORE_PLACE_ID",
"opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
"new_store_design": true,
"indoor_seating": false
}
अपने JavaScript कोड में, अपने स्टोर की जगहों का डेटा फ़ेच करें. साथ ही, हर जगह के लिए मैप पर एक पिन दिखाएं.
ऐसा करने का एक उदाहरण यहां दिया गया है. यह फ़ंक्शन, स्टोर की जानकारी वाले ऑब्जेक्ट को लेता है और हर स्टोर की जगह के आधार पर एक मार्कर बनाता है.
function displayInitialMarkers(storeLocations) {
if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
storeLocations.forEach(store => {
if (store.location) {
const marker = new AdvancedMarkerElement({
position: new LatLng(store.location.lat, store.location.lng),
title: store.name
});
mapElement.appendChild(marker);
}
});
}
स्टोर लोड करने और मैप पर उनकी जगहों को दिखाने वाली पिन जोड़ने के बाद, एचटीएमएल और सीएसएस का इस्तेमाल करके साइडबार बनाएं. इससे आपके हर स्टोर की जानकारी दिखेगी.
इस स्टेज पर आपका स्टोर लोकेटर कैसा दिख सकता है, इसका एक उदाहरण यहां दिया गया है:
मैप के व्यूपोर्ट में होने वाले बदलावों को सुनें
परफ़ॉर्मेंस और उपयोगकर्ता अनुभव को बेहतर बनाने के लिए, अपने ऐप्लिकेशन को अपडेट करें. इससे साइडबार में मार्कर और जानकारी सिर्फ़ तब दिखेगी, जब उनसे जुड़ी जगहें मैप के दिखने वाले हिस्से (व्यूपोर्ट) में होंगी. इसके लिए, मैप व्यूपोर्ट में होने वाले बदलावों को सुनना, इन इवेंट को डिबाउंस करना, और फिर सिर्फ़ ज़रूरी मार्कर को फिर से ड्रॉ करना शामिल है.
मैप के आइडल इवेंट में इवेंट लिसनर अटैच करें. यह इवेंट, पैनिंग या ज़ूम करने की प्रोसेस पूरी होने के बाद ट्रिगर होता है. इससे आपको कैलकुलेशन के लिए एक स्टेबल व्यूपोर्ट मिलता है.
map.addListener('idle', debounce(updateMarkersInView, 300));
ऊपर दिया गया कोड स्निपेट, idle इवेंट को सुनता है और debounce फ़ंक्शन को कॉल करता है. डीबाउंस फ़ंक्शन का इस्तेमाल करने से यह पक्का होता है कि मार्कर अपडेट करने का लॉजिक सिर्फ़ तब चलता है, जब उपयोगकर्ता ने कुछ समय के लिए मैप से इंटरैक्ट करना बंद कर दिया हो. इससे परफ़ॉर्मेंस बेहतर होती है.
function debounce(func, delay) {
let timeoutId;
return function(...args) {
const context = this;
clearTimeout(timeoutId);
timeoutId = setTimeout(() => {
func.apply(context, args);
}, delay);
};
}
ऊपर दिया गया कोड, डीबाउंस फ़ंक्शन का एक उदाहरण है. यह एक फ़ंक्शन और डिले आर्ग्युमेंट लेता है. इसे आइडल लिसनर में पास किया जा सकता है. मैप के मूव होने के बाद, 300 मिलीसेकंड का इंतज़ार करना काफ़ी है. इससे यूज़र इंटरफ़ेस (यूआई) में कोई खास देरी नहीं होती.
टाइम आउट की यह अवधि खत्म होने के बाद, पास किए गए फ़ंक्शन को कॉल किया जाता है. इस मामले में,
updateMarkersInView.
updateMarkersInView फ़ंक्शन को ये कार्रवाइयां करनी चाहिए:
मैप से सभी मौजूदा मार्कर मिटाएं
देखें कि स्टोर की जगह, मैप के मौजूदा दायरे में आती है या नहीं. उदाहरण के लिए:
if (map.getBounds().contains(storeLatLng)) {
// logic
}
ऊपर दिए गए if स्टेटमेंट में, मार्कर दिखाने और साइड बार में स्टोर की जानकारी सेव करने के लिए कोड लिखें. ऐसा तब करें, जब स्टोर की जगह, मैप के व्यूपोर्ट में मौजूद हो.
Place Details एलिमेंट का इस्तेमाल करके, जगह की ज़्यादा जानकारी दिखाना
इस स्टेज पर, ऐप्लिकेशन सभी स्टोर की जगहें दिखाता है. साथ ही, उपयोगकर्ता उन्हें मैप व्यूपोर्ट के आधार पर फ़िल्टर कर सकते हैं. इसे बेहतर बनाने के लिए, हर स्टोर की ज़्यादा जानकारी जोड़ी जाती है. जैसे, फ़ोटो, समीक्षाएं, और सुलभता की जानकारी. इसके लिए, Place Details एलिमेंट का इस्तेमाल किया जाता है. इस उदाहरण में, खास तौर पर Place Details Compact Element का इस्तेमाल किया गया है.
आपके डेटा सोर्स में मौजूद हर स्टोर की जगह के लिए, उससे जुड़ा जगह का आईडी होना चाहिए. यह आईडी, Google Maps पर जगह की खास तौर पर पहचान करता है. साथ ही, इसकी जानकारी फ़ेच करने के लिए ज़रूरी है. आम तौर पर, आपको ये जगह के आईडी पहले से ही मिल जाते हैं. साथ ही, इन्हें अपने हर स्टोर के रिकॉर्ड में सेव किया जाता है.
ऐप्लिकेशन में Place Details Compact Element को इंटिग्रेट करना
जब किसी स्टोर को मौजूदा मैप व्यूपोर्ट में दिखाया जाता है और उसे साइडबार में रेंडर किया जाता है, तो उसके लिए डाइनैमिक तौर पर, जगह की जानकारी वाला कॉम्पैक्ट एलिमेंट बनाया और शामिल किया जा सकता है.
जिस स्टोर को प्रोसेस किया जा रहा है उसके लिए, अपने डेटा से जगह का आईडी वापस पाएं. जगह के आईडी का इस्तेमाल करके, यह कंट्रोल किया जाता है कि एलिमेंट किस जगह को दिखाएगा.
JavaScript में, PlaceDetailsCompactElement का एक इंस्टेंस डाइनैमिक तौर पर बनाएं. एक नया PlaceDetailsPlaceRequestElement भी बनाया जाता है. इसमें जगह का आईडी पास किया जाता है और इसे PlaceDetailsCompactElement में जोड़ दिया जाता है. आखिर में, PlaceContentConfigElement का इस्तेमाल करके, एलिमेंट में दिखने वाले कॉन्टेंट को कॉन्फ़िगर करें.
यहां दिए गए फ़ंक्शन के लिए यह ज़रूरी है कि जगहों की जानकारी देने वाली यूआई किट की ज़रूरी लाइब्रेरी इंपोर्ट की गई हों और उस स्कोप में उपलब्ध हों जहां इस फ़ंक्शन को कॉल किया जाता है. साथ ही, फ़ंक्शन को पास किए गए storeData में place_id शामिल हो.
यह फ़ंक्शन एलिमेंट को दिखाएगा और कॉलिंग कोड, इसे डीओएम में जोड़ने के लिए ज़िम्मेदार होगा.
function createPlaceDetailsCompactElement(storeData) {
// Create the main details component
const detailsCompact = new PlaceDetailsCompactElement();
detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'
// Specify the Place ID
const placeRequest = new PlaceDetailsPlaceRequestElement();
placeRequest.place = storeData.place_id;
detailsCompact.appendChild(placeRequest);
// Configure which content elements to display
const contentConfig = new PlaceContentConfigElement();
// For this example, we'll render media, rating, accessibility, and attribution:
contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
contentConfig.appendChild(new PlaceRatingElement());
contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
// Configure attribution
const placeAttribution = new PlaceAttributionElement();
placeAttribution.setAttribute('light-scheme-color', 'gray');
placeAttribution.setAttribute('dark-scheme-color', 'gray');
contentConfig.appendChild(placeAttribution);
detailsCompact.appendChild(contentConfig);
// Return the element
return detailsCompact;
}
ऊपर दिए गए कोड के उदाहरण में, एलिमेंट को जगह की फ़ोटो, समीक्षा की रेटिंग, और सुलभता की जानकारी दिखाने के लिए कॉन्फ़िगर किया गया है. इसे पसंद के मुताबिक बनाया जा सकता है. इसके लिए, उपलब्ध अन्य कॉन्टेंट एलिमेंट को जोड़ा या हटाया जा सकता है. उपलब्ध सभी विकल्पों के लिए, PlaceContentConfigElement दस्तावेज़ देखें.
जगह की जानकारी देने वाले छोटे एलिमेंट को सीएसएस की कस्टम प्रॉपर्टी की मदद से स्टाइल किया जा सकता है. इससे आपको अपने ऐप्लिकेशन के डिज़ाइन से मैच करने के लिए, उसके लुक (रंग, फ़ॉन्ट वगैरह) को पसंद के मुताबिक बनाने की सुविधा मिलती है. इन कस्टम प्रॉपर्टी को अपनी सीएसएस फ़ाइल में लागू करें. इस्तेमाल की जा सकने वाली सीएसएस प्रॉपर्टी के लिए, PlaceDetailsCompactElement का रेफ़रंस दस्तावेज़ देखें.
इस चरण में आपका आवेदन कुछ इस तरह दिख सकता है:
स्टोर खोजने की सुविधा को बेहतर बनाना
आपने स्टोर फ़ाइंडर ऐप्लिकेशन के लिए एक मज़बूत बुनियाद तैयार कर ली है. अब, इसकी सुविधाओं को बढ़ाने और उपयोगकर्ताओं को बेहतर और ज़्यादा उपयोगकर्ता-केंद्रित अनुभव देने के कई तरीकों पर विचार करें.
ऑटोकंप्लीट की सुविधा जोड़ना
किसी जगह के शुरुआती अक्षर लिखने पर पूरा नाम सुझाने की सुविधा के साथ खोज के लिए इनपुट को इंटिग्रेट करें. इससे उपयोगकर्ताओं को स्टोर खोजने के लिए, इलाकों को ढूंढने में आसानी होगी. जब उपयोगकर्ता कोई पता, आस-पास की जगह या लोकप्रिय जगह टाइप करते हैं और कोई सुझाव चुनते हैं, तो मैप को इस तरह प्रोग्राम करें कि वह अपने-आप उस जगह पर फ़ोकस हो जाए. इससे आस-पास के स्टोर की जानकारी अपडेट हो जाएगी. इसके लिए, एक इनपुट फ़ील्ड जोड़ें और उसमें किसी जगह के शुरुआती अक्षर लिखने पर पूरा नाम सुझाने की सुविधा अटैच करें. किसी सुझाव को चुनने पर, मैप को उस जगह पर फ़ोकस किया जा सकता है. इसे कॉन्फ़िगर करना न भूलें, ताकि नतीजे आपके कारोबार के इलाके के हिसाब से दिखें या सिर्फ़ उसी इलाके तक सीमित रहें.
जगह की जानकारी का पता लगाना
खास तौर पर मोबाइल उपयोगकर्ताओं के लिए, तुरंत काम की जानकारी उपलब्ध कराएं. इसके लिए, उनकी मौजूदा भौगोलिक जगह का पता लगाने की सुविधा लागू करें. उपयोगकर्ता की जगह की जानकारी का पता लगाने के लिए, ब्राउज़र की अनुमति मिलने के बाद, मैप को अपने-आप उपयोगकर्ता की जगह पर सेट करें और आस-पास के स्टोर दिखाएं. जब उपयोगकर्ताओं को तुरंत कोई विकल्प चाहिए होता है, तो वे मेरे आस-पास सुविधा को काफ़ी अहमियत देते हैं. जगह की जानकारी का ऐक्सेस मांगने के लिए, कोई बटन या शुरुआती प्रॉम्प्ट जोड़ें.
दूरी और दिशा-निर्देश दिखाना
जब कोई उपयोगकर्ता अपनी पसंद का स्टोर चुन लेता है, तो Routes API को इंटिग्रेट करके, उसके अनुभव को बेहतर बनाएं. आपने जो भी स्टोर लिस्ट किया है उसके लिए, उपयोगकर्ता की मौजूदा जगह या खोजी गई जगह से दूरी का हिसाब लगाएं और उसे दिखाएं. इसके अलावा, कोई ऐसा बटन या लिंक दें जो Routes API का इस्तेमाल करके, उपयोगकर्ता की जगह से चुने गए स्टोर तक का रास्ता जनरेट करे. इसके बाद, इस रास्ते को अपने मैप पर दिखाया जा सकता है या नेविगेशन के लिए Google Maps से लिंक किया जा सकता है. इससे, स्टोर ढूंढने से लेकर वहां पहुंचने तक का अनुभव बेहतर हो जाता है.
इन एक्सटेंशन को लागू करके, Google Maps Platform की ज़्यादा सुविधाओं का इस्तेमाल किया जा सकता है. इससे, ज़्यादा बेहतर और सुविधाजनक स्टोर लोकेटर बनाया जा सकता है. यह लोकेटर, उपयोगकर्ताओं की सामान्य ज़रूरतों को सीधे तौर पर पूरा करता है.
नतीजा
इस गाइड में, इंटरैक्टिव स्टोर फ़ाइंडर बनाने के मुख्य चरणों के बारे में बताया गया है. आपने Maps JavaScript API का इस्तेमाल करके, मैप पर अपने स्टोर की जगहों की जानकारी दिखाने का तरीका सीख लिया है. साथ ही, व्यूपोर्ट में होने वाले बदलावों के आधार पर, दिखने वाले स्टोर की जानकारी को डाइनैमिक तौर पर अपडेट करने का तरीका भी जान लिया है. इसके अलावा, आपने यह भी सीख लिया है कि जगहों की जानकारी देने वाली यूआई किट के साथ, अपने स्टोर का डेटा कैसे दिखाया जाता है. Place Details एलिमेंट के साथ, जगह के आईडी जैसी अपने स्टोर की मौजूदा जानकारी का इस्तेमाल करके, अपनी हर जगह के लिए ज़्यादा और स्टैंडर्ड जानकारी दिखाई जा सकती है. इससे, उपयोगकर्ता के लिए आसान स्टोर लोकेटर बनाने में मदद मिलती है.
Maps JavaScript API और जगहों की जानकारी देने वाली यूआई किट आज़माएं. इससे आपको कॉम्पोनेंट पर आधारित बेहतरीन टूल मिलेंगे. इनकी मदद से, जगह की जानकारी देने वाले बेहतर ऐप्लिकेशन तेज़ी से बनाए जा सकते हैं. इन सुविधाओं को मिलाकर, उपयोगकर्ताओं के लिए दिलचस्प और जानकारी देने वाले अनुभव बनाए जा सकते हैं.
योगदानकर्ता
हेनरिक वाल्व | DevX इंजीनियर