Si viene de Power BI Embedded

Si ha insertado informes de Power BI con powerbi-client, la Embed API de Icon Map le resultará familiar a propósito: un iframe, un identificador, métodos que devuelven promesas, eventos a los que se suscribe, filtros que establece desde su página, marcadores que captura y aplica. Esta página relaciona una con la otra.

Los mismos dos modelos de inserción

Power BI	Icon Map
Insertar para sus clientes (la aplicación es propietaria de los datos)	Un mapa publicado: `embed(element, { publishId })`
Insertar para su organización (el usuario es propietario de los datos)	`embedForOrganization(element, { mapItem })`
Token de inserción desde su servidor	Token de inserción desde su servidor, para publicaciones protegidas con token (`getToken`)
Token de Entra para el usuario que ha iniciado sesión	Lo mismo (`getToken(scopes)`), o inicio de sesión dentro del marco

Arranque

// Power BI
const report = powerbi.embed(element, { type: "report", id, embedUrl, accessToken, settings });
report.on("loaded", () => { /* now it is safe to call things */ });

// Icon Map
const map = embed(element, { publishId, getToken });
await map.ready;      // optional - commands sent early are held, not lost

Power BI	Icon Map
`powerbi.embed(el, config)`	`embed(el, options)`
`powerbi.get(el)`	`getEmbed(el)`
`powerbi.reset(el)`	`reset(el)`
`powerbi.bootstrap()` y después `embed()`: iniciar la descarga antes de tener un token	`embed(el, { deferRender: true })` y después `map.render({ getToken })`
`report.setAccessToken(token)`	`map.setToken({ token })`
Gestión de `tokenExpiration`	Evento `tokenExpiring`
`report.reload()` / `refresh()`	`map.reload()` / `map.refreshData()`
`report.fullscreen()`	`map.fullscreen()`
`report.print()`	`map.print()`
`report.iframe`	`map.iframe`

Una diferencia que conviene conocer: no tiene que esperar a un evento loaded antes de llamar a la API. Los comandos emitidos antes de tiempo se retienen hasta que el mapa puede responderlos.

Filtros

Power BI	Icon Map
`getFilters()` / `setFilters()` / `removeFilters()`	`getFilters()` / `setFilters()` / `clearFilters()`
`updateFilters(operation, filters)` con `Add`, `Replace`, `ReplaceAll`, `RemoveAll`	`updateFilters({ operation, filters })` con `add`, `replace`, `replaceAll`, `removeAll`
Filtro básico (`In`)	Un valor de lista: `{ region: ["EMEA", "APAC"] }`
Filtro avanzado (intervalo)	`{ revenue: { low: 1000, high: 5000 } }`
Filtro de fecha relativa	`{ period: { operator: "inLast", count: 30, unit: "days" } }`
`filter.displaySettings` (`isLockedInViewMode`, `isHiddenInViewMode`, `displayName`)	`display: { region: { locked, hidden, displayName } }`
Cualquier tabla y columna del modelo	Solo los filtros que declaró el autor: descúbralos con `getFilterSchema()`

La última fila es la verdadera diferencia. En Power BI su página indica cualquier columna; en Icon Map indica un filtro que el autor decidió ofrecer, y cualquier otra cosa se rechaza con undeclared_filter. Consulte Filtros.

Segmentaciones, selección y marcadores

Power BI	Icon Map
`visual.getSlicerState()` / `setSlicerState()`	`getSlicers()` / `setSlicerState({ slicerId, state })`
Evento `dataSelected`	`featureClick` y `selectionChanged`
Selección de puntos de datos desde su página	`selectByKey({ layerId, field, keys })`, `setSelection()`
-	`highlight()`: resalte sin selección, para pasar el puntero por una lista
`bookmarksManager.getBookmarks()` / `apply(name)`	`getBookmarks()` / `applyBookmark({ bookmarkId })`
`bookmarksManager.capture()` / `applyState(state)`	`captureScene()` / `applyScene({ scene })`
Evento `bookmarkApplied`	Evento `bookmarkApplied`
URL del informe con `?bookmarkGuid=` o `?filter=`	Vínculos profundos: `?bookmark=`, `?f.<name>=`, `#s=`

Una escena capturada es un objeto simple y documentado en lugar de una cadena opaca, y sobrevive a una nueva publicación: las partes que ya no existen se omiten y se notifican en lugar de provocar un fallo.

Presentación y navegación

Power BI	Icon Map
`settings.panes`, `filterPaneEnabled`, `navContentPaneEnabled`	`setChrome({ legend, layerControl, bookmarksBar, search ... })`
`settings.background: Transparent`	`setBackground({ background: "transparent" })`
`report.applyTheme()`	`setTheme({ mode })`: claro, oscuro o automático. No se admiten temas personalizados
`settings.localeSettings`	Opción `language`, `setLanguage()`
`settings.hyperlinkClickBehavior: RaiseEvent` + `dataHyperlinkClicked`	`hyperlinkBehavior: "raiseEvent"` + `linkClicked`
`getPages()` / `setPage()`	No hay páginas. Lo más parecido son los marcadores y `getLayers()` / `setVisibility()`
`setZoom` de página y de objeto visual	El grupo de cámara: `setView`, `flyTo`, `fitBounds`, `fitLayer`
`visual.exportData()`	Sin equivalente, por diseño; vea más abajo
`report.saveAs()`, modo de edición, `switchMode()`	Sin equivalente. Un mapa insertado es solo de visualización

Comandos personalizados

Power BI	Icon Map
Comando `settings.extensions` en el menú contextual de un objeto visual	`addMenuCommand({ id, title, layerIds? })` en la ventana emergente de la entidad
Evento `commandTriggered`	Evento `menuCommandTriggered`

Eventos

Power BI	Icon Map
`loaded`	Promesa `ready`, evento `loaded`
`rendered`	`rendered` (con `durationMs`)
`error`	Opción `onError`, evento `error`, promesas rechazadas con un `code`
`pageChanged`	`bookmarkApplied`, `visibilityChanged`
`filtersApplied`	`filtersChanged`
`visualClicked`, `dataSelected`	`featureClick`, `selectionChanged`
-	`viewChanged`: la cámara

Cada evento de estado de Icon Map lleva un reason (user, command, bookmark ...), algo que los de Power BI no tienen. Existe para que una página que refleja el mapa pueda ignorar el eco de sus propios comandos; consulte Eventos.

Lo que funciona de forma distinta

Detección de funciones. En lugar de comprobar versiones del SDK o del servicio, lea (await map.ready).commands. Enumera lo que responde este mapa concreto, teniendo en cuenta la versión del mapa, el tipo de inserción y los conmutadores del autor.
El autor tiene el control. Cada grupo de comandos se puede desactivar por publicación, y solo los sitios que el autor indicó pueden controlar el mapa. Tenga previstos denied_capability y denied_origin.
Sin datos masivos. No hay exportData(). featureClick devuelve los campos que la capa muestra en su información sobre herramientas, y nada devuelve filas de forma masiva. Si su página necesita los datos, léalos de su propio origen y use selectByKey para relacionar ambos.
Errores con tipo. Los fallos son EmbedError con un code estable, en lugar de objetos de error cuyo message hay que analizar.
Tamaño. El SDK ocupa unos 17 KB sin dependencias, y hay una compilación para etiqueta script destinada a páginas que no pueden usar un empaquetador.