¿Qué necesitamos para empezar?

Los requisitos son pocos pero insalvables:

  • Un servidor web con tu propio dominio. Si tienes un blog o cualquier espacio web por limitado que sea te servirá sin importar el lenguaje de programación que use
  • Los archivos básicos de BootBoard (que puedes decargar más adelante)
  • Una cuenta de Google que tenga acceso a al menos una cuenta de Google Analytics
  • Un API Client ID para esta cuenta de google...

¿Cómo creo mi API Client ID?

El Id de cliente de las APIs de Google es esencial para poder realizar conexiones con Javascript a Google Analytics. Este ID le permite a Google saber bajo que desarrollo se están conectando los usuarios

Para crear el tuyo debes seguir el siguiente proceso:

  1. Date de alta en la Google APIs Console, el centro de control de las APIs de Google, con tu cuenta de Google.
  2. Te pedirá que crees un proyecto, le damos a crear proyecto y aceptamos los términos del servicio
  3. En el listado de APIs escogeremos la "Analytics API" que encontraremos bajo la categoría "Advirtising APIs". Tambien podemos localizala escribiendo "analytics" en el buscador superior
  4. Al entrar veremos un botón azul que nos permite conectar la API "Enable Api". Lo presionamos y así google ya sabe que tiene que aceptar conexiones a analytics con nuestra cuenta
  5. Sin salir de la API de Analytics, seleccionarmeos Quotas, le daremos al icono de lapiz para editar y pasaremos el valor de peticiones por segundo a 10 (inicialmente está a 1)
  6. En el menú de la izquierda vamos a "APIs & Auth" > "Consent Screen" y rellenamos como minimo el valor de "Produc Name". Podemos ponerle por ejemplo el nombre genérico de "Dashboard".
  7. En el menú de la izquierda vamos ahora a "APIs & Auth" > "Credentials".
  8. Seleccionamos "Create new Client Id" dentro de la sección "OAuth", no confundir con las Keys de Public API Access que para esto no nos sirven
  9. Seleccionamos como tipo de aplicación "Web Application" que es la conexión para Apps Javascript
  10. Indicamos nuestro dominio en "Authorized Javascript origins" sin usar comodines (*) ni directorios (el dominio puro). Por ejemplo: http://www.midominio.com Si nuestro dashboard se va a visitar desde más de un dominio podemos ir añadiendo uno por línea.
  11. Clicamos en Generar nuevo "Client Id" y veremos como ya tenemos a la derecha de la pantalla información sobre nuestra conexión.
  12. Apuntamos el valor de "Client ID" es el único que nos interesa, ni el Email, ni el secreto ni el resto de valores vamos a necesitarlos

Y ya está, ya tenemos CLient ID para nuestros dashboards.


Descargar e instalar BootBoard

Puedes descargar un archivo ZIP con los archivos necesarios

Se trata de solo 2 archivos:

  • index.html es una base html donde puedes empezar a montar tu dashboard.
  • bootboard.0.2.min.js el el codigo javascript que hace la magia y que no hace falta ni que entres a mirar ;)
  • (opcional) O si realmente quieres mirarlo mejor bajate bootboard.dev.js que es le mismo código pero mucho más legible que el .min

Una vez descargados estos dos ficheros, debes descomprimirlos y subirlos a cualquier carpeta de tu servidor, dentro del dominio que indicaste al crear tu Client ID en la Google APIs Console (si el dominio no coincide no funcionará)

Por último debes buscar en el HTML del archivo index.html la declaración de la variable "GOOGLE_API_CLIENT_ID" y cambiarla por el valor de tu Client ID que copiaste de la Google APIs Console

Ahora ya puedes cargar la URL donde hayas subido tu dashboard y disfrutar de la magia :)


Adaptando el dashboard a tus necesidades

El Dashboard es un HTML que bootboard.js interpreta para saber que datos demandar y que gráficos imprimir.

De la estética se encargará Bootstrap por lo que es más que recomendable que consultes su documentación de "CSS" y "Components" para familizarizarte con el sitema de columnas y recursos de navegación que trae.

Verás que el dashboard de ejemplo usa los estilos de Bootstrap exactos y no inventa nada nuevo. Eso no significa que tu no puedas añadir tu propio css o que no puedas cargar alguno de los Themes de Bootstrap que hay por internet.

Otro tema son widgets o gráficos del dashboard que si que hay que aprender a manejar y para los que no encontrarás documentación fuera de estas páginas.

Aquí te dejamos algunas anotaciones para que empieces a entenderlos:


