De Programacion

Incorporación de un componente de análisis interactivo con Cumul.io y cualquier marco web

En este artículo, explicamos cómo construir una capa de visualización de datos integrada e interactiva en una aplicación con Cumul.io. Para hacerlo, hemos creado una aplicación de demostración que visualiza los análisis de las listas de reproducción de Spotify. Usamos Cumul.io como nuestro panel interactivo, ya que hace que la integración sea muy fácil y proporciona funciones que permiten la interacción entre el panel y las aplicaciones (es decir, eventos personalizados). La aplicación es una aplicación web JavaScript simple con un servidor Node.js, aunque, si lo desea, puede lograr lo mismo con Angular, React y React Native mientras usa los paneles de Cumul.io también.

Aquí, creamos paneles que muestran datos del conjunto de datos de Kaggle Spotify 1921–2020, más de 160 mil pistas y también datos a través de la API web de Spotify cuando un usuario inicia sesión. Hemos creado paneles para obtener información sobre las características de las listas de reproducción y las canciones. Hemos agregado algunos eventos personalizados de Cumul.io que permitirán a cualquier usuario final que visite estos paneles seleccionar canciones de un gráfico y agregarlas a una de sus propias listas de reproducción de Spotify. También pueden seleccionar una canción para mostrar más información sobre ella y reproducirla desde la aplicación. El código de la aplicación completa también está disponible públicamente en un repositorio abierto.

Aquí hay un adelanto de cómo se ve el resultado final de la versión completa:

¿Qué son los eventos personalizados de Cumul.io y sus capacidades?

En pocas palabras, los eventos personalizados de Cumul.io son una forma de activar eventos desde un panel, para usarlos en la aplicación en la que está integrado el panel. Puede agregar eventos personalizados en gráficos seleccionados en un panel y hacer que la aplicación los escuche. eventos.

¿Por qué? Lo bueno de esta herramienta es cómo le permite reutilizar datos de un panel de análisis, una herramienta de BI, dentro de la aplicación en la que está integrada. Le brinda la libertad de definir acciones basadas en datos, que se pueden activar directamente desde un panel integrado, mientras mantiene el panel y la capacidad de análisis como una entidad completamente separada de la aplicación, que se puede administrar por separado.

Qué contienen: los eventos personalizados de Cumul.io se adjuntan a gráficos en lugar de paneles de control en su conjunto. Entonces, la información que tiene un evento se limita a la información que tiene un gráfico.

Un evento es simplemente un objeto JSON. Este objeto contendrá campos como el ID del panel que lo activó, el nombre del evento y una serie de otros campos según el tipo de gráfico desde el que se activó el evento. Por ejemplo, si el evento se activó desde un diagrama de dispersión, recibirá los valores de los ejes xey del punto desde el que se activó. Por otro lado, si se activa desde una tabla, recibiría valores de columna, por ejemplo. Vea ejemplos de cómo se verán estos eventos en diferentes gráficos:

// 'Add to Playlist' custom event from a row in a table{ "type":"customEvent", "dashboard":"xxxx", "name":"xxxx", "object":"xxxx", "data":{   "language":"en",   "columns":[     {"id":"Ensueno","value":"Ensueno","label":"Name"},      {"id":"Vibrasphere","value":"Vibrasphere","label":"Artist"},      {"value":0.406,"formattedValue":"0.41","label":"Danceability"},      {"value":0.495,"formattedValue":"0.49","label":"Energy"},      {"value":180.05,"formattedValue":"180.05","label":"Tempo (bpm)"},      {"value":0.568,"formattedValue":"0.5680","label":"Accousticness"},      {"id":"2007-01-01T00:00:00.000Z","value":"2007","label":"Release Date (Yr)"},   ],   "event":"add_to_playlist" }}
//'Song Info' custom event from a point in a scatter plot{ "type":"customEvent", "dashboard":"xxxx", "name":"xxxx", "object":"xxxx", "data":{   "language":"en",   "x-axis":{"id":0.601,"value":"0.601","label":"Danceability"},   "y-axis":{"id":0.532,"value":"0.532","label":"Energy"},   "name":{"id":"xxxx","value":"xxx","label":"Name"},   "event":"song_info"  }}

