Ajouter une carte 3D à votre application

Sélectionnez une plate-forme : Android iOS JavaScript

Carte 3D montrant New York

Cette page présente un exemple d'ajout d'une carte 3D de base à une application Android à l'aide du SDK Maps 3D pour Android. Les instructions de cette page supposent que vous avez déjà suivi les étapes de la page Configuration et que vous disposez des éléments suivants :

  • Un projet Google Cloud avec le SDK Maps 3D pour Android activé
  • Une clé API configurée pour être utilisée avec le SDK Maps 3D pour Android
  • Un projet Android Studio configuré pour être utilisé avec le SDK Maps 3D pour Android

Pour en savoir plus sur ces conditions préalables, consultez Configuration.

Partie 1 : Mettre à jour le fichier de mise en page (activity_main.xml) pour ajouter le composant Map3DView

Le composant Map3DView est la vue qui affiche la carte 3D dans l'application. Les étapes suivantes permettent d'ajouter le composant et de configurer l'état initial de la carte, y compris la position de la caméra et les attributs associés :

  1. Ouvrez le fichier de mise en page de votre activité principale, qui se trouve généralement à l'emplacement app/src/main/res/layout/activity_main.xml.

  2. Dans l'élément racine ConstraintLayout (ou l'élément de mise en page racine), ajoutez l'espace de noms XML map3d :

    xmlns:map3d="http://schemas.android.com/apk/res-auto"

  3. Supprimez l'élément <TextView> par défaut qui affiche "Hello World!".

  4. Ajoutez le composant Map3DView à votre mise en page. Vous pouvez personnaliser la position de la caméra et d'autres attributs :

    <?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:mapMode="hybrid"
    map3d:centerLat="38.544012"
    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>

Partie 2 : Mettre à jour MainActivity.kt

Les étapes suivantes initialisent le composant Map3DView ajouté au fichier activity_main.xml dans la partie 1 et gèrent les événements de cycle de vie du composant.

Notez que le SDK Maps 3D pour Android n'accepte qu'une seule instance Map3DView active à la fois. L'affichage simultané de plusieurs instances Map3DView (par exemple, dans la même mise en page ou dans des activités ou fragments visibles différents) n'est pas pris en charge et peut entraîner des problèmes d'affichage, tels que des écrans noirs sur les vues secondaires.

De plus, tous les Map3DView partageront et refléteront le même état de la carte (par exemple, la position de la caméra, les repères ajoutés, les polygones, etc.), qui persistera même si un Map3DView est détruit (à l'aide de onDestroy) et qu'un autre est créé, sauf s'il est effacé manuellement. Par exemple, si vous ajoutez des repères à Map3DView1, puis que vous le détruisez et créez Map3DView2, ces mêmes repères seront toujours présents sur Map3DView2.

Responsabilités du développeur :

  • Une vue à la fois : assurez-vous qu'un seul Map3DView se trouve dans une partie active de la hiérarchie des vues à tout moment.
  • Nettoyage manuel : lorsque vous passez d'un Map3DView (par exemple, Map3DView1) à un autre (par exemple, Map3DView2), vous devez appeler onDestroy() sur l'ancienne instance (Map3DView1). Étant donné que l'état de la carte sous-jacente est partagé, pour vous assurer que Map3DView2 démarre avec un état nouveau ou spécifique, vous devez effacer manuellement tout état défini par Map3DView1. Cela inclut la suppression des repères, des superpositions, etc., et la réinitialisation de la position de la caméra à l'aide de l'objet GoogleMap3D obtenu dans OnMap3DViewReadyCallback.

  1. Ouvrez votre fichier MainActivity.kt, qui se trouve généralement à l'emplacement app/src/main/java/com/example/yourpackagename/MainActivity.kt.

  2. Ajoutez les importations nécessaires pour le SDK Maps 3D pour Android :

    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

  3. Modifiez la classe MainActivity pour implémenter OnMap3DViewReadyCallback :

    class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {

  4. Déclarez des variables pour Map3DView et GoogleMap3D :

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

  5. Dans la méthode onCreate, après setContentView(...) et le bloc ViewCompat.setOnApplyWindowInsetsListener, initialisez map3DView, appelez sa méthode de cycle de vie onCreate et demandez la carte de manière asynchrone :

    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)
}

  6. Remplacez les méthodes onMap3DViewReady et onError. Ces rappels sont déclenchés lorsque la carte est prête à être utilisée ou lorsqu'une erreur se produit lors de l'initialisation :

    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.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)
}

  7. Transférez les événements de cycle de vie de votre activité vers Map3DView en ajoutant les remplacements suivants à 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()
}

Partie 3 : Synchroniser Gradle et exécuter l'application

Maintenant que vous avez mis à jour la mise en page et l'activité de votre application, vous pouvez la compiler et l'exécuter pour afficher la vue de la carte en 3D.

  1. Pour synchroniser votre projet avec Gradle, sélectionnez File > Sync Project with Gradle Files (Fichier > Synchroniser le projet avec les fichiers Gradle).

  2. Pour créer et exécuter votre application sur un émulateur ou un appareil physique, sélectionnez Run > Run (Exécuter > Exécuter).

Si tout est configuré correctement, une carte 3D s'affiche dans votre application, centrée près des coordonnées spécifiées dans votre activity_main.xml.

États de chargement et d'erreur de la carte

Le SDK Maps 3D pour Android affiche automatiquement un retour visuel intégré tout en gérant l'état de la carte :

  • Superposition de chargement : un indicateur de progression centré s'affiche lors de l'initialisation de la vue de la carte ou du chargement de sa fenêtre d'affichage initiale.
  • Superposition d'erreur : une fiche d'erreur stylisée s'affiche en cas d'échec critique, par exemple si la clé API n'est pas valide, en cas d'erreur réseau ou si l'application est exécutée sur un appareil non compatible.

Vous pouvez capturer ces erreurs d'initialisation ou de chargement de manière programmatique en remplaçant onError(error: Exception) dans votre implémentation OnMap3DViewReadyCallback.

Écouter les événements de clic sur la carte

Pour écouter les événements de clic sur la carte, appelez setMap3DClickListener sur GoogleMap3D. Lorsqu'un utilisateur clique sur la carte, le rappel onMap3DClick reçoit un objet Map3DClickEvent qui fournit les valeurs location et placeId du point cliqué, et renvoie un Boolean (true pour supprimer le widget d'UI Places par défaut ou false pour l'afficher). Pour en savoir plus, consultez Interagir avec les points d'intérêt.

L'exemple suivant montre comment définir un écouteur de clic sur la carte :

googleMap3D.setMap3DClickListener { event: Map3DClickEvent ->
    Log.d(
        "MainActivity",
        "Clicked at ${event.location}, placeId: ${event.placeId}"
    )
    false
}

Étapes suivantes

Maintenant que vous avez ajouté une carte 3D de base à votre application, vous pouvez explorer des fonctionnalités plus avancées du SDK Maps 3D pour Android, comme les animations de trajectoire de la caméra, les repères 3D ou les polygones.