Configurando los gráficos de tu dashboard

Cada gráfico de Bootboard es un <div/> en tu html que incluye en sus atributos la información necesaria para poder saber que datos mostrar y con que gráfica.


Definiendo un gráfico

Cualquier elemento de tu HTML se transformará en un gráfico siempre que cumpla con estos requisitos:

  • Esté dentro del contenedor con id "dashboard"
  • Tenga la clase "ga-chart"
  • Disponga de los atributos data adecuados para formular la llamada a analytics

Cómo se definen las fechas

Todos los valores de fechas permiten hasta 4 formas distintas por las que escribirlas

  • Fecha directa: Con el formato YYYY-MM-DD siendo por ejemplo 1979-07-02 el 2 de Julio de 1979
  • Fecha literal: Con un formato muy especifico (el soportado por la API de google analytics) se permite escribir de forma literal fechas relativas a la actual. Por ejemplo "30daysAgo".
  • Fecha relativa: Un sistema propio que permite escribir fechas relativas (a la actual o a otra fecha) y que tiene el siguiente formato (±Y)-(±M)-(±D) permitiendo sumar o restar dias, meses o años a la fecha de referencia. Por ejemplo: (-1)-(+0)-(-5) Daria como fecha el resultado de restar un año y 5 dias a la fecha actual.
  • Mix de fechas directas y relativas: Tambien se permite mezclar fechas directas con relativas. Por ejemplo (-1)-01-01 sería el 1 de enero del año anterior al actual y (+0)-(+0)-01 el día 1 del mes actual.

La mayor parte de las definiciones de fechas permitirán cualquiera de los 4 métodos, sin embargo sobretodo en campos de comparaciones de fechas las fechas directas y literales si bien podrán usarse carecerán de setido


Atributos permitidos en un gráfico


Class="xxxxxx-height"

Por defecto todos los gráficos tienen la misma altura y sacan el ancho del gráfico del ancho del DIV donde se han incluido.

Para ocasiones especiales se permite alterar esta altura añadiendo esas clases al div ga-chart.

  • xsmall-height: tendrá una altura de 75px
  • small-height: tendrá una altura de 150px
  • Los gráficos normales (sin clase especial) tendrán una altura de 300px
  • big-height: tendrá una altura de 450px

Title

El atributo title se hereda por el gráfico y pasa a ser el título de este.

Si se desea que no exista titulo debe definirse vacio: title=""


Atributos Data en gráficos normales

Los atributos data son las opciones de consulta y visualización del gráfico. Deben especificarse los suficientes para que la consulta pueda realizarse y el gráfico imprimirse

  • data-type= Indica el tipo de gráfico a crear. Por el momento se permiten los tipos: pie, line, area, column, bar, table, geo, metric y socialcount
  • data-dimensions= Las dimensiones afectadas. De usar más de una se separan por comas. La mayoría de gráficos solo aceptan 1 dimensión aunque algunos pueden aceptar 2
  • data-metrics= Las métricas a extraer. De usar más de una se separan por comas. No pueden usarse 2 dimensiones a la vez que dos métricas en los gráficos.
  • data-start-date= Fecha de inicio de la consulta. Puede estar en formato YYYY-MM-DD o en composiciones tipo 30daysAgo,1weekAgo,yesterday,etc.
  • data-end-date= Fecha de inicio de la consulta. Puede estar en formato YYYY-MM-DD o en composiciones tipo 30daysAgo,1weekAgo,yesterday,etc.
  • data-filter= Fitro a aplicar a la consulta.
  • data-segment= Segmento Dinamico (no es necesario usar "dynamic::") que aplicar a la consulta.
  • data-sort= El orden de aparición de los elementos, por defecto aparecerán según la primera métrica en orden descendente salvo en "area" y "line" donde se ordenaran por la primera dimension de forma ascendente
  • data-colors= Lista de colores web que aplicar al gráfico, separados por comas
  • data-maxvalues= Maximo numero de valores a mostrar, en caso de superarlo aparecerá el valor "others" sumando todos los que falten.
  • data-stacked= En gráficos con 2 dimensiones puede usarse stacked (normal o percent) para mostrar los datos anidados en gráficos de tendencia, barras o columna

Templates y Comparaciones en gráficos tipo "metric"

Los gráficos tipo métric (cajas con indicadores sueltos) tienen algunas opciones extra que los hacen especialmente útiles.

