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

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

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

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

इस क्विकस्टार्ट को Android Studio Hdgehog और Android Gradle प्लग इन के वर्शन 8.2 का इस्तेमाल करके डेवलप किया गया था.

ध्यान दें: अगर आपका डेवलपमेंट एनवायरमेंट, Android Studio या Gradle के किसी दूसरे वर्शन का इस्तेमाल करता है, तो हो सकता है कि आपको अपने एनवायरमेंट के हिसाब से चरणों में बदलाव करना पड़े. Android Studio और Gradle वर्शन के बारे में ज़्यादा जानकारी के लिए, Android Gradle प्लग इन और Android Studio के साथ काम करने की सुविधा देखें.

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

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

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

  

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

Android Studio में Google Maps प्रोजेक्ट बनाने की प्रोसेस फ़्लैमिंगो और Android Studio के बाद के रिलीज़ में बदल दी गई थी.

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

2. नया प्रोजेक्ट विंडो में, फ़ोन और टैबलेट कैटगरी में जाकर, कोई गतिविधि नहीं चुनें. इसके बाद, आगे बढ़ें पर क्लिक करें.

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

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

   • SDK टूल के कम से कम वर्शन को अपने टेस्ट डिवाइस के साथ काम करने वाले SDK टूल के वर्शन पर सेट करें. आपको Android एपीआई लेवल 21 ("Lollipop"; Android 5.0) या उसके बाद के वर्शन के लिए, Maps SDK टूल के लिए ज़रूरी वर्शन 19.0.x से बड़ा वर्शन चुनना होगा. SDK टूल के वर्शन की ज़रूरी शर्तों के बारे में नई जानकारी पाने के लिए, रिलीज़ नोट देखें.

     ध्यान दें: अगर आपको यह तय करने में मुश्किल हो रही है कि SDK टूल का कौनसा वर्शन चुनना है, तो मेरी मदद करें लिंक पर क्लिक करें. इससे आपको Android SDK के साथ काम करने वाले Android SDK के डिस्ट्रिब्यूशन की जानकारी दिखेगी. उदाहरण के लिए, Android API लेवल 21 ("Lollipop"; Android 5.0) चुनने पर, आपका ऐप्लिकेशन 99% से ज़्यादा Android डिवाइसों पर चलना चाहिए.

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

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

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

5. Google मैप दृश्य गतिविधि जोड़ें:

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

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

      

   3. नई Android गतिविधि डायलॉग बॉक्स में, लॉन्चर गतिविधि चेकबॉक्स चुनें.

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

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

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

   चेतावनी: AndroidManifest.xml फ़ाइल में Google Maps API पासकोड पाने और फिर उसे अपनी local.properties फ़ाइल में जोड़ने के निर्देश दिए गए हैं. local.properties फ़ाइल में अपनी एपीआई पासकोड न जोड़ें. ऐसा करने से आपकी एपीआई पासकोड कम सुरक्षित तरीके से सेव होती है. इसके बजाय, Cloud प्रोजेक्ट बनाने और एपीआई पासकोड कॉन्फ़िगर करने के लिए, अपना Google Cloud प्रोजेक्ट सेट अप करें में दिए गए निर्देशों का पालन करें.

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

नीचे दिए गए टैब पर क्लिक करके, Cloud Console को सेटअप करने के ज़रूरी चरण पूरे करें:

पहला चरण

कंसोल

1. Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, प्रोजेक्ट बनाएं पर क्लिक करके, नया Cloud प्रोजेक्ट बनाएं.

   प्रोजेक्ट सिलेक्टर पेज पर जाएं

2. पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग की सुविधा चालू हो. पुष्टि करें कि आपके प्रोजेक्ट के लिए बिलिंग की सुविधा चालू हो.

   Google Cloud, मुफ़्त में आज़माने की सुविधा देता है. मुफ़्त में आज़माने की अवधि 90 दिनों के खत्म होने पर या खाते पर 300 डॉलर के शुल्क जमा होने के बाद खत्म हो जाती है. इनमें से जो भी स्थिति पहले आती है उसके हिसाब से. सदस्यता को किसी भी समय रद्द किया जा सकता है. Google Maps Platform पर हर महीने 200 डॉलर का क्रेडिट दिया जाता है. ज़्यादा जानकारी के लिए, बिलिंग खाते के क्रेडिट और बिलिंग देखें.

Cloud SDK

