Android क्विकस्टार्ट के लिए Maps SDK टूल

Android Studio के लिए Google Maps व्यू टेंप्लेट का इस्तेमाल करके, मैप दिखाने वाला Android ऐप्लिकेशन बनाएं. अगर आपके पास पहले से कोई Android Studio प्रोजेक्ट है जिसे आपको सेट अप करना है, तो Android Studio प्रोजेक्ट सेट अप करना लेख पढ़ें.

यह क्विकस्टार्ट गाइड उन डेवलपर के लिए है जिन्हें Kotlin या Java के साथ Android डेवलपमेंट की बुनियादी जानकारी है.

डेवलपमेंट एनवायरमेंट के बारे में जानकारी

हमारा सुझाव है कि आप Android Studio और Android Gradle प्लग इन के सबसे नए स्टेबल वर्शन का इस्तेमाल करें.

Android डिवाइस सेट अप करना

Maps SDK for Android का इस्तेमाल करने वाले ऐप्लिकेशन को चलाने के लिए, आपको उसे किसी ऐसे Android डिवाइस या Android एम्युलेटर पर डिप्लॉय करना होगा जो Android 6.0 या इसके बाद के वर्शन पर आधारित हो और जिसमें Google API शामिल हों.

• Android डिवाइस का इस्तेमाल करने के लिए, हार्डवेयर डिवाइस पर ऐप्लिकेशन चलाएं में दिए गए निर्देशों का पालन करें.
• Android Emulator का इस्तेमाल करने के लिए, वर्चुअल डिवाइस बनाया जा सकता है. इसके बाद, Android Studio के साथ मिलने वाले डिवाइस मैनेजर का इस्तेमाल करके, एम्युलेटर को इंस्टॉल किया जा सकता है.

Android Studio में Google Maps प्रोजेक्ट बनाना

1. Android Studio खोलें और Android Studio में आपका स्वागत है विंडो में, नया प्रोजेक्ट पर क्लिक करें.

2. New Project विंडो में, Phone and Tablet कैटगरी में जाकर, No Activity चुनें. इसके बाद, Next पर क्लिक करें.

3. नया प्रोजेक्ट फ़ॉर्म भरें:

   • भाषा को Java या Kotlin पर सेट करें. Android के लिए Maps SDK टूल, दोनों भाषाओं के साथ काम करता है. Kotlin के बारे में ज़्यादा जानने के लिए, Kotlin की मदद से Android ऐप्लिकेशन डेवलप करना लेख पढ़ें.

   • कम से कम एसडीके को एसडीके के ऐसे वर्शन पर सेट करें जो आपके टेस्ट डिवाइस के साथ काम करता हो. आपको Android के लिए Maps SDK के 20.0.x वर्शन के लिए ज़रूरी कम से कम वर्शन से ज़्यादा का वर्शन चुनना होगा. यह वर्शन, Android एपीआई लेवल 23 ("Marshmallow"; Android 6.0) या इसके बाद का वर्शन है. SDK टूल के वर्शन की ज़रूरी शर्तों के बारे में नई जानकारी पाने के लिए, रिलीज़ नोट देखें.

   • बिल्ड कॉन्फ़िगरेशन की भाषा को Kotlin DSL या Groovy DSL पर सेट करें. यहां दी गई प्रोसेस में, बिल्ड कॉन्फ़िगरेशन की दोनों भाषाओं के स्निपेट दिखाए गए हैं.

4. पूरा करें पर क्लिक करें.

   Android Studio, Gradle को शुरू करता है और प्रोजेक्ट को बिल्ड करता है. इसमें थोड़ा समय लग सकता है.

5. Google Maps पर व्यू की गतिविधि जोड़ें:

   1. अपने प्रोजेक्ट में मौजूद app फ़ोल्डर पर राइट क्लिक करें.

   2. नया > Google > Google Maps पर व्यू की गतिविधि को चुनें:

      

   3. New Android Activity डायलॉग बॉक्स में, Launcher Activity चेकबॉक्स को चुनें.

   4. पूरा करें चुनें.

      ज़्यादा जानकारी के लिए, टेंप्लेट से कोड जोड़ना लेख पढ़ें.

