API Google Maps sur Wear OS

Carte sur un objet connecté

Le SDK Maps pour Android vous permet de créer une appli connectée basée sur une carte, qui s'exécute directement sur les appareils Wear OS by Google. Les utilisateurs de votre application peuvent voir leur position sur la carte d'un simple coup d'œil à leur poignet. Ils peuvent déterminer leur position sur un itinéraire, par exemple, puis effectuer un zoom avant pour afficher plus de détails, ou appuyer sur un repère pour afficher une fenêtre d'informations fournie par votre application.

Cette page décrit les fonctionnalités d'API disponibles sur un appareil Wear et vous aide à créer votre application.

Premiers pas avec Wear OS

Créer une appli connectée avec le SDK Maps pour Android revient pratiquement au même que créer une appli Google Maps pour un autre appareil Android. La seule différence réside dans la conception, qui doit tenir compte du format réduit de l'objet connecté. Cela permet d'optimiser les performances et la facilité d'utilisation de l'application.

Android Studio est l'outil recommandé pour le développement sur Wear OS, car il propose des méthodes de paramétrage de projet, d'intégration de bibliothèques et de packaging.

Pour des conseils d'ordre général sur la conception d'une appli connectée, consultez les consignes de conception pour Wear OS. Pour des conseils sur la création de votre première appli connectée, consultez le guide sur la création d'appli connectées.

Créer votre première application de cartographie sur Wear OS

Ce guide rapide part du principe que vous connaissez le SDK Maps pour Android, que vous avez suivi les guides Wear OS pour créer un module connecté dans votre application, et que vous souhaitez à présent ajouter une carte à ce module.

Ajouter des dépendances à votre module Wear OS

Assurez-vous que les dépendances suivantes sont incluses dans le fichier build.gradle du module Wear OS de votre application :

dependencies {
    // ...
    compileOnly 'com.google.android.wearable:wearable:2.8.1'
    implementation 'com.google.android.support:wearable:2.8.1'
    implementation 'com.google.android.gms:play-services-maps:18.0.1'

    // This dependency is necessary for ambient mode
    implementation 'androidx.wear:wear:1.2.0'
}

Pour en savoir plus sur les dépendances, consultez le guide Ajouter un module Wear OS à votre projet existant.

Mettre en œuvre un geste de balayage pour fermer l'application et définir la couleur d'arrière-plan initiale

Nous vous recommandons d'utiliser un SwipeDismissFrameLayout pour afficher la carte sur l'objet connecté. Avec la classe SwipeDismissFrameLayout, vous pouvez implémenter le geste balayer pour fermer afin de permettre aux utilisateurs de quitter l'application en balayant l'écran depuis le bord le plus à gauche.

Pour définir une couleur d'arrière-plan personnalisée initiale, utilisez l'attribut XML map:backgroundColor afin de spécifier la couleur à afficher jusqu'au chargement réel des tuiles.

Ajoutez les éléments SwipeDismissFrameLayout et backgroundColor à votre définition de mise en page en tant que conteneurs pour SupportMapFragment :

  <androidx.wear.widget.SwipeDismissFrameLayout
      android:id="@+id/map_container"
      android:layout_width="match_parent"
      android:layout_height="match_parent">
    <fragment
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        map:backgroundColor="#fff0b2dd" />
  </androidx.wear.widget.SwipeDismissFrameLayout>

Lorsque vous obtenez l'objet SwipeDismissFrameLayout dans votre activité, ajoutez un rappel et définissez son comportement pour effectuer l'action de fermeture nécessaire comme indiqué ci-dessous :

Java


public class MainActivity extends AppCompatActivity implements OnMapReadyCallback,
    AmbientModeSupport.AmbientCallbackProvider {

    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(MainActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        final SwipeDismissFrameLayout mapFrameLayout = (SwipeDismissFrameLayout) findViewById(
            R.id.map_container);
        mapFrameLayout.addCallback(new SwipeDismissFrameLayout.Callback() {
            @Override
            public void onDismissed(SwipeDismissFrameLayout layout) {
                onBackPressed();
            }
        });

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    // ...
}

      

Kotlin


class MainActivity : AppCompatActivity(), OnMapReadyCallback,
                     AmbientModeSupport.AmbientCallbackProvider {

    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(MainActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        val mapFrameLayout = findViewById<SwipeDismissFrameLayout>(R.id.map_container)
        mapFrameLayout.addCallback(object : SwipeDismissFrameLayout.Callback() {
            override fun onDismissed(layout: SwipeDismissFrameLayout) {
                onBackPressed()
            }
        })

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    // ...
}

      

Ajouter une carte

Utilisez la méthode de rappel onMapReady(GoogleMap) comme d'habitude pour obtenir un handle vers l'objet GoogleMap. Le rappel est déclenché dès que la carte est prête à être utilisée. Dans la méthode de rappel, vous pouvez ajouter des repères ou des polylignes à la carte, ajouter des écouteurs ou déplacer la caméra. L'exemple ci-dessous ajoute un repère près de l'opéra de Sydney :

Java


private static final LatLng SYDNEY = new LatLng(-33.85704, 151.21522);

@Override
public void onMapReady(@NonNull GoogleMap googleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(new MarkerOptions().position(SYDNEY)
        .title("Sydney Opera House"));

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 10));
}

      

