Empezar

Descripción general

En este documento te guiaremos por un ejemplo completo de cómo usar la API de inserción. Una vez completado, tendrás una aplicación como esta.

Captura de pantalla del ejemplo explicado en esta guía
Captura de pantalla del ejemplo explicado en esta guía.

Crear un panel simple

Puedes tener en ejecución la aplicación de muestra en el servidor siguiendo estos dos pasos sencillos:

  1. Crear un nuevo ID de cliente
  2. Copiar y pegar el código

Después de que tengas esta aplicación activa, en la siguiente sección se explicará de forma detallada cómo encajan todas las piezas.

Crear un nuevo ID de cliente

La API de inserción gestiona prácticamente todo el proceso de autorización de forma automática al proporcionar un componente de inicio de sesión con un solo clic que utiliza el conocido flujo de OAuth 2.0. Para que este botón funcione en tu página, necesitarás un ID de cliente.

Si nunca has creado un ID de cliente, puedes hacerlo siguiendo estas instrucciones.

A medida que vayas siguiendo las instrucciones, es importante que no pases por alto estos dos pasos críticos:

  • Habilitar la API de Analytics
  • Configurar los orígenes correctos

Los orígenes controlan los dominios que pueden usar este código para autorizar a los usuarios. De este modo se impide que otros usuarios copien tu código y lo ejecuten en su sitio.

Por ejemplo, si tu sitio web está alojado en el dominio example.com, asegúrate de configurar el origen siguiente para tu ID de cliente http://example.com. Si quieres probar el código localmente, también deberás agregar el origen al servidor local, por ejemplo: http://localhost:8080.

Copiar y pegar el código

Una vez que tengas el ID de cliente con los orígenes correctos configurados puedes crear la demostración. Solo tienes que copiar el siguiente código en un archivo HTML en el servidor e incluir tu ID de cliente en el apartado donde se indica "Insert your client ID here".

<!DOCTYPE html>
<html>
<head>
  <title>Embed API Demo</title>
</head>
<body>

<!-- Step 1: Create the containing elements. -->

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

<!-- Step 2: Load the library. -->

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

<script>
gapi.analytics.ready(function() {

  // Step 3: Authorize the user.

  var CLIENT_ID = 'Insert your client ID here';

  gapi.analytics.auth.authorize({
    container: 'auth-button',
    clientid: CLIENT_ID,
  });

  // Step 4: Create the view selector.

  var viewSelector = new gapi.analytics.ViewSelector({
    container: 'view-selector'
  });

  // Step 5: Create the timeline chart.

  var timeline = new gapi.analytics.googleCharts.DataChart({
    reportType: 'ga',
    query: {
      'dimensions': 'ga:date',
      'metrics': 'ga:sessions',
      'start-date': '30daysAgo',
      'end-date': 'yesterday',
    },
    chart: {
      type: 'LINE',
      container: 'timeline'
    }
  });

  // Step 6: Hook up the components to work together.

  gapi.analytics.auth.on('success', function(response) {
    viewSelector.execute();
  });

  viewSelector.on('change', function(ids) {
    var newIds = {
      query: {
        ids: ids
      }
    }
    timeline.set(newIds).execute();
  });
});
</script>
</body>
</html>

Descripción del código

En esta sección se describe de forma detallada exactamente lo que hace el código proporcionado en la aplicación de muestra. Cuando entiendas cómo funciona, podrás crear una propia.

Paso 1: crear los contenedores de componentes

La mayoría de los componentes de la API de inserción se presentarán visualmente en la página. La forma de controlar dónde aparecen estos componentes es creando contenedores para ellos. En la aplicación de ejemplo tenemos un botón de autorización, un selector de vistas y un gráfico. Cada uno de estos componentes se representa en los siguientes elementos HTML:

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

Al crear un componente, se indica qué contenedor se usará por su atributo de ID, tal como se verá en los ejemplos siguientes.

Paso 2: cargar la biblioteca

La API de inserción se puede cargar con el siguiente fragmento:

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

Cuando la biblioteca está completamente cargada, se invocarán las devoluciones de llamada que se han enviado a gapi.analytics.ready.

<script>
gapi.analytics.ready(function() {
  // Put your application code here...
});
</script>

Paso 3: autorizar al usuario

La API de inserción gestiona prácticamente todo el proceso de autorización de forma automática al proporcionar un componente de inicio de sesión con un solo clic que utiliza el conocido flujo de OAuth 2.0. Para que este botón funcione en tu página, debes pasar una referencia de contenedor y el ID de cliente

gapi.analytics.auth.authorize({
  container: 'auth-button',
  clientid: CLIENT_ID,
});

De este modo se generará un botón dentro del elemento con el ID "auth-button", que se ocupará automáticamente del flujo de autorización.

Paso 4: crear el selector de vistas

El componente del selector de vistas se puede usar para obtener los ID de una determinada vista, para poder ejecutar un informe.

Para crear un selector de vistas, solo necesitas la referencia de contenedor que has creado en el paso 1.

var viewSelector = new gapi.analytics.ViewSelector({
  container: 'view-selector'
});

De esta forma se crea el componente del selector de vistas, pero todavía no se presenta en la página. Para ello, debes llamar a execute(), que se trata en el paso 6.

Paso 5: crear el gráfico temporal

La API de inserción te proporciona un componente de gráfico que es un gráfico de Google y un objeto de informe. De este modo se simplifica considerablemente el proceso para mostrar datos ya que el objeto de gráfico se ocupará de ejecutar los informes en segundo plano y se actualizará automáticamente con los resultados.

Para crear un componente de gráfico debes especificar los parámetros de consulta de la API así como las opciones de gráfico. En esas opciones hay una referencia al ID del contenedor que has creado en el paso 1.

var timeline = new gapi.analytics.googleCharts.DataChart({
  reportType: 'ga',
  query: {
    'dimensions': 'ga:date',
    'metrics': 'ga:sessions',
    'start-date': '30daysAgo',
    'end-date': 'yesterday',
  },
  chart: {
    type: 'LINE',
    container: 'timeline'
  }
});

Al igual que con el selector de vistas, se crea el componente de gráfico pero, para presentarlo en la página, es necesario llamar a execute(), que se explicará en el paso siguiente.

Paso 6: combinar los componentes para que funcionen juntos

Los componentes de la API de inserción envían eventos cuando se producen determinadas acciones, como la autorización correcta, la selección de una nueva vista o un gráfico totalmente procesado.

La aplicación de ejemplo de esta guía espera a que se procese el selector de vistas hasta después de que se haya producido la autorización, y actualiza el gráfico temporal siempre que se selecciona una nueva vista en el selector de vistas.

gapi.analytics.auth.on('success', function(response) {
  viewSelector.execute();
});

viewSelector.on('change', function(ids) {
  var newIds = {
    query: {
      ids: ids
    }
  }
  timeline.set(newIds).execute();
});

Para obtener una lista completa de todos los eventos que emiten los distintos componentes, consulta la referencia de la API.

Pasos siguientes

En esta guía te hemos presentado el proceso para crear una visualización básica con la API de inserción. Si quieres obtener más información, consulta la referencia de la API para ver todo lo que es posible hacer.