Langue

Français

Référence de l'API Embed

Chaque commande et chaque événement de l'API Embed d'Icon Map, générés à partir du contrat TypeScript du SDK. Chaque commande est une méthode du handle renvoyé par embed() ; elle se résout avec le résultat indiqué, ou est rejetée avec une EmbedError dont le code est l'un des codes d'erreur.

Une commande marquée read nécessite aussi le réglage Read state and events de l'auteur. Les types cités ici (EmbedCamera, EmbedScene ...) sont exportés par @iconmap/embed.

Commandes

Session

Toujours disponibles dès qu'une session est ouverte. Non soumises à la stratégie de l'auteur.

Commande	Arguments	Se résout avec	Remarques
`ping`	-	`{ protocol: number; uptimeMs: number }`	Aller-retour jusqu'à la visionneuse. Utile pour vérifier que la carte répond, et pour laisser un message asynchrone antérieur se terminer.
`getCapabilities`	-	`EmbedCapabilities`	Le descripteur de capacités, à nouveau (le même objet que celui avec lequel `ready` s'est résolu).
`setToken`	`{ token: string }`	-	Fournit un nouveau jeton d'intégration avant l'expiration de l'ancien (voir `tokenExpiring`). Cartes publiées uniquement.
`setLanguage`	`{ language: string }`	-	Change la langue du lecteur. Uniquement une langue de `capabilities.map.locales` ; toute autre valeur est rejetée avec `invalid_args`, jamais de repli silencieux.

Caméra

Déplacer et lire la vue. Groupe de stratégie : camera.

Commande	Arguments	Se résout avec	Remarques
`getView`	-	`EmbedViewState`	read La caméra et les limites visibles.
`setView`	`Partial<EmbedCamera> & { animate?: boolean }`	-	Définit n'importe quelle valeur parmi center / zoom / bearing / pitch. Saute directement, sauf si `animate` vaut true.
`flyTo`	`Partial<EmbedCamera> & { durationMs?: number; curve?: number }`	-	Un vol animé vers une position de caméra.
`fitBounds`	`{ bounds: EmbedBounds; padding?: EmbedPadding; maxZoom?: number; animate?: boolean; pitch?: number; bearing?: number }`	-	Cadre un rectangle englobant. `pitch` / `bearing` sont les valeurs sur lesquelles la caméra se pose ; sans eux, elle conserve son inclinaison actuelle (passez `pitch: 0, bearing: 0` pour un cadrage à plat, nord en haut, après un vol incliné).
`fitLayer`	`{ layerId: string; padding?: EmbedPadding; maxZoom?: number; pitch?: number; bearing?: number }`	-	Cadre les données d'une couche telles que filtrées actuellement. `unknown_id` si la couche n'a pas d'étendue. `pitch` / `bearing` comme pour `fitBounds`.
`zoomBy`	`{ delta: number; animate?: boolean }`	-	Zoome avant ou arrière d'un delta, borné à la plage de la carte.
`resize`	-	-	Indique à la carte que son conteneur a changé de taille (après avoir redimensionné le parent du cadre).
`setMaxBounds`	`{ bounds: EmbedBounds \| null }`	-	Limite le déplacement à un rectangle ; `null` supprime la limite.

Couches et visibilité

Afficher et masquer ce que l'auteur a publié. Visibilité uniquement, jamais le style. Groupe de stratégie : layers.

Commande	Arguments	Se résout avec	Remarques
`getLayers`	-	`EmbedLayerInfo[]`	read Les couches de la carte : id, nom, type, et si chacune est affichée actuellement.
`getVisibility`	-	`EmbedVisibility`	read Chaque bascule de la scène, entièrement renseignée : couches, étiquettes et groupes d'entités du fond de carte, terminateur, ombrage, visuels.
`setVisibility`	`EmbedVisibility`	`{ skipped: string[] } \| void`	Applique un instantané partiel de visibilité : ce que vous omettez reste inchangé. Les id inconnus sont ignorés et signalés. Masquer un segment le DÉSACTIVE, comme dans un signet : sa sélection cesse de filtrer jusqu'à ce qu'il soit de nouveau affiché. Pour filtrer la carte sans afficher de carte de segment, utilisez le groupe des filtres (`setFilters`).
`setLayerVisibility`	`{ layerId: string; visible: boolean }`	-	Affiche ou masque une couche.
`resetVisibility`	-	-	Remet chaque bascule dans l'état publié par l'auteur.
`getVisuals`	-	`EmbedVisualInfo[]`	read Les graphiques, segments, zones de texte et autres visuels de la carte, avec leur visibilité.
`getLayerStats`	`{ layerId: string }`	`{ layerId: string; visibleFeatureCount: number }`	read Le nombre d'entités que contient la couche à cet instant, après filtres et segments.

Filtres déclarés

Valeurs des filtres déclarés par l'auteur sur la carte. Cartes publiées uniquement. Groupe de stratégie : filters.

Commande	Arguments	Se résout avec	Remarques
`getFilterSchema`	-	`EmbedFilterSchemaEntry[]`	read Les filtres déclarés par l'auteur : nom, type, opérateurs, valeur par défaut. Construisez votre propre interface de filtrage à partir de ces informations.
`getFilters`	-	`EmbedFilterValues`	read Les valeurs de filtre actuellement appliquées.
`setFilters`	`EmbedFilterValues`	-	Remplace les valeurs de filtre. Un nom que l'auteur n'a pas déclaré est rejeté avec `undeclared_filter` avant que quoi que ce soit ne soit appliqué.
`updateFilters`	`{ operation: EmbedFilterOperation; filters?: EmbedFilterValues; display?: Record<string, EmbedFilterDisplay> }`	-	Ajoute, remplace ou supprime des filtres individuels, à la manière de Power BI, avec des paramètres d'affichage facultatifs par filtre (`locked`, `hidden`, `displayName`).
`clearFilters`	-	-	Supprime toutes les valeurs de filtre de l'hôte.

Données

Réexécuter les requêtes en direct. Cartes publiées uniquement. Groupe de stratégie : data.

Commande	Arguments	Se résout avec	Remarques
`refreshData`	`{ bindingIds?: string[] } \| void`	`{ refreshed: string[] }`	Réexécute les requêtes en direct sans passer par le cache des résultats. Se résout avec les id de liaison actualisés (vide sur une carte instantanée).

Segments

Piloter les segments du lecteur. Groupe de stratégie : slicers.

Commande	Arguments	Se résout avec	Remarques
`getSlicers`	-	`EmbedSlicerInfo[]`	read Les segments de la carte et leur état actuel.
`getSlicerValues`	`{ slicerId: string; search?: string }`	`{ values: unknown[]; truncated: boolean }`	read Les valeurs proposées par un segment de liste, éventuellement restreintes par une chaîne de recherche. Fonctionne aussi pour un segment masqué.
`setSlicerState`	`{ slicerId: string; state: EmbedSlicerState }`	-	Définit la sélection d'un segment, exactement comme si le lecteur l'avait fait.
`clearSlicer`	`{ slicerId: string }`	-	Efface un segment.
`clearAllSlicers`	-	-	Efface tous les segments.

Sélection et mise en surbrillance

Sélectionner des entités, filtrer les graphiques de manière croisée, mettre en surbrillance sans sélectionner. Groupe de stratégie : selection.

Commande	Arguments	Se résout avec	Remarques
`getSelection`	-	`EmbedSelection`	read Les clés des entités sélectionnées, par id de couche.
`setSelection`	`EmbedSelection`	`{ skipped: string[] } \| void`	Remplace la sélection. Les id de couche inconnus sont ignorés et signalés.
`clearSelection`	-	-	Efface la sélection.
`selectByKey`	`{ layerId: string; keys: Array<string \| number>; field?: string; zoomTo?: boolean }`	`{ matched: number }`	Sélectionne des entités à l'aide de vos propres clés : avec `field`, les clés sont comparées aux valeurs de ce champ (« équipement 41B ») ; sans, ce sont des clés d'entité telles que `featureClick` les a signalées. `zoomTo` cadre le résultat. 500 clés au maximum. `field` doit être une colonne présente dans la carte publiée. Une carte publiée ne contient que les colonnes qu'elle utilise (info-bulles, style, étiquettes, segments) : une colonne de clé utilisée nulle part ailleurs en est absente et ne correspond à rien. L'auteur l'ajoute alors aux champs d'info-bulle de la couche.
`getChartSelection`	-	`Record<string, EmbedChartDatum[]>`	read Les points de données sélectionnés dans chaque graphique (le filtre croisé de la carte), par id de graphique.
`setChartSelection`	`{ chartId: string; datums: EmbedChartDatum[] }`	-	Sélectionne des points de données dans un graphique, ce qui filtre la carte de manière croisée comme le ferait un clic.
`clearChartSelection`	`{ chartId?: string } \| void`	-	Efface la sélection d'un graphique, ou de tous.
`closePopups`	-	-	Ferme la fenêtre contextuelle d'entité si elle est ouverte.
`highlight`	`{ layerId: string; keys: Array<string \| number>; field?: string }`	`{ matched: number }`	Mise en évidence passagère : dessine `keys` sur `layerId` comme sélectionnées SANS modifier la sélection, donc pas de fenêtre contextuelle, pas de portée de panneau, pas de `selectionChanged`. Le prochain clic du lecteur la remplace. Avec `field`, les clés sont résolues via ce champ comme pour `selectByKey`.
`clearHighlight`	-	-	Supprime une mise en surbrillance définie avec `highlight`.

Scènes, signets et visites

Capturer et restaurer l'état complet de la session. Groupe de stratégie : scenes.

Commande	Arguments	Se résout avec	Remarques
`captureScene`	`{ include?: Array<keyof EmbedScene>; opaque?: boolean } \| void`	`EmbedScene \| { state: string }`	read L'état complet de la session sous la forme d'un seul objet sérialisable : caméra, visibilité, segments, filtres, sélection, fond de carte. Stockez-le, ou transformez-le en lien avec `sceneToUrl`.
`applyScene`	`{ scene: EmbedScene \| { state: string }; animate?: boolean }`	`{ skipped: string[] }`	Restaure une scène capturée. Les id que la carte n'a plus sont ignorés et signalés : une scène survit ainsi à une republication.
`resetScene`	-	-	Remet tout dans l'état publié par l'auteur.
`getBookmarks`	-	`EmbedBookmarkInfo[]`	read Les signets de l'auteur. Vide sauf si l'auteur a choisi de proposer des signets lors de la publication de la carte.
`applyBookmark`	`{ bookmarkId: string; animate?: boolean }`	-	Applique un signet par le même chemin que la barre de signets.
`getTours`	-	`EmbedTourInfo[]`	read Les visites de l'auteur.
`playTour`	`{ tourId: string }`	-	Lance une visite. Les événements de caméra déclenchés pendant sa lecture portent `reason: "tour"`.
`stopTour`	-	-	Arrête la visite en cours.

Présentation

Fond de carte, contrôles, thème, légende, export d'image. Groupe de stratégie : presentation.

Commande	Arguments	Se résout avec	Remarques
`getBasemaps`	-	`EmbedBasemapInfo[]`	read Les fonds de carte publiés par l'auteur pour cette carte, et celui qui est actif.
`setBasemap`	`{ basemapId: string }`	-	Bascule vers l'un des fonds de carte publiés. Il n'existe aucun moyen de charger votre propre style.
`setChrome`	`EmbedChromeSettings`	-	Masque ou affiche les contrôles propres à la carte (légende, contrôle des couches, fenêtres contextuelles, barre de signets, commandes de visite, recherche). Un réglage peut masquer un contrôle configuré par l'auteur ; il ne peut pas en ajouter un que l'auteur n'a pas configuré.
`setTheme`	`EmbedThemeSettings`	-	Clair, sombre, ou celui de la carte.
`setBackground`	`{ background: "default" \| "transparent" }`	-	Rend transparente la page derrière la carte, pour laisser apparaître votre propre arrière-plan.
`getLegend`	-	`EmbedLegendEntry[]`	read La légende telle qu'elle est affichée, sous forme de données : construisez votre propre légende hors du cadre.
`getMapInfo`	-	`EmbedMapInfo`	read Le descripteur de la carte : titre, description, mode des données, langues, et l'attribution que vous devez afficher si vous masquez nos contrôles.
`print`	-	-	Ouvre la boîte de dialogue d'impression du navigateur pour la carte. Refusée avec `denied_capability` lorsqu'une étiquette de confidentialité n'autorise pas l'exportation.
`exportImage`	`EmbedExportImageArgs \| void`	`EmbedExportedImage`	read Une image PNG ou JPEG de la carte telle que le lecteur la voit, sous forme d'URL de données. Refusée avec `denied_capability` lorsqu'une étiquette de confidentialité n'autorise pas l'exportation.

Ajouter vos propres actions à la fenêtre contextuelle d'entité. Groupe de stratégie : commands.

Commande	Arguments	Se résout avec	Remarques
`addMenuCommand`	`EmbedMenuCommand`	-	Ajoute votre propre action à la fenêtre contextuelle d'entité. Seuls un titre en texte brut et un id entrent dans le cadre, jamais de HTML ni de script. Un clic dessus déclenche `menuCommandTriggered`.
`removeMenuCommand`	`{ id: string }`	-	Supprime une action de fenêtre contextuelle que vous avez ajoutée.
`getMenuCommands`	-	`Array<{ id: string; title: string }>`	read Les actions de fenêtre contextuelle que vous avez ajoutées.

Analyse

Exécuter le moteur d'analyse d'une couche, lorsque la carte en a un. Groupe de stratégie : analysis.

Commande	Arguments	Se résout avec	Remarques
`getAnalysisOps`	-	`EmbedAnalysisOp[]`	read Les opérations d'analyse auxquelles cette carte répond, chacune avec sa couche et des indications sur ses arguments. Vide lorsque la carte n'a pas de moteur d'analyse.
`runAnalysis`	`{ op: string; layerId?: string; args?: Record<string, unknown> }`	`EmbedAnalysisResult`	Exécute une opération d'analyse. Une seule s'exécute à la fois par couche ; jusqu'à 4 attendent (`busy` au-delà) ; 60 par minute et par session (`budget_exceeded`). Les résultats volumineux sont plafonnés et marqués `truncated`.
`getClock`	`{ layerId?: string } \| void`	`EmbedClockState \| null`	read L'horloge de simulation d'une couche d'analyse, ou null si elle n'en a pas.
`setClock`	`{ simSeconds: number; layerId?: string }`	`EmbedClockState`	Déplace l'horloge de simulation d'une couche d'analyse.

Sur le handle uniquement

Ces membres s'exécutent dans votre page, pas dans la carte : ils n'apparaissent donc jamais dans capabilities.commands.

Membre	Rôle
`ready`	Une promesse du descripteur de capacités. Rejetée avec `denied_origin` lorsque votre origine n'est pas autorisée.
`capabilities`, `protocol`	Ce à quoi répond cette visionneuse, une fois connu.
`on(name, handler)` / `off(name)`	S'abonner à un événement ; `on` renvoie une fonction de désabonnement.
`render(options)`	Termine une incorporation différée (`deferRender: true`).
`reload()`	Recharge le cadre. Les abonnements sont rétablis à l'ouverture de la nouvelle session.
`fullscreen()` / `exitFullscreen()`	Affiche le cadre en plein écran. À appeler depuis un gestionnaire de clic : les navigateurs exigent un geste de l'utilisateur sur votre page.
`destroy()`	Supprime le cadre et rejette toute commande en cours avec `destroyed`.
`iframe`	L'élément `<iframe>` monté.

Événements

Rien n'est envoyé tant que vous ne vous êtes pas abonné (handle.on(name, handler) ou l'option events). Chaque événement porte un seq propre à la session ; un trou signifie qu'un événement a été perdu. Les événements d'état portent une reason ("user", "command", "bookmark", "tour", "scene" ou "load"), ce qui permet à une synchronisation bidirectionnelle d'ignorer son propre écho.

