Referencia de la Embed API

Todos los comandos y eventos de la Embed API de Icon Map, generados a partir del contrato TypeScript del SDK. Cada comando es un método del identificador que devuelve embed() y se resuelve con el resultado indicado, o se rechaza con un EmbedError cuyo code es uno de los códigos de error.

Un comando marcado como lectura necesita además el conmutador Read state and events del autor. Los tipos que se citan aquí (EmbedCamera, EmbedScene ...) los exporta @iconmap/embed.

Comandos

Sesión

Siempre disponibles una vez abierta una sesión. No dependen de la directiva del autor.

Comando	Argumentos	Se resuelve con	Notas
`ping`	-	`{ protocol: number; uptimeMs: number }`	Ida y vuelta al visor. Útil como comprobación de que sigue activo, y para dejar que se asiente un mensaje asincrónico anterior.
`getCapabilities`	-	`EmbedCapabilities`	De nuevo el descriptor de capacidades (el mismo objeto con el que se resolvió `ready`).
`setToken`	`{ token: string }`	-	Envía un token de inserción nuevo antes de que caduque el anterior (vea `tokenExpiring`). Solo mapas publicados.
`setLanguage`	`{ language: string }`	-	Cambia el idioma del lector. Solo un idioma de `capabilities.map.locales`; cualquier otro se rechaza con `invalid_args`, nunca con una alternativa silenciosa.

Cámara

Mover y leer la vista. Grupo de la directiva: camera.

Comando	Argumentos	Se resuelve con	Notas
`getView`	-	`EmbedViewState`	lectura La cámara y los límites visibles.
`setView`	`Partial<EmbedCamera> & { animate?: boolean }`	-	Establece cualquiera de center / zoom / bearing / pitch. Salta, a menos que `animate` sea true.
`flyTo`	`Partial<EmbedCamera> & { durationMs?: number; curve?: number }`	-	Un vuelo animado hasta una cámara.
`fitBounds`	`{ bounds: EmbedBounds; padding?: EmbedPadding; maxZoom?: number; animate?: boolean; pitch?: number; bearing?: number }`	-	Encuadra un rectángulo delimitador. `pitch` / `bearing` son los valores en los que queda la cámara; si se omiten, mantiene su inclinación actual (pase `pitch: 0, bearing: 0` para un encuadre plano y orientado al norte después de un vuelo inclinado).
`fitLayer`	`{ layerId: string; padding?: EmbedPadding; maxZoom?: number; pitch?: number; bearing?: number }`	-	Encuadra los datos de una capa tal como están filtrados. `unknown_id` cuando la capa no tiene extensión. `pitch` / `bearing` como en `fitBounds`.
`zoomBy`	`{ delta: number; animate?: boolean }`	-	Acerca o aleja según un incremento, limitado al intervalo del mapa.
`resize`	-	-	Indica al mapa que su contenedor cambió de tamaño (después de cambiar el tamaño del elemento padre del marco).
`setMaxBounds`	`{ bounds: EmbedBounds \| null }`	-	Limita el desplazamiento a un rectángulo; `null` quita el límite.

Capas y visibilidad

Mostrar y ocultar lo que publicó el autor. Solo visibilidad, nunca estilo. Grupo de la directiva: layers.

Comando	Argumentos	Se resuelve con	Notas
`getLayers`	-	`EmbedLayerInfo[]`	lectura Las capas del mapa: id, nombre, tipo y si cada una se muestra ahora.
`getVisibility`	-	`EmbedVisibility`	lectura Todos los conmutadores de la escena, completos: capas, etiquetas y grupos de entidades del mapa base, terminador, sombreado, objetos visuales.
`setVisibility`	`EmbedVisibility`	`{ skipped: string[] } \| void`	Aplica una instantánea parcial de visibilidad: lo que omita se queda como está. Los ids desconocidos se omiten y se notifican. Ocultar una segmentación la DESACTIVA, como en un marcador: su selección deja de filtrar hasta que se vuelve a mostrar. Para filtrar el mapa sin mostrar una tarjeta, use el grupo de filtros (`setFilters`).
`setLayerVisibility`	`{ layerId: string; visible: boolean }`	-	Muestra u oculta una capa.
`resetVisibility`	-	-	Devuelve todos los conmutadores al estado publicado por el autor.
`getVisuals`	-	`EmbedVisualInfo[]`	lectura Los gráficos, segmentaciones, cuadros de texto y otros objetos visuales del mapa, con su visibilidad.
`getLayerStats`	`{ layerId: string }`	`{ layerId: string; visibleFeatureCount: number }`	lectura Cuántas entidades contiene la capa en este momento, después de los filtros y las segmentaciones.

