Aller au contenu principal

SDK React

Des cartes outdoor en composants React

@mountaya/elements-react fournit la carte, ses contrôles, le profil altimétrique et le tableau des segments sous forme de composants. @mountaya/client-react y ajoute le provider, le hook de session et des hooks de requête typés.

Compatible avec les outils que vous utilisez déjà

Nos réponses à vos défis

Intégrez une carte outdoor à votre application React, sans moteur de rendu à brancher.

Un moteur de rendu, une version

MapView initialise le moteur de rendu et signe chaque requête de tuiles. MapLibre s'installe à côté, dans la version sur laquelle son worker de carte est construit.

Des sessions renouvelées avant expiration

useSessionToken appelle votre endpoint d'émission avant l'expiration du jeton. Vos utilisateurs ne voient donc jamais une requête échouer à cause d'un jeton expiré.

Deux composants utilisables sans carte

ItineraryProfile et ItinerarySegmentTable s'affichent sans canvas ni requête de tuiles. Intégrez-les à un tableau de bord, à une barre latérale ou à une vue destinée à l'impression.

Paquets

Les paquets à installer pour React

Des hooks pour récupérer les données, des composants pour les afficher et les briques qui composent l'éditeur.

@mountaya/client-react

npm install @mountaya/client-react

@mountaya/elements-react

npm install @mountaya/elements-react @mountaya/elements @mountaya/client maplibre-gl@6.18.0

@mountaya/studio-react

npm install @mountaya/studio-react maplibre-gl@6.18.0

Carte, profil et tableau

Un même parcours sur la carte, le profil et le tableau

La carte, le composant de profil altimétrique et le composant de tableau des segments affichent le même parcours et se répondent. L'exemple présenté ici est la Patrouille des Glaciers, de Zermatt à Verbier.

Carte hivernale du parcours de la Patrouille des Glaciers, de Zermatt à Verbier.

Tableau des segments de la Patrouille des Glaciers : une ligne par segment, de Zermatt à Verbier, avec sa distance, ses dénivelés positif et négatif et ses altitudes minimale et maximale.

Profil altimétrique du parcours de la Patrouille des Glaciers, qui culmine à 3 643 m après le franchissement de quatre grands cols.
Distance
55,9 km
Dénivelé positif
4 235 m
Dénivelé négatif
4 365 m
Point culminant
3 643 m

Le profil est relié à la carte

Lorsque vous parcourez le profil, une fiche indique la distance, l'altitude et le dénivelé cumulé à l'endroit survolé, et un repère se déplace sur la carte.

Chaque lieu au bon kilomètre

Les points de passage du parcours sont épinglés sur le profil, à la distance où ils se trouvent, et chaque segment est résumé en dessous.

Chaque ligne a son segment

Le survol d'une ligne du tableau met en évidence le segment correspondant sur la carte, et le survol du parcours sur la carte met en évidence sa ligne.

Les mêmes chiffres partout

La distance et le dénivelé de chaque segment sont calculés une seule fois, sur nos serveurs, à partir de la trace complète. Le tableau, le profil et la carte affichent donc exactement les mêmes valeurs.

Intégration

Installer, s'authentifier, interroger, afficher

Un provider, un hook de session, un hook de requête, puis la carte : chaque extrait contient ses propres imports et fonctionne tel quel.

React

Installer

MapLibre s'installe à côté des composants, dans la version exacte sur laquelle leur worker de carte est construit.

npm install @mountaya/client @mountaya/client-react @mountaya/elements @mountaya/elements-react @tanstack/react-query maplibre-gl@6.18.0

S'authentifier

Une clé publiable peut figurer sans risque dans un navigateur et suffit pour afficher la carte. La Data API exige en plus, à chaque requête, un jeton de session émis par votre serveur à partir de votre clé secrète.

import { Mountaya } from "@mountaya/client/browser";
import { useSessionToken } from "@mountaya/client-react";
import { useState } from "react";

// Calls your endpoint and refreshes before expiry, not on a 401.
const { session } = useSessionToken({
  mint: () => fetch("/api/mountaya-session").then((r) => r.json()),
});

// One client for the component's life: a request waits for the first token,
// and a refresh reaches the next call and every map built on the client.
const [client] = useState(
  () => new Mountaya({ credential: { publishableKey, sessionToken: session } }),
);

Appeler

Chaque opération correspond à une méthode typée. La Data API repose sur GraphQL, mais c'est le client qui rédige la requête à votre place.

import { isMountayaApiError } from "@mountaya/client";
import { useItinerary } from "@mountaya/client-react";

export const Itinerary = ({ itineraryId }: { itineraryId: string }) => {
  const { data, error, isPending } = useItinerary(itineraryId);

  if (isPending) return <Spinner />;
  if (error) {
    // The platform's own sentence where it answered; a timeout or a dropped connection has none.
    const message = isMountayaApiError(error) ? error.errors[0]?.message : error.message;
    return <ErrorBanner message={message} />;
  }

  return <h1>{data.name}</h1>;
};

Afficher

Transmettez le client à la carte : elle signe ensuite elle-même ses requêtes de tuiles.

import { Mountaya } from "@mountaya/client";
import type { MountayaMap } from "@mountaya/elements";
import { MapControls, MapView, MountayaElementsProvider } from "@mountaya/elements-react";
import { useState } from "react";
import "@mountaya/elements-react/styles.css"; // the one stylesheet: it carries the elements' own

const client = new Mountaya({ credential: { publishableKey: "pk_…" } });

export const Map = () => {
  const [map, setMap] = useState<MountayaMap | null>(null);

  return (
    <MountayaElementsProvider map={map}>
      <MapView center={[6.86, 45.83]} client={client} onReady={setMap} zoom={12} />
      <MapControls compass geolocate layers preferences zoom />
    </MountayaElementsProvider>
  );
};

Qu'allez-vous construire avec les SDK et Elements ?

Expliquez-nous ce que votre produit doit afficher. Nous vous montrerons les SDK et Elements qui s'en chargent.

Questions fréquentes

@mountaya/client et @mountaya/client-react pour les données, @mountaya/elements et @mountaya/elements-react pour l'affichage. maplibre-gl s'installe à côté, dans la version exacte sur laquelle le worker de carte des composants est construit. Une seule feuille de style est à importer, @mountaya/elements-react/styles.css : elle reprend déjà les styles du moteur de rendu et ceux de @mountaya/elements. Les hooks de requête s'appuient sur TanStack Query.

MapView et MapControls pour la carte, ItineraryProfile et ItinerarySegmentTable pour le parcours, et MountayaElementsProvider pour les relier entre eux. Le paquet client-react ajoute un provider, un hook de session et des hooks de requête typés.

Oui. Par défaut, MapView crée et authentifie le moteur de rendu à votre place. Si vous en avez besoin, créez l'instance vous-même, puis transmettez-la au composant.

Le client d'API fonctionne dès aujourd'hui dans React Native : vous y disposez des données, du routage et de l'analyse du terrain. Les composants de rendu, eux, ne sont pas publiés pour React Native.