API Google Maps sur Wear OS

Avec le SDK Maps pour Android, vous pouvez créer une appli de cartographie pour wearables 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 pour wearables avec le SDK Maps pour Android revient pratiquement au même que créer une application Google Maps pour un autre appareil Android. La différence réside dans la conception qui doit tenir compte du facteur de forme plus petit d'un wearable pour optimiser les performances et l'usabilité de l'appli.

Android Studio est l'outil recommandé pour le développement sur Wear OS, car il propose des méthodes utiles 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 pour wearables, consultez les consignes de conception pour Wear OS. Pour des conseils sur la création de votre première appli pour wearables, consultez le guide sur la création d'applis pour wearables.

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 wearable dans votre application et que vous souhaitez à présent ajouter une carte à ce module.

Ajouter les dépendances pour votre module wearable

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

dependencies {
    // ...
    compileOnly("com.google.android.wearable:wearable:2.9.0")
    implementation("com.google.android.support:wearable:2.9.0")
    implementation("com.google.android.gms:play-services-maps:19.0.0")

    // This dependency is necessary for ambient mode
    implementation("androidx.wear:wear:1.3.0")
}

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

Implémenter un geste "balayer pour fermer" et définir la couleur d'arrière-plan initiale

Nous vous recommandons d'utiliser un SwipeDismissFrameLayout pour afficher la carte sur le wearable. 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 :

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

    // ...
}

      

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

    // ...
}

      

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 :

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

      

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

      

Activer le mode ambiant

Le SDK Maps pour Android est compatible avec le mode ambiant pour les applis pour wearables. Les applications qui prennent en charge le mode ambiant sont parfois appelées applications Always-on. Le mode ambiant est activé dès que l'utilisateur n'utilise plus activement l'application et permet à celle-ci de rester visible sur le wearable.

Le SDK Maps pour Android permet d'utiliser un rendu simplifié de la carte en mode ambiant, avec des couleurs atténuées. Le style de la carte s'ajuste automatiquement dès que l'appareil passe du mode interactif au mode ambiant. En mode ambiant, tous les repères, les objets et les commandes d'interface utilisateur disparaissent. Cela permet de réduire la consommation d'énergie de votre application et d'assurer 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 ambiant 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 ambiant. 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 du wearable au fichier build.gradle.kts de votre application. Consultez l'exemple sur cette page.
4. Ajoutez l'entrée dans la bibliothèque partagée du wearable au fichier manifeste de l'appli pour wearables, comme décrit dans la formation Android expliquant comment garder votre application visible.
5. Ajoutez l'autorisation WAKE_LOCK aux fichiers manifestes des applications portables et pour wearables, comme indiqué dans la formation Android expliquant comment 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 et doit être affichée en mode ambiant à la place du cadran lorsque l'appareil passe au mode ambiant.
7. Implémentez l'interface AmbientModeSupport.AmbientCallbackProvider dans votre activité pour qu'elle puisse recevoir les changements d'état du mode ambiant.
8. Configurez votre carte pour qu'elle prenne en charge le mode ambiant. Pour cela, vous pouvez définir l'attribut map:ambientEnabled="true" dans le fichier de mise en page XML de l'activité, ou bien 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 ambiant.
9. Lorsque l'activité passe en mode ambiant, 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 de la carte, avec des couleurs atténuées.
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 ambiant dans l'activité :

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

      

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

      

Vous pouvez actualiser l'écran alors que l'application est en mode ambiant. Pour plus de détails sur l'actualisation du contenu et sur le mode ambiant 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 pris en charge sur les wearables.

Pour permettre aux utilisateurs de quitter l'application lorsqu'ils consultent un panorama Street View, utilisez l'interface StreetViewPanorama.OnStreetViewPanoramaLongClickListener 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

Une application exemple est disponible sur GitHub. Vous pouvez l'utiliser comme point de départ pour votre application. Elle montre comment configurer une carte Google Maps de base sur Wear OS.

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

Cette section décrit les différences entre les fonctionnalités cartographiques prises en charge sur les wearables 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 sur le wearable et que votre application n'a pas besoin de prendre en charge des interactions telles que des gestes, des panoramiques ou des zooms 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 wearable. 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 de la carte	La barre d'outils de la carte est désactivée et ne peut pas être activée sur un wearable.
Commandes d'interface utilisateur	Les commandes d'interface utilisateur sont désactivées par défaut sur les wearables. 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 à un doigt fonctionnent normalement. Par exemple, appuyer et faire glisser pour faire un panoramique sur la carte, appuyer deux fois pour faire un zoom avant et appuyer avec deux doigts pour faire un zoom arrière. La prise en charge des gestes à plusieurs doigts varie selon l'appareil de l'utilisateur. Exemples de gestes à plusieurs doigts : 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 wearables. 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 utilisateur Sélecteur de niveau n'est pas pris en charge sur les wearables.
Superpositions de tuiles	Les superpositions de tuiles ne sont pas prises en charge sur les wearables.

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. C'est nécessaire pour une plus grande facilité d'utilisation de la carte sur le petit facteur de forme d'un wearable.
• En concevant l'expérience utilisateur de votre application, n'oubliez pas qu'un wearable a une autonomie réduite. Le fait de garder l'écran actif et la carte visible aura un impact sur les performances de la batterie.