Las posibilidades con esta funcionalidad son prácticamente ilimitadas. Por supuesto, dependiendo de lo que quieras hacer, es posible que tengas que escribir un par de líneas más de código, ¡pero es indiscutiblemente una herramienta bastante poderosa!

El tablero

En realidad, aquí no repasaremos el proceso de creación del panel y nos centraremos en la parte de interactividad una vez que esté integrado en la aplicación. Los paneles integrados en este tutorial ya se crearon y tienen eventos personalizados habilitados. Por supuesto, puedes crear los tuyos propios e integrarlos en lugar del que hemos creado previamente (puedes crear una cuenta con una prueba gratuita). Pero antes, algo de información general sobre los paneles de Cumul.io;

Cumul.io le ofrece una forma de crear paneles desde la plataforma o mediante su API. En cualquier caso, los paneles estarán disponibles dentro de la plataforma, desacoplados de la aplicación en la que desea integrarlos, por lo que se pueden mantener de forma completamente independiente.

En su página de destino verá sus paneles y podrá crear uno nuevo:

Puede abrir uno y arrastrar y soltar cualquier gráfico que desee:

Puede conectar datos que luego puede arrastrar y soltar en esos gráficos:

Y esos datos pueden ser una de varias cosas. Como una base de datos preexistente que puede conectar a Cumul.io, un conjunto de datos de un almacén de datos que utiliza, un complemento personalizado, etc.

Habilitar eventos personalizados

Ya hemos habilitado estos eventos personalizados para el diagrama de dispersión y la tabla en el panel utilizado en esta demostración, que integraremos en la siguiente sección. Si deseas seguir este paso, ¡siéntase libre de crear sus propios paneles también!

Lo primero que debe hacer será agregar eventos personalizados a un gráfico. Para hacer esto, primero seleccione un gráfico en su panel al que le gustaría agregar un evento. En la configuración del gráfico, seleccione Interactividad y active Eventos personalizados:

Para agregar un evento, haga clic en editar y defina su nombre y etiqueta del evento. El nombre del evento es lo que recibirá su aplicación y la etiqueta es la que aparecerá en su panel. En nuestro caso, hemos agregado 2 eventos; 'Agregar a la lista de reproducción' e 'Información de la canción':

Esta es toda la configuración que necesita para que su panel active un evento a nivel de gráfico. Antes de salir del editor, necesitará su ID del panel para integrarlo más adelante. Puede encontrar esto en la pestaña Configuración de su panel de control. El resto del trabajo queda en el nivel de aplicación. Aquí será donde definimos lo que realmente queremos hacer una vez que recibamos cualquiera de estos eventos.

Puntos para llevar

  1. Los eventos funcionan a nivel de gráfico e incluirán información dentro de los límites de la información del gráfico.
  2. Para agregar un evento, vaya a la configuración del gráfico en el gráfico al que desea agregarlo.
  3. Definir nombre y etiqueta del evento. ¡Y tu estas listo!
  4. (No olvide tomar nota del ID del panel para la integración)

Usando eventos personalizados en tu propia plataforma

Ahora que ha agregado algunos eventos al panel, el siguiente paso es usarlos. El punto clave aquí es que, una vez que hace clic en un evento en su panel, su aplicación que integra el panel recibe un evento. La API de integración proporciona una función para escuchar estos eventos y luego depende de usted definir qué hacer con ellos. Para obtener más información sobre la API y ejemplos de código para su SDK, también puede consultar los documentos para desarrolladores relevantes.

Para esta sección, también proporcionamos un repositorio de GitHub abierto (separado del repositorio de la aplicación principal) que puede usar como proyecto inicial para agregar eventos personalizados.

El repositorio cumulio-spotify-datatalks está estructurado para que pueda realizar el pago en el compromiso llamado esqueleto para comenzar desde el principio. Todas las siguientes confirmaciones representarán un paso que recorreremos aquí. Es una versión reducida de la aplicación completa, que se centra en las partes principales de la aplicación que demuestran eventos personalizados. Me saltaré algunos pasos, como las llamadas a la API de Spotify que se encuentran en src/spotify.js, para limitar este tutorial al tema de "agregar y usar eventos personalizados".

