Google आपकी पसंदीदा भाषा में कॉन्टेंट का अनुवाद करने के लिए, एआई टेक्नोलॉजी का इस्तेमाल करता है. एआई से मिले अनुवादों में गलतियां हो सकती हैं.

अपने ऐप्लिकेशन में 3D मैप जोड़ना

यह प्रॉडक्ट या सुविधा, एक्सपेरिमेंट के तौर पर उपलब्ध है (pre-GA). हो सकता है कि Pre-GA के तहत आने वाले प्रॉडक्ट और सुविधाओं के लिए, आपको पूरी सहायता न मिले. साथ ही, ऐसा हो सकता है कि Pre-GA के तहत आने वाले प्रॉडक्ट और सुविधाओं में किए गए बदलाव, Pre-GA के अन्य वर्शन के साथ काम न करें. Pre-GA ऑफ़र पर, Google Maps Platform की सेवा से जुड़ी खास शर्तें लागू होती हैं. ज़्यादा जानकारी के लिए, लॉन्च के चरणों की जानकारी देखें.

प्लैटफ़ॉर्म चुनें: Android iOS JavaScript

न्यूयॉर्क शहर को दिखाने वाला 3D मैप

इस पेज पर, Android के लिए Maps 3D SDK का इस्तेमाल करके, किसी Android ऐप्लिकेशन में बुनियादी 3D मैप जोड़ने का तरीका बताया गया है. इस पेज पर दिए गए निर्देशों में यह माना गया है कि आपने सेटअप पेज पर दिए गए चरणों को पहले ही पूरा कर लिया है. साथ ही, आपके पास ये चीज़ें हैं:

Google Cloud प्रोजेक्ट में, Android के लिए Maps 3D SDK चालू होना चाहिए
Android के लिए Maps 3D SDK के साथ इस्तेमाल करने के लिए कॉन्फ़िगर किया गया एपीआई पासकोड
Android Studio प्रोजेक्ट, जिसे Android के लिए Maps 3D SDK के साथ इस्तेमाल करने के लिए सेट अप किया गया हो

इन ज़रूरी शर्तों के बारे में ज़्यादा जानने के लिए, सेटअप देखें.

पहला चरण: `Map3DView` कॉम्पोनेंट जोड़ने के लिए, लेआउट फ़ाइल (`activity_main.xml`) को अपडेट करना

Map3DView कॉम्पोनेंट, ऐप्लिकेशन में 3D मैप रेंडर करने वाला व्यू है. यहां दिए गए चरणों में, कॉम्पोनेंट को जोड़ा जाता है और मैप की शुरुआती स्थिति को कॉन्फ़िगर किया जाता है. इसमें कैमरे की पोज़िशन और उससे जुड़े एट्रिब्यूट शामिल हैं:

ध्यान दें: इस सेक्शन में दिए गए चरणों में यह माना गया है कि आपने सेटअप में बताई गई प्रोसेस का इस्तेमाल करके, अपना Android Studio प्रोजेक्ट बना लिया है और उसे कॉन्फ़िगर कर लिया है. इसके अलावा, यह भी माना गया है कि आपने किसी मौजूदा प्रोजेक्ट में नई व्यू ऐक्टिविटी जोड़ दी है. अगर आपने व्यू ऐक्टिविटी जोड़े बिना कोई नया Android Studio प्रोजेक्ट बनाया है, तो आपके प्रोजेक्ट में activity_main.xml फ़ाइल नहीं होगी.

अपनी मुख्य गतिविधि की लेआउट फ़ाइल खोलें. यह फ़ाइल आम तौर पर app/src/main/res/layout/activity_main.xml पर मौजूद होती है.
रूट ConstraintLayout (या रूट लेआउट एलिमेंट) में, map3d एक्सएमएल नेमस्पेस जोड़ें:
```
xmlns:map3d="http://schemas.android.com/apk/res-auto"
```
डिफ़ॉल्ट <TextView> को मिटा दें. यह "Hello World!" दिखाता है.

अपने लेआउट में Map3DView कॉम्पोनेंट जोड़ें. कैमरे की पोज़िशन और अन्य एट्रिब्यूट को पसंद के मुताबिक बनाया जा सकता है:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
  android:id="@+id/main"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  tools:context=".MainActivity">

  <com.google.android.gms.maps3d.Map3DView
    android:id="@+id/map3dView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    map3d:mode="hybrid"
    map3d:centerLat="38.544012"
    map3d:mode="hybrid"
    map3d:centerLng="-107.670428"
    map3d:centerAlt="2427.6"
    map3d:heading="310"
    map3d:tilt="63"
    map3d:range="8266"
    map3d:roll="0"
    map3d:minAltitude="0"
    map3d:maxAltitude="1000000"
    map3d:minHeading="0"
    map3d:maxHeading="360"
    map3d:minTilt="0"
    map3d:maxTilt="90"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