6. बिल्ड पूरा होने पर, Android Studio AndroidManifest.xml और MapsActivity फ़ाइलें खोलता है. आपकी गतिविधि का नाम अलग हो सकता है. यह इस बात पर निर्भर करता है कि आपने सेटअप के दौरान क्या कॉन्फ़िगर किया था.

अपना Google Cloud प्रोजेक्ट सेट अप करना

Cloud Console को सेटअप करने के लिए, यहां दिया गया तरीका अपनाएं:

पहला चरण: अपना प्रोजेक्ट सेट अप करना

gcloud projects create "PROJECT"

दूसरा चरण: एपीआई या एसडीके चालू करना

Google Maps Platform का इस्तेमाल करने के लिए, आपको वे एपीआई या एसडीके चालू करने होंगे जिनका इस्तेमाल आपको अपने प्रोजेक्ट के साथ करना है.

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

तीसरा चरण: एपीआई पासकोड पाना

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

एपीआई पासकोड एक यूनीक आइडेंटिफ़ायर होता है. यह इस्तेमाल और बिलिंग के मकसद से, आपके प्रोजेक्ट से जुड़े अनुरोधों की पुष्टि करता है. आपके प्रोजेक्ट से कम से कम एक एपीआई पासकोड जुड़ा होना चाहिए. नई कुंजी बनाने या किसी मौजूदा कुंजी में एपीआई या SDK टूल जोड़ने के लिए, यह तरीका अपनाएं.

अपने ऐप्लिकेशन में एपीआई पासकोड जोड़ना

इस सेक्शन में, एपीआई पासकोड को सेव करने का तरीका बताया गया है, ताकि आपका ऐप्लिकेशन उसे सुरक्षित तरीके से रेफ़र कर सके. आपको अपने वर्शन कंट्रोल सिस्टम में एपीआई पासकोड की जांच नहीं करनी चाहिए. इसलिए, हमारा सुझाव है कि आप इसे अपने प्रोजेक्ट की रूट डायरेक्ट्री में मौजूद secrets.properties फ़ाइल में सेव करें और उस फ़ाइल को वर्शन कंट्रोल से बाहर रखें. Gradle प्रॉपर्टी फ़ाइलों के बारे में ज़्यादा जानने के लिए, Gradle प्रॉपर्टी फ़ाइलें देखें.

इस टास्क को आसान बनाने के लिए, हमारा सुझाव है कि आप Android के लिए सीक्रेट ग्रेडल प्लग इन का इस्तेमाल करें.

Android के लिए Secrets Gradle Plugin इंस्टॉल करने और अपना एपीआई पासकोड सेव करने के लिए:

1. Android Studio में, अपनी टॉप-लेवल build.gradle.kts या build.gradle फ़ाइल खोलें और plugins ब्लॉक में यह कोड जोड़ें.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   ग्रूवी

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. मॉड्यूल-लेवल की build.gradle.kts या build.gradle फ़ाइल खोलें. इसके बाद, plugins एलिमेंट में यह कोड जोड़ें.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   ग्रूवी

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. अगर Android Studio का इस्तेमाल किया जा रहा है, तो अपने प्रोजेक्ट को Gradle के साथ सिंक करें.
4. अपनी टॉप-लेवल डायरेक्ट्री में secrets.properties फ़ाइल खोलें. इसके बाद, यह कोड जोड़ें. YOUR_API_KEY को अपने एपीआई पासकोड से बदलें. secrets.properties को अपनी .gitignore फ़ाइल में जोड़ना न भूलें. इसके अलावा, इसे अपने वर्शन कंट्रोल सिस्टम से बाहर रखें, ताकि आप वर्शन कंट्रोल में अपने एपीआई पासकोड की जांच न करें.

   MAPS_API_KEY=YOUR_API_KEY

