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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    2. नया > Google > Google मैप दृश्य गतिविधि चुनें.

      मैप पर की गई गतिविधि की जानकारी जोड़ें.

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

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

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

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

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

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

पहला चरण

कंसोल

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

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

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

दूसरा चरण

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

कंसोल

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 के लिए सीक्रेट ग्रेडल प्लगिन का इस्तेमाल करें.

अपने 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. फ़ाइल सेव करें और Gredle के साथ अपना प्रोजेक्ट सिंक करें.
  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}" />

    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 होता है या अगर आपने Kotlin को अपने ऐप्लिकेशन MapsActivity.kt की भाषा के तौर पर सेट किया है.

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

  • 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:18.2.0'
}

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

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

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

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

अगले चरण

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

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

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