Filtros declarados

Valores para los filtros que el autor declaró en el mapa. Solo mapas publicados. Grupo de la directiva: filters.

Comando	Argumentos	Se resuelve con	Notas
`getFilterSchema`	-	`EmbedFilterSchemaEntry[]`	lectura Los filtros que declaró el autor: nombre, tipo, operadores, valor predeterminado. Cree su propia interfaz de filtrado a partir de esto.
`getFilters`	-	`EmbedFilterValues`	lectura Los valores de filtro aplicados actualmente.
`setFilters`	`EmbedFilterValues`	-	Sustituye los valores de filtro. Un nombre que el autor no declaró se rechaza con `undeclared_filter` antes de aplicar nada.
`updateFilters`	`{ operation: EmbedFilterOperation; filters?: EmbedFilterValues; display?: Record<string, EmbedFilterDisplay> }`	-	Añade, sustituye o quita filtros individuales, al estilo de Power BI, con opciones de visualización por filtro opcionales (`locked`, `hidden`, `displayName`).
`clearFilters`	-	-	Quita todos los valores de filtro de la página host.

Datos

Volver a ejecutar consultas en directo. Solo mapas publicados. Grupo de la directiva: data.

Comando	Argumentos	Se resuelve con	Notas
`refreshData`	`{ bindingIds?: string[] } \| void`	`{ refreshed: string[] }`	Vuelve a ejecutar las consultas en directo sin pasar por la caché de resultados. Se resuelve con los ids de enlace actualizados (vacío en un mapa instantáneo).

Segmentaciones

Controlar las segmentaciones del lector. Grupo de la directiva: slicers.

Comando	Argumentos	Se resuelve con	Notas
`getSlicers`	-	`EmbedSlicerInfo[]`	lectura Las segmentaciones del mapa y su estado actual.
`getSlicerValues`	`{ slicerId: string; search?: string }`	`{ values: unknown[]; truncated: boolean }`	lectura Los valores que ofrece una segmentación de lista, opcionalmente restringidos por una cadena de búsqueda. También funciona para una segmentación oculta.
`setSlicerState`	`{ slicerId: string; state: EmbedSlicerState }`	-	Establece la selección de una segmentación, exactamente como si lo hubiera hecho el lector.
`clearSlicer`	`{ slicerId: string }`	-	Borra una segmentación.
`clearAllSlicers`	-	-	Borra todas las segmentaciones.

Selección y resaltado

Seleccionar entidades, aplicar filtros cruzados a gráficos, resaltar sin seleccionar. Grupo de la directiva: selection.

Comando	Argumentos	Se resuelve con	Notas
`getSelection`	-	`EmbedSelection`	lectura Las claves de las entidades seleccionadas, por id de capa.
`setSelection`	`EmbedSelection`	`{ skipped: string[] } \| void`	Sustituye la selección. Los ids de capa desconocidos se omiten y se notifican.
`clearSelection`	-	-	Borra la selección.
`selectByKey`	`{ layerId: string; keys: Array<string \| number>; field?: string; zoomTo?: boolean }`	`{ matched: number }`	Selecciona entidades por sus propias claves: con `field`, las claves se comparan con los valores de ese campo ("activo 41B"); sin él, son claves de entidad tal como las notificó `featureClick`. `zoomTo` encuadra el resultado. Como máximo 500 claves. `field` debe ser una columna que lleve el mapa publicado. Un mapa publicado contiene solo las columnas que usa (información sobre herramientas, estilo, etiquetas, segmentaciones), así que una columna de clave que nada más usa no está y no coincide con nada: el autor la añade a los campos de información sobre herramientas de la capa.
`getChartSelection`	-	`Record<string, EmbedChartDatum[]>`	lectura Los puntos de datos seleccionados en cada gráfico (el filtro cruzado del mapa), por id de gráfico.
`setChartSelection`	`{ chartId: string; datums: EmbedChartDatum[] }`	-	Selecciona puntos de datos en un gráfico, lo que aplica un filtro cruzado al mapa igual que un clic.
`clearChartSelection`	`{ chartId?: string } \| void`	-	Borra la selección de un gráfico, o de todos.
`closePopups`	-	-	Cierra la ventana emergente de la entidad si hay una abierta.
`highlight`	`{ layerId: string; keys: Array<string \| number>; field?: string }`	`{ matched: number }`	Resalte transitorio: pinta `keys` en `layerId` como seleccionadas SIN cambiar la selección: sin ventana emergente, sin ámbito de panel, sin `selectionChanged`. El siguiente clic del lector lo sustituye. Con `field`, las claves se resuelven a través de ese campo como en `selectByKey`.
`clearHighlight`	-	-	Quita un resaltado establecido con `highlight`.