Comparaciones: Las comparaciones permiten no realizar solo una única extraccion de datos sino 2 para un solo recuadro. Eso permite diponer de 2 valores y lo que es mejor de distintos indicadores que comparan el primero con el segundo de ellos

Las comparaciones se definen con campos "data" opcionales que redefinen la consulta lanzada sobre analytics para el segundo dato extraido. Ninguno de los campos es obligatorio auqnue esta claro que si no variamos ninguno de los campos ambas consultas sería iguales

  • data-compared-metric= Permite cambiar la métrica consultada para la consulta secundaria
  • data-compared-date= Permite alterar la fecha de la consulta principal indicando fechas relativas tipo (+0)-(-1)-(+0) >> Resta un mes a las fechas indicadas en la consulta principal
  • data-compared-segemnt= Permite cambiar el segmento consultado para la consulta secundaria
  • data-compared-filter= Permite cambiar el filtro consultado para la consulta secundaria
  • data-compared-invertcolors= Si se define positivamente (yes,1,etc.) los colores de los indicadores de comparación se invierten marcando como flecha roja las subidas y flecha verde las bajadas

Templates Para definir como aparecen los datos en estos graficos se usan dos atributos:

  • title= representa el atributo de title (como en cualquier otro gráfico) pero en este caso es un template y el titulo gráficamente queda bajo el valor
  • data-template= representa al template del valor a mostrar

En los valores de template puede escribirse el HTML que se desee y se mostrará tal cual en el gráfico. En este además se reemplazarán ciertas palabras clave por los valores de las consultas.

  • {data} se reemplazará con el dato de la consulta principal
  • {compared} se reemplazará con el dato de la consulta de comparación
  • {ratio} se reemplazará con el ratio que representa la consulta principal sobre la de comparación
  • {percent} se reemplazará con el porecentaje que representa la consulta principal sobre la de comparación
  • {ratiochange} se reemplazará con el ratio de diferencia entre la consulta principal y la de comparación
  • {percentchange} se reemplazará con el porcentaje de diferencia entre la consulta principal y la de comparación
  • {diff} se reemplazará con la resta directa entre los valores de la consulta principal y la de comparación

También puedes usar iconos en los valores de template. O bien los tuyos propios o los glyphicons que vienen ya incorporados por bootstrap. Verás que en las demos ofrecidas se usan estos iconos junto a las métricas para hacerlos más vistosos


Métricas especiales para gráficos tipo "meric"

Los gráficos tipo métric admiten algunas métricas especiales que hacen que los datos se saquen de forma distinta.
  • countrows Espera que se haya definido tambien el campo "data-dimensions". Al usarse lo que se mostrará es el total de resultados aportados por la consulta en lugar de un valor de métrica normal de GA

Gráficos con multiples consultas

Tambien se permite crear gráficos de multiples consultas en las que cada valor mostrado sea el resultado de aplicar la misma consulta pero con un segmento distinto.

Estos gráficos son muy utiles para realizar adaptaciones a medida de la información a tus necesidades

Para usar estos gráficos es precino eliminar el campo "data-metrics" y sustiturlo por una serie de valores que contemplen cada consulta realizada

  • data-nameX= Nombre que tendrá este valor en el gráfico
  • data-metricX= Métrica a extraer para este valor
  • data-segmentX= Segmento dinámico que se aplicará a la consulta para poder sacar este valor

Donde X es un numero del 1 al 10 que debe variarse en cada valor a extraer

Problemas y errores conocidos

1. Los gráficos de 2 dimensiones o de multiples consultas no cargan si no hay grafico más simple cargado en el dashboard

Para ahorrar recursos de momento todo el sistema se basa en la Embed API de analytics. Esta api no carga las librerias de gráficos hasta que no recibe alguna petición que se lo demande. Dado que los gráficos de 2 dimensiones y los de multiples consultas no se lanzan con la Embed API si intentamos lanzarlos en solitario pueden no cargarse nunca las librerías internas de datos

El problema se soluciona añadiendo al dashboard al menos 1 gráfico siemple (una sola dimensión) que use alguna de las gráficas de Google Charts (Pie, line, area, column o bar)

2. Los gráficos de multiples queries fallan cuando se una de las queries no devuelve datos para todas las dimensiones

Este es un problema que sucede poco y que debería solucionarse en futuras versiones. Los gráficos de multiples consultas extraen cada consulta y luego las cruzan para poder construir gráficos de dos dimensiones (1 dimension de consultas a medida y otra la demandada a GA). Cuando en una de estas consultas para algún valor de dimensión no existen datos, es posible que el gráfico se corrompa