दूसरा हिस्सा: MainActivity.kt फ़ाइल अपडेट करना

यहां दिए गए तरीके से, पहले चरण में activity_main.xml फ़ाइल में जोड़े गए Map3DView कॉम्पोनेंट को शुरू किया जाता है. साथ ही, कॉम्पोनेंट के लाइफ़साइकल इवेंट मैनेज किए जाते हैं.

ध्यान दें कि Android के लिए Maps 3D SDK, एक समय पर सिर्फ़ एक Map3DView चालू इंस्टेंस के साथ काम करता है. एक साथ कई Map3DView इंस्टेंस दिखाना मुमकिन नहीं है. जैसे, एक ही लेआउट या अलग-अलग दिखने वाली ऐक्टिविटी या फ़्रैगमेंट में. ऐसा करने पर, रेंडरिंग से जुड़ी समस्याएं हो सकती हैं. जैसे, सेकंडरी व्यू पर काली स्क्रीन दिखना.

इसके अलावा, सभी Map3DView एक ही मैप स्टेट को शेयर करेंगे और दिखाएंगे.जैसे, कैमरे की पोज़िशन, जोड़े गए मार्कर, पॉलीगॉन वगैरह. यह तब भी बनी रहेगी, जब एक Map3DView को onDestroy का इस्तेमाल करके मिटा दिया जाता है और दूसरा बनाया जाता है. हालांकि, इसे मैन्युअल तरीके से मिटाया जा सकता है. उदाहरण के लिए, अगर आपने Map3DView1 में मार्कर जोड़े हैं, तो उन्हें मिटाकर Map3DView2 बनाने पर भी, वे मार्कर Map3DView2 में मौजूद रहेंगे.

डेवलपर की ज़िम्मेदारियां:

एक बार में एक व्यू: पक्का करें कि किसी भी समय, आपकी व्यू हैरारकी के ऐक्टिव हिस्से में सिर्फ़ एक Map3DView हो.
मैन्युअल तरीके से क्लीनअप करना: एक Map3DView (जैसे, Map3DView1) से दूसरे (जैसे, Map3DView2) पर स्विच करते समय, आपको पुराने इंस्टेंस (Map3DView1) पर onDestroy() को कॉल करना होगा. मैप की मौजूदा स्थिति शेयर की जाती है. इसलिए, यह पक्का करने के लिए कि Map3DView2 नई या खास स्थिति से शुरू हो, आपको Map3DView1 से सेट की गई किसी भी स्थिति को मैन्युअल तरीके से मिटाना होगा. इसमें मार्कर, ओवरले वगैरह हटाना शामिल है. साथ ही, OnMap3DViewReadyCallback में मिले GoogleMap3D ऑब्जेक्ट का इस्तेमाल करके, कैमरे की पोज़िशन को रीसेट करना भी शामिल है.

अपनी MainActivity.kt फ़ाइल खोलें. यह फ़ाइल आम तौर पर app/src/main/java/com/example/yourpackagename/MainActivity.kt पर मौजूद होती है.

Android के लिए Maps 3D SDK के लिए ज़रूरी इंपोर्ट जोड़ें:

import android.util.Log
import com.google.android.gms.maps3d.GoogleMap3D
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.OnMap3DViewReadyCallback

OnMap3DViewReadyCallback लागू करने के लिए, MainActivity क्लास में बदलाव करें:
```
class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
```

Map3DView और GoogleMap3D के लिए वैरिएबल तय करें:

private lateinit var map3DView: Map3DView
private var googleMap3D: GoogleMap3D? = null

onCreate तरीके में, setContentView(...) और ViewCompat.setOnApplyWindowInsetsListener ब्लॉक के बाद, map3DView को शुरू करें. इसके onCreate लाइफ़साइकल तरीके को कॉल करें और मैप के लिए एसिंक्रोनस तरीके से अनुरोध करें:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContentView(R.layout.activity_main)
    ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
        val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
        insets
    }

    map3DView = findViewById(R.id.map3dView)
    map3DView.onCreate(savedInstanceState)
    map3DView.getMap3DViewAsync(this)
}