Escenas, marcadores y recorridos

Capturar y restaurar todo el estado de la sesión. Grupo de la directiva: scenes.

Comando	Argumentos	Se resuelve con	Notas
`captureScene`	`{ include?: Array<keyof EmbedScene>; opaque?: boolean } \| void`	`EmbedScene \| { state: string }`	lectura Todo el estado de la sesión como un único objeto serializable: cámara, visibilidad, segmentaciones, filtros, selección, mapa base. Guárdelo o conviértalo en un vínculo con `sceneToUrl`.
`applyScene`	`{ scene: EmbedScene \| { state: string }; animate?: boolean }`	`{ skipped: string[] }`	Restaura una escena capturada. Los ids que el mapa ya no tiene se omiten y se notifican, de modo que una escena sobrevive a una nueva publicación.
`resetScene`	-	-	Devuelve todo al estado publicado por el autor.
`getBookmarks`	-	`EmbedBookmarkInfo[]`	lectura Los marcadores del autor. Vacío a menos que el autor decidiera ofrecer marcadores al publicar el mapa.
`applyBookmark`	`{ bookmarkId: string; animate?: boolean }`	-	Aplica un marcador por la misma ruta que usa la barra de marcadores.
`getTours`	-	`EmbedTourInfo[]`	lectura Los recorridos del autor.
`playTour`	`{ tourId: string }`	-	Inicia un recorrido. Los eventos de cámara generados mientras se reproduce llevan `reason: "tour"`.
`stopTour`	-	-	Detiene el recorrido en reproducción.

Presentación

Mapa base, controles propios, tema, leyenda, exportación de imagen. Grupo de la directiva: presentation.

Comando	Argumentos	Se resuelve con	Notas
`getBasemaps`	-	`EmbedBasemapInfo[]`	lectura Los mapas base que publicó el autor para este mapa, y cuál está activo.
`setBasemap`	`{ basemapId: string }`	-	Cambia a uno de los mapas base publicados. No hay forma de cargar un estilo propio.
`setChrome`	`EmbedChromeSettings`	-	Oculta o muestra los controles propios del mapa (leyenda, control de capas, ventanas emergentes, barra de marcadores, controles del recorrido, búsqueda). Un conmutador puede ocultar un control que el autor configuró; no puede añadir uno que no configuró.
`setTheme`	`EmbedThemeSettings`	-	Claro, oscuro o seguir al mapa.
`setBackground`	`{ background: "default" \| "transparent" }`	-	Hace transparente la página que hay detrás del mapa para que se vea su propio fondo.
`getLegend`	-	`EmbedLegendEntry[]`	lectura La leyenda tal como se representa en este momento, como datos: cree su propia leyenda fuera del marco.
`getMapInfo`	-	`EmbedMapInfo`	lectura El descriptor del mapa: título, descripción, modo de datos, idiomas y la atribución que debe mostrar si oculta nuestros controles.
`print`	-	-	Abre el cuadro de diálogo de impresión del navegador para el mapa. Se rechaza con `denied_capability` cuando una etiqueta de confidencialidad no permite la exportación.
`exportImage`	`EmbedExportImageArgs \| void`	`EmbedExportedImage`	lectura Un PNG o JPEG del mapa tal como lo ve el lector, como URL de datos. Se rechaza con `denied_capability` cuando una etiqueta de confidencialidad no permite la exportación.

Comandos del menú emergente

Añadir acciones propias a la ventana emergente de la entidad. Grupo de la directiva: commands.

Comando	Argumentos	Se resuelve con	Notas
`addMenuCommand`	`EmbedMenuCommand`	-	Añade una acción propia a la ventana emergente de la entidad. Solo un título de texto sin formato y un id pasan al marco, nunca HTML ni script. Al hacer clic en ella se genera `menuCommandTriggered`.
`removeMenuCommand`	`{ id: string }`	-	Quita una acción de la ventana emergente que añadió.
`getMenuCommands`	-	`Array<{ id: string; title: string }>`	lectura Las acciones de la ventana emergente que ha añadido.

Análisis