Kotlin


private val sydney = LatLng(-33.85704, 151.21522)

override fun onMapReady(googleMap: GoogleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(
        MarkerOptions().position(sydney)
            .title("Sydney Opera House")
    )

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 10f))
}

      

Activer le mode Veille

Le SDK Maps pour Android est compatible avec le mode Veille pour les applis connectées. Les applications qui prennent en charge le mode Veille sont parfois appelées applications toujours activées. Le mode Veille est activé dès que l'utilisateur n'utilise plus activement l'application et permet à l'application de rester visible sur l'objet connecté.

Le SDK Maps pour Android offre un rendu simplifié avec des couleurs atténuées de la carte pour une utilisation en mode Veille, et le style de la carte s'ajuste automatiquement dès que l'appareil passe du mode interactif au mode Veille. Tous les repères, les objets et les commandes de l'interface utilisateur disparaissent du mode Veille. Cela permet de réduire la consommation d'énergie de votre application et garantit une apparence et une utilisation cohérentes avec les autres applications utilisant ce mode, comme les cadrans de montre.

Pour que votre application utilise le mode Veille de la carte, procédez comme suit :

  1. Mettez à jour le SDK Android pour inclure la plate-forme Android 6.0 (API 23) ou une version ultérieure, qui fournit les API permettant aux activités de passer en mode Veille. Pour en savoir plus sur la mise à jour de votre SDK, consultez la documentation Android sur l'ajout de packages SDK.
  2. Assurez-vous que votre projet cible Android 6.0 ou une version ultérieure, en définissant targetSdkVersion sur 23 ou plus dans le fichier manifeste d'application.
  3. Ajoutez les dépendances connectées au fichier build.gradle de votre application. Consultez l'exemple sur cette page.
  4. Ajoutez l'entrée de bibliothèque partagée connectée au fichier manifeste d'appli connectée, comme décrit dans la formation Android sur la façon de garder votre application visible.
  5. Ajoutez l'autorisation WAKE_LOCK aux fichiers manifestes des applications mobiles et connectées, comme indiqué dans la formation Android sur la façon de garder votre application visible.
  6. Dans la méthode onCreate() de votre activité, appelez la méthode AmbientModeSupport.attach(). Vous indiquez ainsi au système d'exploitation que l'application est toujours activée, de sorte que lorsque l'appareil passe en veille, il doit passer en mode Veille au lieu d'afficher le cadran.
  7. Implémentez l'interface AmbientModeSupport.AmbientCallbackProvider dans votre activité pour qu'elle puisse recevoir les changements de l'état du mode Veille.
  8. Configurez votre carte pour qu'elle prenne en charge le mode Veille. Pour cela, vous pouvez définir l'attribut map:ambientEnabled="true" dans le fichier de mise en page XML de l'activité ou le faire par programmation en définissant GoogleMapOptions.ambientEnabled(true). Ce paramètre informe l'API qu'elle doit précharger les tuiles de carte nécessaires pour l'utilisation en mode Veille.
  9. Lorsque l'activité passe en mode Veille, le système appelle la méthode onEnterAmbient() dans le AmbientCallback que vous fournissez. Ignorez onEnterAmbient() et appelez SupportMapFragment.onEnterAmbient(ambientDetails) ou MapView.onEnterAmbient(ambientDetails). L'API passe à un rendu non interactif et peu coloré de la carte.
  10. De même, dans onExitAmbient(), appelez SupportMapFragment.onExitAmbient() ou MapView.onExitAmbient(). L'API passe au rendu normal de la carte.

L'exemple de code suivant active le mode Veille dans l'activité :

Java


public class AmbientActivity extends AppCompatActivity implements
    AmbientModeSupport.AmbientCallbackProvider {

    private SupportMapFragment mapFragment;

    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(AmbientActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
    }

    @Override
    public AmbientCallback getAmbientCallback() {
        return new AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            @Override
            public void onEnterAmbient(Bundle ambientDetails) {
                super.onEnterAmbient(ambientDetails);
                mapFragment.onEnterAmbient(ambientDetails);
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            @Override
            public void onExitAmbient() {
                super.onExitAmbient();
                mapFragment.onExitAmbient();
            }
        };
    }
}

      

