Maps JavaScript API লোড করা

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

• ডায়নামিক লাইব্রেরি ইমপোর্ট ব্যবহার করা
• সরাসরি স্ক্রিপ্ট লোডিং ট্যাগ ব্যবহার করুন
• NPM js-api-loader package ব্যবহার করুন

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

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

প্রয়োজনীয় ক্লাসের জন্য ভেরিয়েবল ঘোষণা না করেই আপনার ফাংশন লাইব্রেরি লোড করতে পারে। gmp-map এলিমেন্ট ব্যবহার করে আপনি ম্যাপ যোগ করলে এটি বিশেষ কাজে লাগে। ভেরিয়েবল ছাড়া আপনাকে অবশ্যই কোয়ালিফায়েড পাথ ব্যবহার করতে হবে, যেমন google.maps.Map:

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

async function initMap() {
  await google.maps.importLibrary("maps");
  await 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-এর ভার্সন। আপনি কোনও চ্যানেল বা ভার্সন স্পষ্টভাবে উল্লেখ না করলে, আপনি ডিফল্ট হিসেবে সাপ্তাহিক চ্যানেল পাবেন। আপনি প্রিমিয়াম প্ল্যান থেকে মাইগ্রেট করে থাকলে এবং কোনও চ্যানেল বা ভার্সন স্পষ্টভাবে উল্লেখ না করে থাকলে, আপনি ডিফল্ট হিসেবে কোয়ার্টারলি চ্যানেল পাবেন। আপনি কোনও ভুল ভার্সন উল্লেখ করলে, আপনার ডিফল্ট চ্যানেলটি পাবেন। আরও জানুন।

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

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

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

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

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

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

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

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

মনে রাখবেন: ডাইরেক্ট স্ক্রিপ্ট লোডিং ট্যাগ লোড করা সম্পূর্ণ হয়ে গেলে আপনি importLibrary কল করতে পারবেন।

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

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>

প্রয়োজনীয় প্যারামিটার (ডাইরেক্ট) {:.hide-from-toc}

Maps JavaScript API লোড করার সময় নিম্নলিখিত প্যারামিটারগুলি প্রয়োজনীয়।

• key: আপনার API কী। বৈধ API key উল্লেখ না করা হলে, Maps JavaScript API লোড হবে না।

বিকল্প প্যারামিটার (সরাসরি) {:.hide-from-toc}

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 কী ব্যবহার করার অনুমতি দেওয়া হবে তা সীমিত করতে, গ্রাহকরা 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 প্যাকেজ ব্যবহার করা

পরামর্শ: v2.0.0 রিলিজ হল একটি বড় রিফ্যাক্টর যা পুরনো Loader ক্লাসকে দুটি ফাংশন, setOptions() এবং importLibrary() সহ একটি API দিয়ে প্রতিস্থাপন করে। এই শিফ্ট আপনাকে স্বতন্ত্র Maps API লাইব্রেরির অন-ডিমান্ড ডায়নামিক লোডিং প্রদান করে, প্রাথমিক পৃষ্ঠার পারফর্ম্যান্স উন্নত করতে ফিচার ডাউনলোড করার প্রসেস ডিফার করে।

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

npm install @googlemaps/js-api-loader

এখানে দেখানো পদ্ধতিতে প্যাকেজ ইমপোর্ট করুন:

TypeScript

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

মনে রাখবেন: TypeScript ও Google Maps ব্যবহার করা সংক্রান্ত নির্দেশিকা পড়ুন।

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

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

লাইব্রেরি উপলভ্য করতে লোডার Promises ব্যবহার করে। 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();
index.ts

মনে রাখবেন: TypeScript ও Google Maps ব্যবহার করা সংক্রান্ত নির্দেশিকা পড়ুন।

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

// 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-তে মাইগ্রেট করা

এই বিভাগে, আপনার ইন্টিগ্রেশনকে ডায়নামিক লাইব্রেরি ইমপোর্ট 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();