5. अपनी टॉप-लेवल डायरेक्ट्री में local.defaults.properties फ़ाइल बनाएं. यह वही फ़ोल्डर होना चाहिए जिसमें secrets.properties फ़ाइल है. इसके बाद, यह कोड जोड़ें.

   MAPS_API_KEY=DEFAULT_API_KEY

   इस फ़ाइल का मकसद, एपीआई पासकोड के लिए बैकअप लोकेशन उपलब्ध कराना है. ऐसा तब किया जाता है, जब secrets.properties फ़ाइल न मिले, ताकि बिल्ड फ़ेल न हों. ऐसा तब हो सकता है, जब आपने ऐप्लिकेशन को किसी ऐसे वर्शन कंट्रोल सिस्टम से क्लोन किया हो जिसमें secrets.properties शामिल न हो. साथ ही, आपने एपीआई पासकोड देने के लिए, अब तक लोकल स्टोरेज में secrets.properties फ़ाइल न बनाई हो.

6. अपनी AndroidManifest.xml फ़ाइल में, com.google.android.geo.API_KEY पर जाएं और android:value एट्रिब्यूट को इस तरह अपडेट करें:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   ध्यान दें: एपीआई पासकोड के लिए, मेटाडेटा के नाम के तौर पर com.google.android.geo.API_KEY का सुझाव दिया जाता है. इस नाम वाली कुंजी का इस्तेमाल, Android प्लैटफ़ॉर्म पर Google Maps पर आधारित कई एपीआई की पुष्टि करने के लिए किया जा सकता है. इनमें Android के लिए Maps SDK भी शामिल है. पुराने सिस्टम के साथ काम करने की सुविधा के लिए, एपीआई में com.google.android.maps.v2.API_KEY नाम का भी इस्तेमाल किया जा सकता है. इस लेगसी नाम से, सिर्फ़ Android Maps API v2 की पुष्टि की जा सकती है. कोई ऐप्लिकेशन, एपीआई पासकोड के मेटाडेटा के नामों में से सिर्फ़ एक नाम तय कर सकता है. अगर दोनों एट्रिब्यूट की वैल्यू दी जाती हैं, तो एपीआई एक गड़बड़ी दिखाता है.

7. Android Studio में, मॉड्यूल-लेवल की build.gradle.kts या build.gradle फ़ाइल खोलें और secrets प्रॉपर्टी में बदलाव करें. अगर secrets प्रॉपर्टी मौजूद नहीं है, तो उसे जोड़ें.

   प्लग इन की प्रॉपर्टी में बदलाव करके, propertiesFileName को "secrets.properties" पर सेट करें. साथ ही, defaultPropertiesFileName को "local.defaults.properties" पर सेट करें और अन्य प्रॉपर्टी सेट करें.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

   ग्रूवी

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

कोड देखें

टेंप्लेट में दिए गए कोड की जांच करें. खास तौर पर, अपने Android Studio प्रोजेक्ट में ये फ़ाइलें देखें.

Maps पर की गई गतिविधि की फ़ाइल

Maps पर की गई गतिविधि की फ़ाइल, ऐप्लिकेशन की मुख्य गतिविधि होती है. इसमें मैप को मैनेज करने और दिखाने के लिए कोड होता है. डिफ़ॉल्ट रूप से, गतिविधि तय करने वाली फ़ाइल का नाम MapsActivity.java होता है. अगर आपने अपने ऐप्लिकेशन के लिए Kotlin को भाषा के तौर पर सेट किया है, तो फ़ाइल का नाम MapsActivity.kt होता है.

Maps पर की गई गतिविधि के मुख्य एलिमेंट:

• SupportMapFragment ऑब्जेक्ट, मैप की लाइफ़साइकल को मैनेज करता है. साथ ही, यह ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) का पैरंट एलिमेंट होता है.

• GoogleMap ऑब्जेक्ट, मैप के डेटा और व्यू का ऐक्सेस देता है. यह Android के लिए Maps SDK टूल की मुख्य क्लास है. मैप ऑब्जेक्ट गाइड में, SupportMapFragment और GoogleMap ऑब्जेक्ट के बारे में ज़्यादा जानकारी दी गई है.

• moveCamera फ़ंक्शन, मैप को सिडनी, ऑस्ट्रेलिया के LatLng निर्देशांकों पर सेट करता है. मैप जोड़ते समय, सबसे पहले मैप की जगह और कैमरे की सेटिंग कॉन्फ़िगर की जाती हैं. जैसे, व्यूइंग ऐंगल, मैप का ओरिएंटेशन, और ज़ूम करने का लेवल. ज़्यादा जानकारी के लिए, कैमरा और व्यू गाइड देखें.