Kotlin


class AmbientActivity : AppCompatActivity(), AmbientModeSupport.AmbientCallbackProvider {

    private lateinit var mapFragment: SupportMapFragment

    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(AmbientActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
    }

    override fun getAmbientCallback(): AmbientModeSupport.AmbientCallback {
        return object : AmbientModeSupport.AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            override fun onEnterAmbient(ambientDetails: Bundle) {
                super.onEnterAmbient(ambientDetails)
                mapFragment.onEnterAmbient(ambientDetails)
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            override fun onExitAmbient() {
                super.onExitAmbient()
                mapFragment.onExitAmbient()
            }
        }
    }
}

      

Vous pouvez actualiser l'écran alors que l'application est en mode Veille. Pour plus de détails sur l'actualisation du contenu et sur le mode Veille en général, consultez la formation Android sur la façon de garder votre application visible.

Utiliser Street View sur Wear OS

Street View est entièrement compatible avec les accessoires connectés.

Pour permettre aux utilisateurs de quitter l'application lorsqu'ils consultent un panorama Street View, utilisez l'interface StreetPanorama.OnStreetPanoramaLongClickListener pour écouter un geste de clic prolongé. Dès qu'un utilisateur clique de manière prolongée à n'importe quel endroit d'une image Street View, vous recevez un événement onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). Appelez DismissOverlayView.show() pour afficher un bouton de sortie.

Exemple de code

GitHub inclut un exemple d'application que vous pouvez utiliser comme point de départ pour créer votre application. Il montre comment configurer une carte Google basique sous Wear OS.

Fonctionnalités disponibles dans l'API Google Maps sur Wear OS

Cette section souligne les différences entre les fonctionnalités de carte prises en charge sur des objets connectés par rapport aux appareils portables (téléphones et tablettes). Toutes les fonctionnalités d'API non mentionnées ci-dessous devraient fonctionner comme indiqué pour la version complète de l'API.

Fonctionnalité
Mode interactif complet et mode simplifié

Vous pouvez utiliser le SDK Maps pour Android en mode interactif complet ou en mode simplifié. Utilisez le mode simplifié si vous souhaitez optimiser les performances de l'objet connecté et que votre application n'a pas besoin de prendre en charge d'interactions comme des gestes, un panoramique ou un zoom sur la carte.

En mode simplifié, l'intent permettant de démarrer l'application mobile Google Maps lorsque l'utilisateur appuie sur la carte est désactivé et ne peut pas être activé sur un objet connecté.

Pour obtenir la liste complète des différences entre le mode simplifié et le mode interactif complet, consultez la documentation du mode simplifié.

Barre d'outils Carte La barre d'outils Carte est désactivée et ne peut pas être activée sur un objet connecté.
Commandes de l'interface utilisateur Les commandes de l'interface utilisateur sont désactivées par défaut sur les objets connectés. Cela comprend les commandes de zoom, de boussole et le bouton Ma position. Vous pouvez les activer comme d'habitude à l'aide de la classe UiSettings.
Gestes Les gestes à toucher unique fonctionnent normalement. Par exemple, appuyer et faire glisser pour faire un panoramique sur la carte, toucher deux fois pour effectuer un zoom avant et appuyer avec deux doigts pour un zoom arrière. La prise en charge des gestes à touchers multiples varie selon l'appareil de l'utilisateur. Exemples de gestes à touchers multiples : pousser avec deux doigts pour incliner la carte, pincer pour zoomer et effectuer une rotation avec deux doigts.
Plans d'intérieur et bâtiments Les plans d'intérieur sont désactivés par défaut sur les objets connectés. Vous pouvez les activer en appelant GoogleMap.setIndoorEnabled(true). Si les plans d'intérieur sont activés, la carte affiche l'étage par défaut. L'élément d'interface Sélecteur de niveau n'est pas compatible avec les objets connectés.
Superpositions de tuiles Les superpositions de tuiles ne sont pas compatibles avec les objets connectés.

Bonnes pratiques de développement avec l'API Google Maps sur Wear OS

Comment fournir la meilleure expérience utilisateur possible dans votre application :

  • La carte doit occuper la majeure partie de l'écran. Vous devez en effet garantir la facilité d'utilisation de la carte compte tenu du format réduit de l'objet connecté.
  • Lors de la conception de l'expérience utilisateur de votre application, tenez compte du fait qu'un objet connecté dispose d'une autonomie réduite. Le fait de garder l'écran actif et la carte visible aura un impact sur les performances de la batterie.