Ejecutar el motor de análisis de una capa, cuando el mapa tiene uno. Grupo de la directiva: analysis.

Comando	Argumentos	Se resuelve con	Notas
`getAnalysisOps`	-	`EmbedAnalysisOp[]`	lectura Las operaciones de análisis que atiende este mapa, cada una con su capa e indicaciones de argumentos. Vacío cuando el mapa no tiene motor de análisis.
`runAnalysis`	`{ op: string; layerId?: string; args?: Record<string, unknown> }`	`EmbedAnalysisResult`	Ejecuta una operación de análisis. Se ejecuta una por capa a la vez; hasta 4 esperan (`busy` a partir de ahí); 60 por minuto por sesión (`budget_exceeded`). Los resultados grandes se limitan y se marcan como `truncated`.
`getClock`	`{ layerId?: string } \| void`	`EmbedClockState \| null`	lectura El reloj de simulación de una capa de análisis, o null cuando no tiene.
`setClock`	`{ simSeconds: number; layerId?: string }`	`EmbedClockState`	Mueve el reloj de simulación de una capa de análisis.

Solo en el identificador

Se ejecutan en su página, no en el mapa, por lo que nunca aparecen en capabilities.commands.

Miembro	Qué hace
`ready`	Una promesa del descriptor de capacidades. Se rechaza con `denied_origin` cuando su origen no está permitido.
`capabilities`, `protocol`	Lo que atiende este visor, una vez conocido.
`on(name, handler)` / `off(name)`	Se suscribe a un evento; `on` devuelve una función para cancelar la suscripción.
`render(options)`	Completa una inserción diferida (`deferRender: true`).
`reload()`	Recarga el marco. Las suscripciones se restauran cuando se abre la nueva sesión.
`fullscreen()` / `exitFullscreen()`	Pone el marco en pantalla completa. Llámelo desde un controlador de clic: los navegadores exigen un gesto del usuario en su página.
`destroy()`	Quita el marco y rechaza todo lo que esté en curso con `destroyed`.
`iframe`	El elemento `<iframe>` montado.

Eventos

No se envía nada hasta que se suscribe (handle.on(name, handler) o la opción events). Cada evento lleva un seq para toda la sesión; un hueco significa que se descartó uno. Los eventos de estado llevan un reason ("user", "command", "bookmark", "tour", "scene" o "load") para que una sincronización bidireccional pueda ignorar su propio eco.

Evento	Carga	Notas
`loaded`	-	El mapa se representó (el `onLoad` de v1).
`rendered`	`{ durationMs: number }`	Primer fotograma inactivo: los datos propios del mapa están en pantalla. `durationMs` se cuenta desde el inicio del marco.
`viewChanged`	`EmbedViewState & { reason: EmbedChangeReason }`	La cámara se detuvo (o, con `continuousView`, se movió). Con limitación de frecuencia; el último valor siempre llega.
`visibilityChanged`	`{ visibility: EmbedVisibility; reason: EmbedChangeReason }`	Cambió un conmutador de capa, de objeto visual o del mapa base.
`filtersChanged`	`{ filters: EmbedFilterValues; reason: EmbedChangeReason }`	Cambiaron los valores de filtro de la página host.
`slicerChanged`	`{ slicerId: string; state: EmbedSlicerState; reason: EmbedChangeReason }`	Cambió la selección de una segmentación.
`selectionChanged`	`{ selection: EmbedSelection; reason: EmbedChangeReason }`	Cambió la selección.
`featureClick`	`EmbedFeatureClick \| null`	El lector hizo clic en una entidad (`null` = clic en una zona vacía del mapa). `fields` contiene solo los campos de información sobre herramientas de la capa: lo que el lector ya puede ver.
`featureHover`	`EmbedFeatureClick \| null`	El puntero entró en una entidad (`null` = salió). Desactivado a menos que se suscriba; espaciado al menos 100 ms, y una salida nunca se retrasa.
`linkClicked`	`{ url: string; layerId?: string; featureKey?: string \| number; buttonId?: string }`	Se hizo clic en un hipervínculo o un botón de vínculo, cuando `hyperlinkBehavior` es `raiseEvent` o `navigateAndRaiseEvent`. Gestiónelo dentro de su propia aplicación.
`menuCommandTriggered`	`{ commandId: string; layerId: string; featureKey: string \| number; fields: Record<string, unknown> }`	El lector eligió una acción de la ventana emergente que usted añadió con `addMenuCommand`.
`chartSelectionChanged`	`{ chartId: string; datums: EmbedChartDatum[]; reason: EmbedChangeReason }`	Cambiaron los puntos de datos seleccionados de un gráfico.
`bookmarkApplied`	`{ bookmarkId: string }`	Se aplicó un marcador: el lector, un recorrido o usted.
`tourStateChanged`	`{ tourId: string \| null; state: "started" \| "keyframe" \| "ended" }`	Un recorrido se inició, llegó a un fotograma clave o terminó.
`basemapChanged`	`{ basemapId: string }`	Cambió el mapa base activo.
`themeChanged`	`{ mode: string }`	Cambió el tema.
`dataStateChanged`	`{ state: "loading" \| "ready" \| "stale" \| "error"; bindingIds?: string[]; reason?: string }`	Los datos en directo empezaron a cargarse, quedaron listos, se quedaron obsoletos o fallaron.
`tokenExpiring`	`{ expiresInMs: number }`	El token de inserción caduca en `expiresInMs` (se genera 60 s antes). Responda con `setToken`.
`error`	`EmbedErrorInfo`	Un error del visor después de abrirse la sesión.
`viewerResized`	`{ width: number; height: number }`	El contenedor del mapa cambió de tamaño.
`analysisResult`	`EmbedAnalysisResult & { reason: EmbedChangeReason }`	Terminó una operación de análisis, tanto si el lector hizo clic como si la ordenó la página host.
`clockChanged`	`EmbedClockState & { reason: EmbedChangeReason }`	Se movió el reloj del motor de una capa de análisis (con limitación de frecuencia, `EMBED_LIMITS.clockIntervalMs`).

