Maps JavaScript API লোড করা

এই গাইড থেকে আপনি Maps JavaScript API কীভাবে লোড করবেন তা জানতে পারবেন। এটি করার তিনটি উপায় আছে:

ডায়নামিক লাইব্রেরি ইমপোর্ট ব্যবহার করা

ডায়নামিক লাইব্রেরি ইমপোর্ট করার মাধ্যমে রানটাইমে লাইব্রেরি লোড করার সুবিধা পাওয়া যায়। এর ফলে, লোড টাইমে সব লাইব্রেরি একসাথে অনুরোধ করার পরিবর্তে, আপনার যখন যে লাইব্রেরি প্রয়োজন, তখন সেটির জন্য অনুরোধ করতে পারবেন। এছাড়াও, এটি আপনার পৃষ্ঠাটিকে একাধিকবার 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 কোডে বুটস্ট্র্যাপ লোডার কোড যোগ করতে পারবেন।

রানটাইমে লাইব্রেরি লোড করতে, async ফাংশনের মধ্যে থেকে importLibrary() কল করতে await অপারেটর ব্যবহার করুন। প্রয়োজনীয় ক্লাসের জন্য ভেরিয়েবল ঘোষণা করলে, আপনি কোয়ালিফায়েড পাথ (যেমন, 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();

আপনার অ্যাপ্লিকেশনের একই সময়ে একাধিক লাইব্রেরির প্রয়োজন হলে, সেগুলি সমান্তরালভাবে অনুরোধ করতে 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();

বিকল্প হিসেবে, এখানে দেখানো পদ্ধতি অনুযায়ী আপনি সরাসরি HTML-এ লাইব্রেরি লোড করতে পারেন:

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

কীভাবে Dynamic Library Loading API-তে মাইগ্রেট করবেন তা জানুন।

প্রয়োজনীয় প্যারামিটার

  • key: আপনার API কী। সঠিক API key উল্লেখ না করা পর্যন্ত Maps JavaScript API লোড হবে না।

ঐচ্ছিক প্যারামিটার

  • v: Maps JavaScript API-এর যে ভার্সন লোড করতে হবে। আপনি কোনও চ্যানেল বা ভার্সন স্পষ্টভাবে উল্লেখ না করলে, আপনি ডিফল্ট হিসেবে সাপ্তাহিক চ্যানেল পাবেন। আপনি যদি Premium প্ল্যান থেকে মাইগ্রেট করে থাকেন এবং কোনও চ্যানেল বা ভার্সন নির্দিষ্ট না করে থাকেন, তাহলে ডিফল্ট হিসেবে ত্রৈমাসিক চ্যানেল পাবেন। আপনি কোনও ভুল ভার্সন উল্লেখ করলে, আপনার ডিফল্ট চ্যানেলটি পাবেন। আরও জানুন।

  • libraries: Maps JavaScript API-এর অতিরিক্ত অ্যারে লাইব্রেরি যা প্রি-লোডিং শুরু করবে। সাধারণত লাইব্রেরির একটি নির্দিষ্ট সেট নির্দিষ্ট করার পরামর্শ দেওয়া হয় না, তবে যেসব ডেভেলপার তাদের ওয়েবসাইটে ক্যাশিং আচরণকে ফাইন-টিউন করতে চান তাদের জন্য উপলভ্য। ব্যবহার করার আগে প্রতিটি বেছে নেওয়া লাইব্রেরির জন্য google.maps.importLibrary()-এ কল করা এখনও গুরুত্বপূর্ণ।

  • language: ব্যবহার করার জন্য ভাষা। এর ফলে কন্ট্রোলের নাম, কপিরাইট বিজ্ঞপ্তি, ড্রাইভিং নির্দেশাবলী, কন্ট্রোল লেবেল এবং পরিষেবা সংক্রান্ত অনুরোধের উত্তর প্রভাবিত হয়। অনুমোদিত ভাষার তালিকা দেখুন।

  • region: ব্যবহার করার জন্য অঞ্চল কোড। এটি কোনও নির্দিষ্ট দেশ বা অঞ্চলের উপর ভিত্তি করে API-এর আচরণ পরিবর্তন করে।

  • authReferrerPolicy: Maps JS গ্রাহকরা Cloud Console-এ HTTP রেফারার বিধিনিষেধ কনফিগার করতে পারেন, এর ফলে কোন URL একটি নির্দিষ্ট API কী ব্যবহার করতে পারবে তা সীমিত করা যায়। ডিফল্ট হিসেবে, এই বিধিনিষেধগুলি API কী ব্যবহার করার জন্য শুধুমাত্র নির্দিষ্ট পাথকে অনুমতি দেওয়ার জন্য কনফিগার করা যেতে পারে। একই ডোমেন বা উৎসের কোনও URL যদি API Key ব্যবহার করে, তাহলে Maps JavaScript API থেকে অনুরোধ অনুমোদন করার সময় পাঠানো ডেটার পরিমাণ সীমিত করতে আপনি authReferrerPolicy: "origin" সেট করতে পারেন। এই প্যারামিটার নির্দিষ্ট করা থাকলে এবং Cloud Console-এ HTTP রেফারার সংক্রান্ত বিধিনিষেধ চালু করা থাকলে, Maps JavaScript API শুধুমাত্র তখনই লোড হতে পারবে যদি এমন কোনও HTTP রেফারার সংক্রান্ত বিধিনিষেধ থাকে যা বর্তমান ওয়েবসাইটের ডোমেনের সাথে মিলে যায় এবং কোনও পাথ নির্দিষ্ট করা না থাকে।

  • mapIds: ম্যাপ আইডির একটি অ্যারে। নির্দিষ্ট ম্যাপ আইডির কনফিগারেশন প্রিলোড করে। এখানে ম্যাপ আইডি নির্দিষ্ট করা ম্যাপ আইডি ব্যবহারের জন্য প্রয়োজন নেই, তবে যে ডেভেলপাররা নেটওয়ার্ক পারফর্ম্যান্স ফাইন-টিউন করতে চান তাদের জন্য উপলভ্য।

  • channel: প্রতি চ্যানেল ব্যবহার ট্র্যাক করা দেখুন।

সরাসরি স্ক্রিপ্ট লোডিং ট্যাগ ব্যবহার করুন

এই বিভাগে দেখানো হয়েছে যে কীভাবে ডাইরেক্ট স্ক্রিপ্ট লোডিং ট্যাগ ব্যবহার করতে হয়। কারণ ম্যাপ লোড হওয়ার সময় সরাসরি স্ক্রিপ্ট লাইব্রেরি লোড করে, তাই রানটাইমে স্পষ্টভাবে লাইব্রেরির জন্য অনুরোধ করার প্রয়োজনীয়তা সরিয়ে দিয়ে, gmp-map এলিমেন্ট ব্যবহার করে তৈরি করা ম্যাপকে এটি সহজ করে তুলতে পারে। ডাইরেক্ট স্ক্রিপ্ট লোডিং ট্যাগ স্ক্রিপ্ট লোড করার সময় সব অনুরোধ করা লাইব্রেরি একসাথে লোড করে বলে, কিছু অ্যাপ্লিকেশনের পারফর্ম্যান্স প্রভাবিত হতে পারে। প্রতিটি পৃষ্ঠা লোড করার সময় শুধুমাত্র একবার ডাইরেক্ট স্ক্রিপ্ট লোডিং ট্যাগ যোগ করুন।

স্ক্রিপ্ট ট্যাগ যোগ করা

HTML ফাইলে Maps JavaScript API ইনলাইন লোড করতে, নিচে দেখানো মতো script ট্যাগ যোগ করুন।

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

সরাসরি স্ক্রিপ্ট লোডিং URL প্যারামিটার

Maps JavaScript API লোড করার সময় স্ক্রিপ্ট লোডিং URL-এর কোয়েরি স্ট্রিংয়ে আপনি যেসব প্যারামিটার নির্দিষ্ট করতে পারেন, এই বিভাগে সেগুলি নিয়ে আলোচনা করা হয়েছে। কিছু প্যারামিটার প্রয়োজন হলেও অন্যান্য প্যারামিটার ঐচ্ছিক। URL-এর ক্ষেত্রে স্ট্যান্ডার্ড হিসেবে, সব প্যারামিটারকে অ্যামপারস্যান্ড (&) অক্ষর ব্যবহার করে আলাদা করা হয়।

নিম্নলিখিত উদাহরণ URL-এ সব সম্ভাব্য প্যারামিটারের জন্য প্লেসহোল্ডার আছে:

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: আপনার API কী। সঠিক API কী উল্লেখ না করা পর্যন্ত Maps JavaScript API লোড হবে না।

ঐচ্ছিক প্যারামিটার (সরাসরি)

Maps JavaScript API-এর নির্দিষ্ট ভার্সনের জন্য অনুরোধ করতে, অতিরিক্ত লাইব্রেরি লোড করতে, আপনার ম্যাপ লোকালাইজ করতে বা HTTP রেফারার চেক করার নীতি নির্দিষ্ট করতে এইসব প্যারামিটার ব্যবহার করুন

  • loading: Maps JavaScript API ব্যবহার করতে পারে এমন কোড লোডিং কৌশল। async-এ সেট করুন যাতে বোঝা যায় যে Maps JavaScript API সিঙ্ক্রোনাসভাবে লোড করা হয়নি এবং স্ক্রিপ্টের load ইভেন্ট দ্বারা কোনও জাভাস্ক্রিপ্ট কোড ট্রিগার করা হয়নি। আরও ভালো পারফর্ম্যান্সের জন্য, যখনই সম্ভব, এটি async-এ সেট করার জন্য সাজেস্ট করা হয়। (Maps JavaScript API উপলভ্য হলে অ্যাকশন পারফর্ম করতে callback প্যারামিটার ব্যবহার করুন।) ভার্সন ৩.৫৫ থেকে উপলভ্য।

  • callback: Maps JavaScript API সম্পূর্ণভাবে লোড হয়ে গেলে, গ্লোবাল ফাংশনের যে নাম কল করা হবে।

  • v: Maps JavaScript API-এর যে ভার্সন ব্যবহার করতে হবে।

  • libraries: লোড করার জন্য অতিরিক্ত Maps JavaScript API লাইব্রেরির কমা দিয়ে আলাদা করা তালিকা।

  • language: ব্যবহার করার জন্য ভাষা। এটি কন্ট্রোলের নাম, কপিরাইট বিজ্ঞপ্তি, গাড়ি চালানোর দিকনির্দেশ, কন্ট্রোল লেবেল এবং পরিষেবা অনুরোধের উত্তরে প্রভাব ফেলে। অনুমোদিত ভাষার তালিকা দেখুন।

  • region: ব্যবহার করার জন্য অঞ্চল কোড। এটি কোনও নির্দিষ্ট দেশ বা অঞ্চলের উপর ভিত্তি করে API-এর আচরণ পরিবর্তন করে।

  • auth_referrer_policy: কোন কোন URL-কে নির্দিষ্ট API Key ব্যবহার করার অনুমতি দেওয়া হবে তা সীমিত করতে, গ্রাহকরা Cloud Console-এ HTTP রেফারার সংক্রান্ত বিধিনিষেধ কনফিগার করতে পারবেন। ডিফল্ট হিসেবে, API কী ব্যবহার করার জন্য নির্দিষ্ট পাথকে অনুমতি দেওয়ার জন্য এইসব বিধিনিষেধ কনফিগার করা যেতে পারে। একই ডোমেন বা অরিজিনের কোনও URL API কী ব্যবহার করতে পারে, আপনি auth_referrer_policy=origin সেট করে Maps JavaScript API থেকে অনুরোধ অনুমোদন করার সময় পাঠানো ডেটার পরিমাণ সীমিত করতে পারেন। এটি ভার্সন 3.46 থেকে উপলভ্য। এই প্যারামিটার নির্দিষ্ট করা থাকলে এবং Cloud Console-এ HTTP রেফারার সংক্রান্ত বিধিনিষেধ চালু করা থাকলে, Maps JavaScript API শুধুমাত্র তখনই লোড করা যাবে যদি HTTP রেফারার সংক্রান্ত বিধিনিষেধ থাকে যা বর্তমান ওয়েবসাইটের ডোমেনের সাথে মেলে, কোনও পাথ নির্দিষ্ট করা থাকে না।

  • map_ids: কমা দিয়ে আলাদা করা ম্যাপ আইডির তালিকা। নির্দিষ্ট ম্যাপ আইডির জন্য কনফিগারেশন প্রিলোড করে। ম্যাপ আইডি ব্যবহার করার জন্য এখানে ম্যাপ আইডি উল্লেখ করার প্রয়োজন নেই, তবে যেসব ডেভেলপার নেটওয়ার্ক পারফর্ম্যান্স আরও উন্নত করতে চান, তাদের জন্য এটি উপলভ্য।

  • channel: প্রতি চ্যানেল পিছু ব্যবহার ট্র্যাক করা দেখুন।

NPM js-api-loader প্যাকেজ ব্যবহার করা

NPM প্যাকেজ ম্যানেজার ব্যবহার করে লোড করার জন্য @googlemaps/js-api-loader প্যাকেজ উপলভ্য। এই কমান্ড ব্যবহার করে এটি ইনস্টল করুন:

npm install @googlemaps/js-api-loader

এখানে যেভাবে দেখানো হয়েছে সেইভাবে প্যাকেজ ইমপোর্ট করুন:

TypeScript

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

জাভাস্ক্রিপ্ট

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

লোডার লাইব্রেরি উপলভ্য করতে প্রমিস ব্যবহার করে। importLibrary() পদ্ধতি ব্যবহার করে লাইব্রেরি লোড করুন। নিচের উদাহরণে, ম্যাপ লোড করার জন্য loader ব্যবহার করা দেখানো হয়েছে:

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();

জাভাস্ক্রিপ্ট

// 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();

সম্পূর্ণ উদাহরণ কোড দেখুন।

Dynamic Library Import API-তে মাইগ্রেট করা

এই বিভাগে, আপনার ইন্টিগ্রেশনকে ডায়নামিক লাইব্রেরি ইমপোর্ট 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() ব্যবহার করলে, সব লাইব্রেরি অনুরোধ একই সময়ে শুরু হয়, ফলে নেটওয়ার্ক লেটেন্সি কমে যায় এবং ইনিশিয়ালাইজেশন স্পিড উন্নত হয়।