gcloud projects create "PROJECT"

Google Cloud SDK , Cloud SDK इंस्टॉलेशन , और इन निर्देशों के बारे में ज़्यादा पढ़ें:

• gcloud projects create

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

दूसरा चरण

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

कंसोल

Android के लिए Maps SDK टूल चालू करना

Cloud SDK

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

Google Cloud SDK , Cloud SDK इंस्टॉलेशन , और इन निर्देशों के बारे में ज़्यादा पढ़ें:

• gcloud services enable
• gcloud services disable

तीसरा चरण

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

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

एपीआई पासकोड बनाने के लिए:

कंसोल

1. Google Maps Platform > क्रेडेंशियल पेज पर जाएं.

   क्रेडेंशियल पेज पर जाएं

2. क्रेडेंशियल पेज पर, क्रेडेंशियल बनाएं > एपीआई पासकोड पर क्लिक करें.
   एपीआई पासकोड बनाया गया डायलॉग, आपकी नई बनाई गई एपीआई पासकोड दिखाता है.
3. बंद करें पर क्लिक करें.
   नई एपीआई कुंजी, क्रेडेंशियल पेज पर एपीआई पासकोड में मौजूद होती है.
   (प्रोडक्शन में एपीआई कुंजी का इस्तेमाल करने से पहले, एपीआई कुंजी पर पाबंदी लगाना न भूलें.)

Cloud SDK

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Google Cloud SDK , Cloud SDK इंस्टॉलेशन , और इन निर्देशों के बारे में ज़्यादा पढ़ें:

• gcloud alpha services api-keys create

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

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

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

ध्यान दें: सिस्टम की नई ज़रूरी शर्तों और इंस्टॉल करने से जुड़े निर्देशों के लिए, GitHub पर Secrets Gradle प्लगिन का दस्तावेज़ देखें.

अपने Google Maps प्रोजेक्ट में Android के लिए Secrets Gradle प्लग इन इंस्टॉल करने के लिए:

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

   ग्रूवी

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }
   

2. अपनी मॉड्यूल-लेवल build.gradle फ़ाइल खोलें और नीचे दिए गए कोड को plugins एलिमेंट में जोड़ें.

   ग्रूवी

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

   Kotlin

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

3. अपनी मॉड्यूल-लेवल build.gradle फ़ाइल में, पक्का करें कि targetSdk और compileSdk 34 पर सेट हों.
4. फ़ाइल सेव करें और अपने प्रोजेक्ट को Gradle के साथ सिंक करें.
5. secrets.properties फ़ाइल को अपनी टॉप-लेवल की डायरेक्ट्री में खोलें और फिर नीचे दिया गया कोड जोड़ें. YOUR_API_KEY को अपनी एपीआई पासकोड से बदलें. अपनी कुंजी इस फ़ाइल में सेव करें, क्योंकि secrets.properties के लिए वर्शन कंट्रोल सिस्टम की जांच नहीं की जा रही है.
   ध्यान दें: अगर secrets.properties फ़ाइल मौजूद नहीं है, तो उसे उसी फ़ोल्डर में बनाएं जिसमें local.properties फ़ाइल है.

   MAPS_API_KEY=YOUR_API_KEY

6. फ़ाइल सेव करें.

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

   ध्यान दें: जैसा दिखाया गया है, उसके मुताबिक कोड डालें. DEFAULT_API_KEY को अपनी एपीआई पासकोड से न बदलें.

   MAPS_API_KEY=DEFAULT_API_KEY

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

8. फ़ाइल सेव करें.
9. अपनी AndroidManifest.xml फ़ाइल में, com.google.android.geo.API_KEY पर जाएं और android:value attribute को अपडेट करें. अगर <meta-data> टैग मौजूद नहीं है, तो उसे <application> टैग के चाइल्ड टैग के तौर पर बनाएं.

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

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

कोड देखें

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

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

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

मैप गतिविधि के मुख्य एलिमेंट:

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

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

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

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

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

मॉड्यूल build.gradle फ़ाइल में नीचे दी गई मैप डिपेंडेंसी शामिल है, जो Android के लिए Maps SDK टूल के लिए ज़रूरी है.

dependencies {

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

ध्यान दें: Android के लिए Maps SDK टूल के मौजूदा वर्शन के हिसाब से, सटीक वर्शन बदल सकता है.

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

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

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

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

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

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

अगले चरण

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

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

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