Événement	Charge utile	Remarques
`loaded`	-	La carte s'est affichée (le `onLoad` de la v1).
`rendered`	`{ durationMs: number }`	Première image au repos : les données propres à la carte sont à l'écran. `durationMs` est mesuré depuis le démarrage du cadre.
`viewChanged`	`EmbedViewState & { reason: EmbedChangeReason }`	La caméra s'est stabilisée (ou, avec `continuousView`, s'est déplacée). Limité en fréquence ; la dernière valeur arrive toujours.
`visibilityChanged`	`{ visibility: EmbedVisibility; reason: EmbedChangeReason }`	Une bascule de couche, de visuel ou de fond de carte a changé.
`filtersChanged`	`{ filters: EmbedFilterValues; reason: EmbedChangeReason }`	Les valeurs de filtre de l'hôte ont changé.
`slicerChanged`	`{ slicerId: string; state: EmbedSlicerState; reason: EmbedChangeReason }`	La sélection d'un segment a changé.
`selectionChanged`	`{ selection: EmbedSelection; reason: EmbedChangeReason }`	La sélection a changé.
`featureClick`	`EmbedFeatureClick \| null`	Le lecteur a cliqué sur une entité (`null` = clic sur une zone vide de la carte). `fields` ne contient que les champs d'info-bulle de la couche, c'est-à-dire ce que le lecteur voit déjà.
`featureHover`	`EmbedFeatureClick \| null`	Le pointeur est entré sur une entité (`null` = il l'a quittée). Inactif tant que vous ne vous abonnez pas ; espacé d'au moins 100 ms, et une sortie n'est jamais retardée.
`linkClicked`	`{ url: string; layerId?: string; featureKey?: string \| number; buttonId?: string }`	Un lien hypertexte ou un bouton de lien a été cliqué, lorsque `hyperlinkBehavior` vaut `raiseEvent` ou `navigateAndRaiseEvent`. Gérez la navigation dans votre propre application.
`menuCommandTriggered`	`{ commandId: string; layerId: string; featureKey: string \| number; fields: Record<string, unknown> }`	Le lecteur a choisi une action de fenêtre contextuelle que vous avez ajoutée avec `addMenuCommand`.
`chartSelectionChanged`	`{ chartId: string; datums: EmbedChartDatum[]; reason: EmbedChangeReason }`	Les points de données sélectionnés d'un graphique ont changé.
`bookmarkApplied`	`{ bookmarkId: string }`	Un signet a été appliqué, par le lecteur, une visite ou vous.
`tourStateChanged`	`{ tourId: string \| null; state: "started" \| "keyframe" \| "ended" }`	Une visite a démarré, atteint une image clé ou s'est terminée.
`basemapChanged`	`{ basemapId: string }`	Le fond de carte actif a changé.
`themeChanged`	`{ mode: string }`	Le thème a changé.
`dataStateChanged`	`{ state: "loading" \| "ready" \| "stale" \| "error"; bindingIds?: string[]; reason?: string }`	Les données en direct ont commencé à se charger, sont prêtes, sont devenues obsolètes ou ont échoué.
`tokenExpiring`	`{ expiresInMs: number }`	Le jeton d'intégration expire dans `expiresInMs` (déclenché 60 s à l'avance). Répondez avec `setToken`.
`error`	`EmbedErrorInfo`	Une erreur de la visionneuse survenue après l'ouverture de la session.
`viewerResized`	`{ width: number; height: number }`	Le conteneur de la carte a changé de taille.
`analysisResult`	`EmbedAnalysisResult & { reason: EmbedChangeReason }`	Une opération d'analyse s'est terminée, qu'elle ait été déclenchée par un clic du lecteur ou par une commande de l'hôte.
`clockChanged`	`EmbedClockState & { reason: EmbedChangeReason }`	L'horloge du moteur d'une couche d'analyse a avancé (limité en fréquence, `EMBED_LIMITS.clockIntervalMs`).

