Maps JavaScript API लोड करना

इस गाइड में, Maps JavaScript API को लोड करने का तरीका बताया गया है. ऐसा करने के तीन तरीके हैं:

• डाइनैमिक लाइब्रेरी इंपोर्ट का इस्तेमाल करें
• डायरेक्ट स्क्रिप्ट लोडिंग टैग का इस्तेमाल करना
• NPM js-api-loader पैकेज का इस्तेमाल करना

डाइनैमिक लाइब्रेरी इंपोर्ट का इस्तेमाल करना

डाइनैमिक लाइब्रेरी इंपोर्ट की मदद से, रनटाइम के दौरान लाइब्रेरी लोड की जा सकती हैं. इससे आपको ज़रूरत पड़ने पर, ज़रूरी लाइब्रेरी का अनुरोध करने की सुविधा मिलती है. इसके लिए, आपको लोड होने के समय सभी लाइब्रेरी का अनुरोध एक साथ करने की ज़रूरत नहीं होती. यह आपके पेज को Maps JavaScript API को कई बार लोड करने से भी बचाता है.

अपने ऐप्लिकेशन कोड में इनलाइन बूटस्ट्रैप लोडर जोड़कर, Maps JavaScript API को लोड करें. इसके लिए, यहां दिया गया स्निपेट देखें:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

बूटस्ट्रैप लोडर कोड को सीधे अपने JavaScript कोड में भी जोड़ा जा सकता है.

रनटाइम के दौरान लाइब्रेरी लोड करने के लिए, await ऑपरेटर का इस्तेमाल करके async फ़ंक्शन से importLibrary() को कॉल करें. ज़रूरी क्लास के लिए वैरिएबल तय करने से, आपको क्वालिफ़ाइड पाथ (जैसे, google.maps.Map) का इस्तेमाल करने की ज़रूरत नहीं पड़ती. इसके बारे में यहां दिए गए कोड के उदाहरण में बताया गया है:

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();
index.js

जब आपके ऐप्लिकेशन को एक ही समय पर कई लाइब्रेरी की ज़रूरत हो, तो उन्हें एक साथ लोड करने का अनुरोध करने के लिए, Promise.all() का इस्तेमाल करें:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

एक के बाद एक अलग-अलग लाइनों में await google.maps.importLibrary() को कॉल करने से बचें. क्रम में चलने वाले await स्टेटमेंट, कोड के लागू होने की प्रोसेस को तब तक रोकते हैं, जब तक कि हर लाइब्रेरी डाउनलोड और शुरू नहीं हो जाती. इसके बाद ही, अगली लाइब्रेरी का अनुरोध किया जाता है. इससे नेटवर्क वॉटरफ़ॉल बनता है, जिससे लोड होने में ज़्यादा समय लगता है. Promise.all(), लाइब्रेरी के सभी डाउनलोड एक साथ शुरू करता है. साथ ही, सभी डाउनलोड पूरे होने पर, यह प्रोसेस पूरी हो जाती है.

आपका फ़ंक्शन, ज़रूरी क्लास के लिए वैरिएबल का एलान किए बिना भी लाइब्रेरी लोड कर सकता है. यह खास तौर पर तब काम आता है, जब आपने gmp-map एलिमेंट का इस्तेमाल करके मैप जोड़ा हो. वैरिएबल के बिना, आपको क्वालिफ़ाइड पाथ का इस्तेमाल करना होगा. उदाहरण के लिए, google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    google.maps.importLibrary("marker"),
  ]);

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

इसके अलावा, लाइब्रेरी को सीधे एचटीएमएल में लोड किया जा सकता है, जैसा कि यहां दिखाया गया है:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

डाइनैमिक लाइब्रेरी लोडिंग एपीआई पर माइग्रेट करने का तरीका जानें.

ज़रूरी पैरामीटर

• key: आपकी एपीआई कुंजी. Maps JavaScript API तब तक लोड नहीं होगा, जब तक कोई मान्य एपीआई पासकोड नहीं दिया जाता.

ज़रूरी नहीं पैरामीटर

• v: Maps JavaScript API का वह वर्शन जिसे लोड करना है. अगर आपने साफ़ तौर पर कोई चैनल या वर्शन नहीं चुना है, तो आपको डिफ़ॉल्ट रूप से वीकली चैनल मिलेगा. अगर आपने प्रीमियम प्लान से माइग्रेट किया है और साफ़ तौर पर कोई चैनल या वर्शन नहीं चुना है, तो आपको डिफ़ॉल्ट रूप से तिमाही चैनल मिलेगा. अगर आपने कोई अमान्य वर्शन चुना है, तो आपको डिफ़ॉल्ट चैनल मिलेगा. ज़्यादा जानें.

