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

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

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

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

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

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

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

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

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

Android Studio में Google Maps प्रोजेक्ट बनाने का तरीका, Flamingo और उसके बाद के रिलीज़ में बदल गया है.

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

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

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

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

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

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

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

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

  5. Google Maps पर दिखने की गतिविधि जोड़ें:

    1. अपने प्रोजेक्ट में app फ़ोल्डर पर राइट क्लिक करें.
    2. नया > Google > Google Maps पर दिखने की गतिविधि चुनें.

      Maps पर की गई गतिविधि जोड़ें.

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

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

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

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

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

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

चरण 1

कंसोल

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

    प्रोजेक्ट चुनने वाले पेज पर जाएं

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

दूसरा चरण

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

कंसोल

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

Cloud SDK

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

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

तीसरा चरण

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

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

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

कंसोल

  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 टूल इंस्टॉल करने , और इन निर्देशों के बारे में ज़्यादा पढ़ें:

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

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

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

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

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

    Kotlin

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

    ग्रूवी

    buildscript {
        dependencies {
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
        }
    }
  2. मॉड्यूल-लेवल की build.gradle.kts या build.gradle फ़ाइल खोलें और plugins एलिमेंट में यह कोड जोड़ें.

    Kotlin

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

    ग्रूवी

    plugins {
        // ...
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    }
  3. मॉड्यूल-लेवल की build.gradle.kts या build.gradle फ़ाइल में, पक्का करें कि targetSdk और compileSdk को 34 पर सेट किया गया हो.
  4. फ़ाइल सेव करें और अपने प्रोजेक्ट को Gradle के साथ सिंक करें.
  5. अपनी टॉप-लेवल डायरेक्ट्री में secrets.properties फ़ाइल खोलें. इसके बाद, यहां दिया गया कोड जोड़ें. YOUR_API_KEY को अपनी एपीआई पासकोड से बदलें. अपनी कुंजी को इस फ़ाइल में सेव करें, क्योंकि secrets.properties को वर्शन कंट्रोल सिस्टम में शामिल नहीं किया जाता.
    MAPS_API_KEY=YOUR_API_KEY
  6. फ़ाइल सेव करें.
  7. अपनी टॉप-लेवल डायरेक्ट्री में local.defaults.properties फ़ाइल बनाएं. यह फ़ाइल, secrets.properties फ़ाइल वाले फ़ोल्डर में होनी चाहिए. इसके बाद, नीचे दिया गया कोड जोड़ें.

    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}" />

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

  10. 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 same folder as the 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"
    
        // 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.*"
    }
            

    ग्रूवी

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"
    
        // 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 पर की गई गतिविधि की फ़ाइल

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

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

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

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

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

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

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

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

dependencies {

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

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

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

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

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

अगले चरण

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

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

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