Códigos de error

Código	Significado
`unsupported_protocol`	El visor y el SDK no comparten ninguna versión de protocolo.
`unsupported_command`	Esta compilación del visor, este tipo de inserción o este mapa no atiende el comando. Compruebe primero `capabilities.commands`.
`denied_capability`	El autor del mapa no ha activado el grupo del comando (o el acceso de lectura), o una etiqueta de confidencialidad impide una exportación.
`denied_origin`	El origen de su página no está entre los orígenes permitidos del mapa, por lo que no se abrió ninguna sesión de control.
`invalid_args`	Los argumentos no superaron la validación. `message` indica cuál.
`not_ready`	La parte del mapa que necesita el comando no estuvo disponible en 10 segundos. Los comandos enviados antes de tiempo se retienen, no se rechazan, así que esto significa que el mapa no se pudo iniciar: compruebe `onError`.
`unknown_id`	Un id de capa, marcador, recorrido, segmentación, gráfico, mapa base u operación de análisis que este mapa no tiene.
`undeclared_filter`	`setFilters` indicó un filtro que el autor no declaró. `detail.undeclared` los enumera.
`rate_limited`	Más de 60 comandos en un segundo, o el límite de frecuencia del back-end en una actualización de datos.
`budget_exceeded`	Se agotó el presupuesto de análisis por sesión o el presupuesto de consultas de la publicación.
`too_large`	El mensaje del comando superó `EMBED_LIMITS.maxCommandBytes`.
`busy`	Ya hay demasiados comandos de análisis esperando en esa capa.
`data_error`	El back-end no pudo completar una solicitud de datos. Indique `requestId` en una solicitud de soporte.
`auth_required`	Falta el token de inserción, ha caducado o se ha rechazado. Proporcione `getToken` o llame a `setToken`.
`timeout`	El visor no respondió dentro del tiempo de espera del comando (en el SDK).
`destroyed`	El identificador se destruyó, o el marco se recargó, mientras el comando estaba en curso (en el SDK).
`internal`	El comando produjo una excepción inesperada. `detailedMessage` contiene la causa.

Límites

Los fija el visor (EMBED_LIMITS en el SDK). Una página host no puede aumentarlos y un autor no puede reducirlos.

Límite	Valor
Mensaje de comando más grande	64 KB: si es mayor, se rechaza con `too_large`
Carga de evento más grande	32 KB: si es mayor, se descarta (verá un hueco en `seq`)
Claves en un `highlight` / `selectByKey`	500
Ids en un resultado de análisis	1000; después, `truncated: true`
Filas en un resultado de análisis	200; después, `truncated: true`
Comandos de análisis por sesión	60 por minuto; después, `budget_exceeded`
Comandos de análisis en espera en una capa	4; después, `busy`
Espaciado de `featureHover`	100 ms (el último valor siempre llega)
Espaciado de `clockChanged`	250 ms (el último valor siempre llega)
Comandos por segundo	60; después, `rate_limited`