onMap3DViewReady और onError तरीकों को ओवरराइड करें. इन कॉलबैक को तब ट्रिगर किया जाता है, जब मैप इस्तेमाल के लिए तैयार हो जाता है या जब शुरू करने के दौरान कोई गड़बड़ी होती है:

override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
    // Interact with the googleMap3D object here
    this.googleMap3D = googleMap3D
    // You can now make calls to the googleMap3D object, e.g.,
    // googleMap3D.cameraController.flyTo(camera { ... })
}

override fun onError(error: Exception) {
    // Handle the error gracefully here (for example, show an error dialog or log the error).
    Log.e("MainActivity", "Error loading 3D map", error)
}

अपनी गतिविधि से लाइफ़साइकल इवेंट को Map3DView पर फ़ॉरवर्ड करें. इसके लिए, MainActivity में ये ओवरराइड जोड़ें:

override fun onStart() {
    super.onStart()
    map3DView.onStart()
}

override fun onResume() {
    super.onResume()
    map3DView.onResume()
}

override fun onPause() {
    map3DView.onPause()
    super.onPause()
}

override fun onStop() {
    map3DView.onStop()
    super.onStop()
}

override fun onDestroy() {
    map3DView.onDestroy()
    super.onDestroy()
}

override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)
    map3DView.onSaveInstanceState(outState)
}

override fun onLowMemory() {
    super.onLowMemory()
    map3DView.onLowMemory()
}

तीसरा भाग: Gradle और Run को सिंक करना

ऐप्लिकेशन के लेआउट और गतिविधि को अपडेट करने के बाद, अब ऐप्लिकेशन को बनाया और चलाया जा सकता है. इससे 3D मैप व्यू देखा जा सकता है.

अपने प्रोजेक्ट को Gradle के साथ सिंक करने के लिए, फ़ाइल > Gradle फ़ाइलों के साथ प्रोजेक्ट सिंक करें को चुनें.
किसी एम्युलेटर या फ़िज़िकल डिवाइस पर अपना ऐप्लिकेशन बनाने और उसे चलाने के लिए, चलाएं > चलाएं को चुनें.

अगर सब कुछ सही तरीके से कॉन्फ़िगर किया गया है, तो आपको अपने ऐप्लिकेशन में 3D मैप दिखेगा. यह मैप, activity_main.xml में दिए गए निर्देशांकों के आस-पास दिखेगा.

मैप लोड होने और गड़बड़ी की स्थितियां

Android के लिए Maps 3D SDK, मैप की स्थिति को मैनेज करते समय, विज़ुअल फ़ीडबैक को अपने-आप दिखाता है:

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

OnMap3DViewReadyCallback को लागू करने के दौरान, onError(error: Exception) को बदलकर, प्रोग्राम के हिसाब से शुरू करने या लोड करने से जुड़ी इन गड़बड़ियों को कैप्चर किया जा सकता है.

मैप पर क्लिक करने से जुड़े इवेंट को मॉनिटर करने की अनुमति

मैप पर क्लिक इवेंट सुनने के लिए, GoogleMap3D.setMap3DClickListener का इस्तेमाल करें. यह लिसनर तब ट्रिगर होता है, जब कोई उपयोगकर्ता मैप पर क्लिक करता है. यह क्लिक किए गए पॉइंट की जगह और प्लेस आईडी की जानकारी देता है.

यहां दिए गए उदाहरण में, मैप क्लिक लिसनर सेट करने का तरीका बताया गया है:

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

ध्यान दें कि क्लिक हैंडलर, मुख्य (या यूज़र इंटरफ़ेस) थ्रेड पर नहीं चलता है. अगर आपको यूज़र इंटरफ़ेस (यूआई) में बदलाव करने हैं (जैसे, सूचना वाला मैसेज दिखाना), तो आपको मुख्य थ्रेड पर स्विच करना होगा. Kotlin के लिए, lifecycleScope.launch(Dispatchers.Main) का इस्तेमाल करके ऐसा किया जा सकता है.

अगले चरण

अब आपने अपने ऐप्लिकेशन में बुनियादी 3D मैप जोड़ लिया है. इसलिए, Android के लिए Maps 3D SDK टूल की ऐडवांस सुविधाओं के बारे में जानें. जैसे, कैमरे के पाथ के ऐनिमेशन, 3D मार्कर या पॉलीगॉन.

पहला चरण: Map3DView कॉम्पोनेंट जोड़ने के लिए, लेआउट फ़ाइल (activity_main.xml) को अपडेट करना