• addMarker फ़ंक्शन, सिडनी के निर्देशांकों में एक मार्कर जोड़ता है. ज़्यादा जानकारी के लिए, मार्कर गाइड देखें.

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

मॉड्यूल Gradle फ़ाइल

मॉड्यूल-लेवल की build.gradle.kts या build.gradle फ़ाइल में, Maps की यह डिपेंडेंसी शामिल होती है. Android के लिए Maps SDK टूल को इसकी ज़रूरत होती है.

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.0.0"
}

अगर आपका प्रोजेक्ट Gradle वर्शन कैटलॉग (gradle/libs.versions.toml) का इस्तेमाल करता है, तो libs.versions.toml में play-services-maps डिपेंडेंसी तय करें:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

Maps की डिपेंडेंसी को मैनेज करने के बारे में ज़्यादा जानने के लिए, वर्शनिंग देखें.

एक्सएमएल लेआउट फ़ाइल

activity_maps.xml फ़ाइल, एक्सएमएल लेआउट फ़ाइल होती है. इससे ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) के स्ट्रक्चर के बारे में पता चलता है. यह फ़ाइल res/layout डायरेक्ट्री में मौजूद है. activity_maps.xml फ़ाइल में एक फ़्रैगमेंट का एलान किया गया है, जिसमें ये एलिमेंट शामिल हैं:

• tools:context, फ़्रैगमेंट की डिफ़ॉल्ट गतिविधि को MapsActivity पर सेट करता है. इसे Maps पर की गई गतिविधि की फ़ाइल में तय किया जाता है.
• android:name, फ़्रैगमेंट की क्लास का नाम SupportMapFragment पर सेट करता है. यह फ़्रैगमेंट का वह टाइप है जिसका इस्तेमाल, Maps की गतिविधि वाली फ़ाइल में किया जाता है.

एक्सएमएल लेआउट फ़ाइल में यह कोड शामिल होता है:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

ऐप्लिकेशन को डिप्लॉय करना और चलाना

ऐप्लिकेशन को सही तरीके से चलाने पर, यह सिडनी, ऑस्ट्रेलिया को केंद्र में रखकर मैप दिखाता है. साथ ही, शहर पर एक मार्कर दिखाता है, जैसा कि स्क्रीनशॉट में दिखाया गया है.

ऐप्लिकेशन को डिप्लॉय और रन करने के लिए:

1. Android Studio में, अपना ऐप्लिकेशन चलाने के लिए, Run मेन्यू विकल्प (या प्ले बटन आइकॉन) पर क्लिक करें.
2. डिवाइस चुनने के लिए कहा जाने पर, इनमें से कोई एक विकल्प चुनें:
   • अपने कंप्यूटर से कनेक्ट किया गया Android डिवाइस चुनें.
   • इसके अलावा, एम्युलेटर लॉन्च करें रेडियो बटन को चुनें. इसके बाद, सेट अप किया गया वर्चुअल डिवाइस चुनें.
3. ठीक है पर क्लिक करें. Android Studio, आपके ऐप्लिकेशन को बनाने के लिए Gradle को शुरू करेगा. इसके बाद, आपके डिवाइस या एम्युलेटर पर नतीजे दिखाएगा. ऐप्लिकेशन को लॉन्च होने में कुछ मिनट लग सकते हैं.

अगले चरण

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

• अपने Android ऐप्लिकेशन (Kotlin) में मैप जोड़ना: इस कोडलैब में, आपको एक ऐसे ऐप्लिकेशन के बारे में बताया गया है जो Android के लिए Maps SDK की कुछ अतिरिक्त सुविधाएं दिखाता है.

• Maps Android KTX लाइब्रेरी का इस्तेमाल करना: Kotlin एक्सटेंशन (KTX) लाइब्रेरी की मदद से, Android के लिए Maps SDK का इस्तेमाल करते समय, Kotlin भाषा की कई सुविधाओं का फ़ायदा लिया जा सकता है.