Información útil para los siguientes pasos.

  • Puede utilizar el repositorio cumulio-spotify-datatalks y realizar el pago en el compromiso 'esqueleto' como punto de partida.
  • Todos los cambios y adiciones de código se realizarán en formato src/app.js.
  • Las dependencias y las instrucciones para ejecutar se encuentran al final de esta publicación.

Echemos un vistazo a lo que sucede en nuestro caso. Habíamos creado dos eventos; add_to_playlisty song_info. Queremos que los visitantes de nuestro panel puedan agregar una canción a su propia lista de reproducción de su elección en su propia cuenta de Spotify. Para ello, seguimos los siguientes pasos:

  1. Integre el panel con su aplicación
  2. Escuche los eventos entrantes

Integre el panel con su aplicación

Primero, necesitamos agregar un panel a nuestra aplicación. Aquí usamos el panel de lista de reproducción de Cumul.io Spotify como panel principal y el panel de información de la canción como panel de detalle (lo que significa que creamos un nuevo panel dentro del principal que aparece cuando activamos un evento). Si ha verificado la confirmación llamada esqueleto y npm run start, la aplicación actualmente debería abrir una pestaña vacía de 'Favoritos de Cumul.io', con un botón de Iniciar sesión en la parte superior derecha. Para obtener instrucciones sobre cómo ejecutar localmente el proyecto, vaya al final del artículo:

Para integrar un panel, necesitaremos utilizar la Cumulio.addDashboard()función. Esta función espera un objeto con opciones del panel. Esto es lo que hacemos para agregar el panel:

En src/app.js, creamos un objeto que almacena los ID del panel principal y el panel de detalles que muestra información de la canción junto a un dashboardOptionsobjeto:

// create dashboards object with the dashboard ids and dashboardOptions object// !!!change these IDs if you want to use your own dashboards!!!const dashboards = {  playlist: 'f3555bce-a874-4924-8d08-136169855807',   songInfo: 'e92c869c-2a94-406f-b18f-d691fd627d34',};const dashboardOptions = {  dashboardId: dashboards.playlist,  container: '#dashboard-container',  loader: {    background: '#111b31',    spinnerColor: '#f44069',    spinnerBackground: '#0d1425',    fontColor: '#ffffff'  }};

Creamos una loadDashboard()función que llama Cumulio.addDashboard(). Esta función recibe opcionalmente un contenedor y modifica el dashboardOptionsobjeto antes de agregar el panel a la aplicación.

// create a loadDashboard() function that expects a dashboard ID and containerconst loadDashboard = (id, container) = {  dashboardOptions.dashboardId = id;  dashboardOptions.container = container || '#dashboard-container';    Cumulio.addDashboard(dashboardOptions);};

Finalmente, usamos esta función para agregar nuestro panel de listas de reproducción cuando cargamos la pestaña Favoritos de Cumul.io:

export const openPageCumulioFavorites = async () = {  ui.openPage('Cumul.io playlist visualized', 'cumulio-playlist-viz');  /**************** INTEGRATE DASHBOARD ****************/  loadDashboard(dashboards.playlist);};

En este punto, hemos integrado el panel de la lista de reproducción y cuando hacemos clic en un punto en el diagrama de dispersión de Energía/Bailabilidad por canción, obtenemos dos opciones con los eventos personalizados que agregamos anteriormente. Sin embargo, todavía no estamos haciendo nada con ellos.

Escuche los eventos entrantes

Ahora que hemos integrado el panel, podemos decirle a nuestra aplicación que haga cosas cuando reciba un evento. Las dos listas que tienen los eventos "Agregar a lista de reproducción" e "Información de la canción" aquí son:

Primero, necesitamos configurar nuestro código para escuchar los eventos entrantes. Para hacerlo, necesitamos usar la Cumulio.onCustomEvent()función. Aquí, elegimos envolver esta función en una listenToEvents()función que se puede llamar cuando cargamos la pestaña Favoritos de Cumul.io. Luego usamos declaraciones if para verificar qué evento hemos recibido:

const listenToEvents = () = {  Cumulio.onCustomEvent((event) = {    if (event.data.event === 'add_to_playlist'){      //DO SOMETHING    }    else if (event.data.event === 'song_info'){      //DO SOMETHING    }  });};

Este es el punto después del cual las cosas dependen de sus necesidades y creatividad. Por ejemplo, podría simplemente imprimir una línea en su consola o diseñar su propio comportamiento en torno a los datos que reciba del evento. O también puede usar algunas de las funciones auxiliares que hemos creado que mostrarán un selector de lista de reproducción para agregar una canción a una lista de reproducción e integrar el panel de información de la canción. Así es como lo hicimos;

Agregar canción a la lista de reproducción

Aquí, haremos uso de la addToPlaylistSelector()función en src/ui.js. Esta función espera un nombre de canción y una identificación, y mostrará una ventana con todas las listas de reproducción disponibles del usuario que inició sesión. Luego publicará una solicitud de API de Spotify para agregar la canción a la lista de reproducción seleccionada. Como la API web de Spotify requiere el ID de una canción para poder agregarla, hemos creado un Name IDcampo derivado para usarlo en el diagrama de dispersión.

Un evento de ejemplo que recibamos add_to_playlistincluirá lo siguiente para el diagrama de dispersión:

"name":{"id":"So Far To Goid=3R8CATui5dGU42Ddbc2ixE","value":"So Far To Goid=3R8CATui5dGU42Ddbc2ixE","label":"Name  ID"}

Y estas columnas para la tabla:

"columns":[ {"id":"Weapon Of Choice (feat. Bootsy Collins) - Remastered Version","value":"Weapon Of Choice (feat. Bootsy Collins) - Remastered Version","label":"Name"}, {"id":"Fatboy Slim","value":"Fatboy Slim","label":"Artist"},   // ... {"id":"3qs3aHNUcqFGv7jMYJJCYa","value":"3qs3aHNUcqFGv7jMYJJCYa","label":"ID"}]

Extraemos el nombre y el ID de la canción del evento a través de la getSong()función, luego llamamos a la ui.addToPlaylistSelector()función:

/*********** LISTEN TO CUSTOM EVENTS AND ADD EXTRAS ************/const getSong = (event) = {  let songName;  let songArtist;  let songId;  if (event.data.columns === undefined) {    songName = event.data.name.id.split('id=')[0];    songId = event.data.name.id.split('id=')[1];  }  else {    songName = event.data.columns[0].value;    songArtist = event.data.columns[1].value;    songId = event.data.columns[event.data.columns.length - 1].value;  }  return {id: songId, name: songName, artist: songArtist};};const listenToEvents = () = {  Cumulio.onCustomEvent(async (event) = {    const song = getSong(event);    console.log(JSON.stringify(event));    if (event.data.event === 'add_to_playlist'){      await ui.addToPlaylistSelector(song.name, song.id);    }    else if (event.data.event === 'song_info'){      //DO SOMETHING    }  });};

Ahora, el evento 'Agregar a la lista de reproducción' mostrará una ventana con las listas de reproducción disponibles a las que un usuario que haya iniciado sesión puede agregar la canción:

Mostrar más información de la canción

Lo último que queremos hacer es hacer que el evento 'Información de la canción' muestre otro panel cuando se haga clic en él. Mostrará más información sobre la canción seleccionada e incluirá una opción para reproducir la canción. También es el paso en el que profundizamos en algunos casos de uso más complicados de la API que pueden necesitar algunos conocimientos previos. Específicamente, utilizamos filtros parametrizables. La idea es crear un parámetro en su panel, cuyo valor se pueda definir mientras se crea un token de autorización. Incluimos el parámetro como metadatos al crear un token de autorización.

Para este paso, hemos creado un songIdparámetro que se utiliza en un filtro en el panel de información de la canción:

Luego, creamos una getDashboardAuthorizationToken()función. Esto espera metadatos que luego publica en el /authorizationpunto final de nuestro servidor en server/server.js:

const getDashboardAuthorizationToken = async (metadata) = {  try {    const body = {};    if (metadata  typeof metadata === 'object') {      Object.keys(metadata).forEach(key = {        body[key] = metadata[key];      });    }    /*      Make the call to the backend API, using the platform user access credentials in the header      to retrieve a dashboard authorization token for this user    */    const response = await fetch('/authorization', {      method: 'post',      body: JSON.stringify(body),      headers: { 'Content-Type': 'application/json' }    });    // Fetch the JSON result with the Cumul.io Authorization key  token    const responseData = await response.json();    return responseData;  }  catch (e) {    return { error: 'Could not retrieve dashboard authorization token.' };  }};

Finalmente, usamos cargar el songInfopanel cuando song_infose activa el evento. Para hacer esto, creamos un nuevo token de autorización usando el ID de la canción:

const loadDashboard = (id, container, key, token) = {  dashboardOptions.dashboardId = id;  dashboardOptions.container = container || '#dashboard-container';    if (key  token) {    dashboardOptions.key = key;    dashboardOptions.token = token;  }  Cumulio.addDashboard(dashboardOptions);};

Realizamos algunas modificaciones a la loadDashboard()función para poder utilizar el nuevo token:

const loadDashboard = (id, container, key, token) =u003e {n  dashboardOptions.dashboardId = id;n  dashboardOptions.container = container || '#dashboard-container';  nn  if (key u0026u0026 token) {n    dashboardOptions.key = key;n    dashboardOptions.token = token;n  }nn  Cumulio.addDashboard(dashboardOptions);n};

Entonces llama al ui.displaySongInfo(). El resultado final es el siguiente:

const listenToEvents = () = {  Cumulio.onCustomEvent(async (event) = {    const song = getSong(event);    if (event.data.event === 'add_to_playlist'){      await ui.addToPlaylistSelector(song.name, song.id);    }    else if (event.data.event === 'song_info'){      const token = await getDashboardAuthorizationToken({ songId: [song.id] });      loadDashboard(dashboards.songInfo, '#song-info-dashboard', token.id, token.token);      await ui.displaySongInfo(song);    }  });};

¡Y voilá! ¡Hemos terminado! En esta demostración utilizamos muchas funciones auxiliares que no he analizado en detalle, pero puedes clonar el repositorio de demostración y jugar con ellas. Incluso puede ignorarlos y crear su propia funcionalidad en torno a los eventos personalizados.

Conclusión

Para cualquiera que desee tener una capa de visualización y análisis de datos integrada en su aplicación, Cumul.io proporciona una manera bastante fácil de lograrlo, como he intentado demostrar a lo largo de esta demostración. Los paneles siguen siendo entidades desacopladas de la aplicación que luego pueden administrarse por separado. Esto se convierte en una gran ventaja si, por ejemplo, está buscando análisis integrados dentro de un entorno empresarial y prefiere que los desarrolladores no regresen y jueguen con los paneles todo el tiempo.

Los eventos que puedes activar desde paneles y escuchar en sus aplicaciones host, por otro lado, te permiten definir implementaciones basadas en la información de esos paneles desacoplados. Esto puede ser cualquier cosa, desde reproducir una canción en nuestro caso hasta activar el envío de un correo electrónico específico. El mundo está a tu alcance en este sentido, tú decides qué hacer con los datos que tienes de tu capa de análisis. En otras palabras, puede reutilizar los datos de sus paneles, no tiene por qué quedarse ahí en su mundo de paneles y análisis.

Pasos para ejecutar este proyecto

Antes de empezar:

  • Necesitará una cuenta Cumul.io.
  • Deberá registrar su aplicación en el panel de desarrollador de Spotify.
  1. Clona el repositorio cumulio-spotify-datatalks connpm install
  2. Cree un .envarchivo en el directorio raíz y agregue lo siguiente desde sus cuentas de desarrollador de Cumul.io y Spotify:
  3. De Cumul.io:CUMULIO_API_KEY=xxx CUMULIO_API_TOKEN=xxx
  4. Desde Spotify:SPOTIFY_CLIENT_ID=xxx SPOTIFY_CLIENT_SECRET=xxx ACCESS_TOKEN=xxx REFRESH_TOKEN=xxxnpm run start
  5. En tu navegador, ve http://localhost:3000/e inicia sesión en tu cuenta de Spotify

Demo en vivoPrueba Cumul.io

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Subir