• libraries: Maps JavaScript API की अतिरिक्त लाइब्रेरी का कलेक्शन, ताकि प्रीलोडिंग शुरू की जा सके. आम तौर पर, लाइब्रेरी का एक तय सेट तय करने का सुझाव नहीं दिया जाता. हालांकि, यह उन डेवलपर के लिए उपलब्ध है जो अपनी वेबसाइट पर कैश मेमोरी के काम करने के तरीके को बेहतर बनाना चाहते हैं. इस्तेमाल करने से पहले, चुनी गई हर लाइब्रेरी के लिए google.maps.importLibrary() को कॉल करना अब भी ज़रूरी है.

• language: इस्तेमाल की जाने वाली भाषा. इससे कंट्रोल के नाम, कॉपीराइट की सूचनाएं, ड्राइविंग के लिए रास्ते के निर्देश, और कंट्रोल लेबल पर असर पड़ता है. साथ ही, सेवा के अनुरोधों के जवाबों पर भी असर पड़ता है. उपलब्ध भाषाओं की सूची देखें.

• region: इस्तेमाल किया जाने वाला इलाका कोड. इससे किसी देश या इलाके के हिसाब से, एपीआई के काम करने का तरीका बदल जाता है.

• authReferrerPolicy: Maps JS के ग्राहक, Cloud Console में एचटीटीपी रेफ़रल से जुड़ी पाबंदियां कॉन्फ़िगर कर सकते हैं. इससे यह तय किया जा सकता है कि किन यूआरएल को किसी खास एपीआई पासकोड का इस्तेमाल करने की अनुमति है. डिफ़ॉल्ट रूप से, इन पाबंदियों को इस तरह कॉन्फ़िगर किया जा सकता है कि एपीआई पासकोड का इस्तेमाल सिर्फ़ कुछ पाथ के लिए किया जा सके. अगर एक ही डोमेन या ऑरिजिन पर मौजूद कोई यूआरएल, एपीआई पासकोड का इस्तेमाल कर सकता है, तो authReferrerPolicy: "origin" को सेट किया जा सकता है. इससे Maps JavaScript API से किए गए अनुरोधों को अनुमति देते समय, भेजे जाने वाले डेटा की मात्रा को सीमित किया जा सकता है. अगर यह पैरामीटर तय किया गया है और Cloud Console पर एचटीटीपी रेफ़रलकर्ता से जुड़ी पाबंदियां चालू हैं, तो Maps JavaScript API सिर्फ़ तब लोड हो पाएगा, जब एचटीटीपी रेफ़रलकर्ता से जुड़ी पाबंदी, मौजूदा वेबसाइट के डोमेन से मैच करती हो. इसके लिए, पाथ तय करने की ज़रूरत नहीं है.

• mapIds: मैप आईडी का कलेक्शन. इससे, तय किए गए मैप आईडी के लिए कॉन्फ़िगरेशन पहले से लोड हो जाता है. मैप आईडी इस्तेमाल करने के लिए, यहां मैप आईडी की जानकारी देना ज़रूरी नहीं है. हालांकि, यह सुविधा उन डेवलपर के लिए उपलब्ध है जो नेटवर्क की परफ़ॉर्मेंस को बेहतर बनाना चाहते हैं.

• channel: हर चैनल के लिए इस्तेमाल को ट्रैक करने की सुविधा देखें.

डायरेक्ट स्क्रिप्ट लोडिंग टैग का इस्तेमाल करना

इस सेक्शन में, डायरेक्ट स्क्रिप्ट लोडिंग टैग को इस्तेमाल करने का तरीका बताया गया है. डायरेक्ट स्क्रिप्ट, मैप लोड होने पर लाइब्रेरी लोड करती है. इसलिए, यह gmp-map एलिमेंट का इस्तेमाल करके बनाए गए मैप को आसान बना सकती है. इसके लिए, रनटाइम के दौरान लाइब्रेरी का अनुरोध करने की ज़रूरत नहीं पड़ती. स्क्रिप्ट लोड होने पर, डायरेक्ट स्क्रिप्ट लोडिंग टैग, अनुरोध की गई सभी लाइब्रेरी को एक साथ लोड करता है. इसलिए, कुछ ऐप्लिकेशन की परफ़ॉर्मेंस पर असर पड़ सकता है. पेज लोड होने पर, डायरेक्ट स्क्रिप्ट लोडिंग टैग को सिर्फ़ एक बार शामिल करें.

ध्यान दें: डायरेक्ट स्क्रिप्ट लोडिंग टैग के लोड होने के बाद, importLibrary को कॉल किया जा सकता है.

स्क्रिप्ट टैग जोड़ना

किसी एचटीएमएल फ़ाइल में Maps JavaScript API को इनलाइन लोड करने के लिए, यहां दिखाए गए तरीके से script टैग जोड़ें.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