Codes d'erreur

Code	Signification
`unsupported_protocol`	La visionneuse et le SDK n'ont aucune version de protocole en commun.
`unsupported_command`	Cette version de la visionneuse, ce type d'incorporation ou cette carte ne répond pas à la commande. Vérifiez d'abord `capabilities.commands`.
`denied_capability`	L'auteur de la carte n'a pas activé le groupe de la commande (ou l'accès en lecture), ou une étiquette de confidentialité refuse une exportation.
`denied_origin`	L'origine de votre page ne figure pas parmi les origines autorisées de la carte : aucune session de contrôle n'a été ouverte.
`invalid_args`	La validation des arguments a échoué. `message` indique lequel.
`not_ready`	La partie de la carte dont la commande a besoin n'est pas devenue disponible en 10 secondes. Les commandes envoyées trop tôt sont mises en attente, pas refusées : cela signifie donc que la carte n'a pas réussi à démarrer. Consultez `onError`.
`unknown_id`	Un id de couche, de signet, de visite, de segment, de graphique, de fond de carte ou d'opération d'analyse que cette carte n'a pas.
`undeclared_filter`	`setFilters` a nommé un filtre que l'auteur n'a pas déclaré. `detail.undeclared` les liste.
`rate_limited`	Plus de 60 commandes en une seconde, ou la limite de débit du backend sur une actualisation des données.
`budget_exceeded`	Le budget d'analyse par session, ou le budget de requêtes de la publication, est épuisé.
`too_large`	Le message de commande a dépassé `EMBED_LIMITS.maxCommandBytes`.
`busy`	Trop de commandes d'analyse attendent déjà sur cette couche.
`data_error`	Le backend a fait échouer une requête de données. Indiquez le `requestId` dans votre demande au support.
`auth_required`	Le jeton d'intégration est absent, expiré ou refusé. Fournissez `getToken` ou appelez `setToken`.
`timeout`	La visionneuse n'a pas répondu dans le délai d'expiration de la commande (côté SDK).
`destroyed`	Le handle a été détruit, ou le cadre rechargé, pendant que la commande était en cours (côté SDK).
`internal`	La commande a levé une exception inattendue. `detailedMessage` en donne la cause.

Limites

Fixées par la visionneuse (EMBED_LIMITS dans le SDK). Un hôte ne peut pas les relever et un auteur ne peut pas les abaisser.

Limite	Valeur
Taille maximale d'un message de commande	64 KB, au-delà refusé avec `too_large`
Taille maximale d'une charge utile d'événement	32 KB, au-delà abandonnée (vous voyez un trou dans `seq`)
Clés dans un seul `highlight` / `selectByKey`	500
Id dans un résultat d'analyse	1000, puis `truncated: true`
Lignes dans un résultat d'analyse	200, puis `truncated: true`
Commandes d'analyse par session	60 par minute, puis `budget_exceeded`
Commandes d'analyse en attente sur une couche	4, puis `busy`
Espacement de `featureHover`	100 ms (la dernière valeur arrive toujours)
Espacement de `clockChanged`	250 ms (la dernière valeur arrive toujours)
Commandes par seconde	60, puis `rate_limited`