डायरेक्ट स्क्रिप्ट लोडिंग यूआरएल पैरामीटर

इस सेक्शन में उन सभी पैरामीटर के बारे में बताया गया है जिन्हें Maps JavaScript API लोड करते समय, स्क्रिप्ट लोड करने वाले यूआरएल की क्वेरी स्ट्रिंग में तय किया जा सकता है. कुछ पैरामीटर ज़रूरी होते हैं, जबकि कुछ ज़रूरी नहीं होते. यूआरएल में स्टैंडर्ड के तौर पर, सभी पैरामीटर को एंपरसैंड (&) वर्ण का इस्तेमाल करके अलग किया जाता है.

यहां दिए गए उदाहरण वाले यूआरएल में, सभी संभावित पैरामीटर के लिए प्लेसहोल्डर मौजूद हैं:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

यहां दिए गए उदाहरण में मौजूद script टैग का यूआरएल, Maps JavaScript API को लोड करता है:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

ज़रूरी पैरामीटर (डायरेक्ट)

Maps JavaScript API को लोड करते समय, ये पैरामीटर ज़रूरी हैं.

• key: आपकी एपीआई कुंजी. Maps JavaScript API तब तक लोड नहीं होगा, जब तक कोई मान्य एपीआई पासकोड नहीं दिया जाता.

वैकल्पिक पैरामीटर (डायरेक्ट)

Maps JavaScript API के किसी खास वर्शन का अनुरोध करने, अतिरिक्त लाइब्रेरी लोड करने, अपने मैप को स्थानीय भाषा में उपलब्ध कराने या एचटीटीपी रेफ़रर की जांच करने की नीति तय करने के लिए, इन पैरामीटर का इस्तेमाल करें

• loading: कोड लोड करने की रणनीति, जिसका इस्तेमाल Maps JavaScript API कर सकता है. इसे async पर सेट करें, ताकि यह पता चल सके कि Maps JavaScript API को सिंक्रोनस तरीके से लोड नहीं किया गया है. साथ ही, स्क्रिप्ट के load इवेंट से कोई JavaScript कोड ट्रिगर नहीं हुआ है. बेहतर परफ़ॉर्मेंस के लिए, हमारा सुझाव है कि जब भी संभव हो, इसे async पर सेट करें. (Maps JavaScript API उपलब्ध होने पर, कार्रवाइयां करने के लिए callback पैरामीटर का इस्तेमाल करें.) यह वर्शन 3.55 से उपलब्ध है.

• callback: Maps JavaScript API के पूरी तरह से लोड होने के बाद, कॉल किए जाने वाले ग्लोबल फ़ंक्शन का नाम.

• v: Maps JavaScript API का वह वर्शन जिसका इस्तेमाल करना है.

• libraries: Maps JavaScript API की अतिरिक्त लाइब्रेरी की कॉमा लगाकर अलग की गई सूची, जिसे लोड करना है.

• language: इस्तेमाल की जाने वाली भाषा. इससे कंट्रोल के नाम, कॉपीराइट वाले कॉन्टेंट की सूचनाएं, ड्राइविंग के लिए रास्ते के निर्देश, और कंट्रोल लेबल पर असर पड़ता है. साथ ही, सेवा के अनुरोधों के जवाबों पर भी असर पड़ता है. उपलब्ध भाषाओं की सूची देखें.

• region: इस्तेमाल किया जाने वाला इलाका कोड. इससे किसी देश या इलाके के हिसाब से, एपीआई के काम करने का तरीका बदल जाता है.

• auth_referrer_policy: ग्राहक, Cloud Console में एचटीटीपी रेफ़रल से जुड़ी पाबंदियां कॉन्फ़िगर कर सकते हैं. इससे यह तय किया जा सकता है कि किन यूआरएल को किसी खास एपीआई पासकोड का इस्तेमाल करने की अनुमति है. डिफ़ॉल्ट रूप से, इन पाबंदियों को इस तरह कॉन्फ़िगर किया जा सकता है कि सिर्फ़ कुछ पाथ के लिए एपीआई पासकोड का इस्तेमाल किया जा सके. अगर उसी डोमेन या ऑरिजिन का कोई यूआरएल, एपीआई पासकोड का इस्तेमाल कर सकता है, तो auth_referrer_policy=origin को सेट किया जा सकता है. इससे Maps JavaScript API से अनुरोधों को अनुमति देते समय, भेजे जाने वाले डेटा की मात्रा को सीमित किया जा सकता है. यह सुविधा, वर्शन 3.46 और उसके बाद के वर्शन में उपलब्ध है. अगर यह पैरामीटर सेट है और Cloud Console पर एचटीटीपी रेफ़रलकर्ता से जुड़ी पाबंदियां चालू हैं, तो Maps JavaScript API सिर्फ़ तब लोड हो पाएगा, जब एचटीटीपी रेफ़रलकर्ता से जुड़ी कोई पाबंदी, मौजूदा वेबसाइट के डोमेन से मैच करती हो. इसके लिए, पाथ की जानकारी देना ज़रूरी नहीं है.

• map_ids: मैप आईडी की कॉमा लगाकर अलग की गई लिस्ट. इससे, तय किए गए मैप आईडी का कॉन्फ़िगरेशन पहले से लोड हो जाता है. मैप आईडी का इस्तेमाल करने के लिए, यहां मैप आईडी की जानकारी देना ज़रूरी नहीं है. हालांकि, यह सुविधा उन डेवलपर के लिए उपलब्ध है जो नेटवर्क की परफ़ॉर्मेंस को बेहतर बनाना चाहते हैं.

• channel: हर चैनल के हिसाब से इस्तेमाल को ट्रैक करना देखें.

NPM js-api-loader पैकेज का इस्तेमाल करना

अहम जानकारी: v2.0.0 रिलीज़, एक बड़ा रीफ़ैक्टर है. यह पुरानी Loader क्लास को एक ऐसे एपीआई से बदल देता है जिसमें दो फ़ंक्शन होते हैं: setOptions() और importLibrary(). इस बदलाव से, आपको Maps API की अलग-अलग लाइब्रेरी को मांग पर डाइनैमिक तरीके से लोड करने की सुविधा मिलती है. इससे, शुरुआती पेज की परफ़ॉर्मेंस को बेहतर बनाने के लिए, सुविधाओं को डाउनलोड करने में देरी होती है.

@googlemaps/js-api-loader पैकेज उपलब्ध है. इसे NPM पैकेज मैनेजर का इस्तेमाल करके लोड किया जा सकता है. इसे इंस्टॉल करने के लिए, इस कमांड का इस्तेमाल करें:

npm install @googlemaps/js-api-loader

पैकेज को यहां दिखाए गए तरीके से इंपोर्ट करें:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.ts

ध्यान दें: TypeScript और Google Maps का इस्तेमाल करने के बारे में जानने के लिए, गाइड पढ़ें.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.js

लाइब्रेरी उपलब्ध कराने के लिए, लोडर Promises का इस्तेमाल करता है. importLibrary() तरीके का इस्तेमाल करके लाइब्रेरी लोड करें. यहां दिए गए उदाहरण में, मैप लोड करने के लिए लोडर का इस्तेमाल करने का तरीका बताया गया है:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();
index.ts

ध्यान दें: TypeScript और Google Maps का इस्तेमाल करने के बारे में जानने के लिए, गाइड पढ़ें.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map'), mapOptions);
}

void init();
index.js

उदाहरण के तौर पर दिया गया पूरा कोड देखें.

Dynamic Library Import API पर माइग्रेट करना

इस सेक्शन में, डाइनैमिक लाइब्रेरी इंपोर्ट एपीआई का इस्तेमाल करने के लिए, इंटिग्रेशन को माइग्रेट करने का तरीका बताया गया है.

माइग्रेट करने का तरीका

सबसे पहले, डायरेक्ट स्क्रिप्ट लोडिंग टैग को इनलाइन बूटस्ट्रैप लोडर टैग से बदलें.

पहले

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

बाद में

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

इसके बाद, अपने ऐप्लिकेशन कोड को अपडेट करें:

• अपने initMap() फ़ंक्शन को एसिंक्रोनस में बदलें.
• अपनी ज़रूरत की लाइब्रेरी लोड करने और उन्हें ऐक्सेस करने के लिए, importLibrary() को कॉल करें.

पहले

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

बाद में

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();

एक से ज़्यादा लाइब्रेरी लोड करना

एक से ज़्यादा लाइब्रेरी लोड करने के लिए, Promise.all() का इस्तेमाल करें. इससे लाइब्रेरी के लिए एक साथ अनुरोध किया जा सकता है और वापस की गई क्लास को डिस्ट्रक्चर किया जा सकता है:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

अलग-अलग await स्टेटमेंट को जोड़कर, लाइब्रेरी को क्रम से लोड न करें:

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

जब हर importLibrary() कॉल को एक के बाद एक await किया जाता है, तो लाइब्रेरी का दूसरा अनुरोध तब तक शुरू नहीं होता, जब तक पहली लाइब्रेरी पूरी तरह से डाउनलोड और शुरू नहीं हो जाती. Promise.all() का इस्तेमाल करने से, लाइब्रेरी के सभी अनुरोध एक साथ शुरू होते हैं. इससे नेटवर्क इंतज़ार का समय कम होता है और शुरू होने की स्पीड बेहतर होती है.