Acceso automatizado a datos de Google Analytics en Hojas de cálculo de Google

Nick Mihailovski, equipo de la API de Google Analytics, agosto de 2012

En este instructivo, se describe cómo acceder a las API de Management y Core Reporting dentro de Hojas de cálculo de Google mediante Apps Script.

Introducción

Puedes usar la API de Google Analytics y Google Apps Script para acceder a tus datos de Google Analytics desde Hojas de cálculo de Google. Esto es muy útil porque te permite usar todas las excelentes funciones de Hojas de cálculo de Google con tus datos de estadísticas, como herramientas fáciles de compartir, colaborar, crear gráficos y de visualización.

En este instructivo, se explica el código necesario para acceder a los datos de Google Analytics en Hojas de cálculo de Google con Google Apps Script.

Descripción general

En este instructivo, verás cómo registrarte y configurar el entorno de Apps Script para usar la API de Google Analytics. Una vez configurado, en el instructivo se explica cómo recuperar un ID de vista (perfil) para el usuario autorizado con la API de Management. Luego, cómo usar el ID de vista (perfil) para consultar la API de Core Reporting a fin de recuperar las 250 palabras clave de la búsqueda para dispositivos móviles principales de Google. Finalmente, los resultados se insertan en una hoja de cálculo de Google. Una vez que tienes datos, en el instructivo también se analiza cómo automatizar la recuperación de datos.

Por lo general, cuando compilas una aplicación con la API de Google Analytics y Apps Script, debes seguir estos pasos:

• Habilita las APIs de Google Analytics en Hojas de cálculo de Google
• Trabaja con las APIs de Google Analytics

Revisemos cada paso en detalle.

Habilitar la API de Google Analytics en Apps Script

Para habilitar el acceso a tus datos de Google Analytics desde Hojas de cálculo de Google, sigue estos pasos:

1. Crea un archivo de Hojas de cálculo de Google. Asígnale un nombre genial.
2. Crea una nueva secuencia de comandos de Apps Script.
   1. En el menú, ve a Extensiones > Apps Script.
   2. Si aparece un menú, haz clic en Blank Project.
   3. Asígnale un nombre al proyecto. Asegúrate de que tenga un nombre llamativo.

Una vez que tengas una secuencia de comandos nueva, deberás habilitar el servicio de Google Analytics.

1. En el editor de secuencia de comandos, selecciona Resources > Advanced Google services...
2. En el cuadro de diálogo que aparece, haz clic en el interruptor de activado/desactivado junto a la API de Google Analytics.
3. En la parte inferior del diálogo, haz clic en el vínculo de Google Developers Console.
4. En la nueva consola, vuelve a hacer clic en el interruptor de activación/desactivación junto a la API de Google Analytics. (Una vez habilitada, irá a la parte superior de la página).
5. Regresa al editor de secuencia de comandos y haz clic en OK en el cuadro de diálogo.

Aparecerá un pequeño cuadro de diálogo amarillo en la ventana emergente que indicará que agregaste correctamente un nuevo servicio de API de Google a tu secuencia de comandos. Ya está todo listo para comenzar a escribir tu primera secuencia de comandos.

Trabaja con la API de Google Analytics

Con la secuencia de comandos de este instructivo, se consultará la API de Google Analytics para obtener las 250 palabras clave de la búsqueda en dispositivos móviles de Google más populares y, luego, se mostrarán los resultados en Hojas de cálculo de Google. Para lograrlo, la secuencia de comandos seguirá estos pasos:

• Recuperar la primera vista (perfil) del usuario autorizado
• Consultar la API de Core Reporting para obtener datos
• Inserta datos en una hoja de cálculo.

Agrega la siguiente función al proyecto en blanco.

function runDemo() {
  try {

    var firstProfile = getFirstProfile();
    var results = getReportDataForProfile(firstProfile);
    outputToSpreadsheet(results);

  } catch(error) {
    Browser.msgBox(error.message);
  }
}

En el código anterior, se usa un bloque try...catch para controlar cualquier error de la API. Si se produce algún error, se detendrá la ejecución del programa y se mostrará el error en un cuadro de mensaje. En el bloque try, se usa una función para realizar cada uno de los pasos por los que pasará la secuencia de comandos. Ahora, agreguemos el código para cada una de estas funciones.

Recuperar la primera vista (perfil) del usuario autorizado

En Google Analytics, cada informe pertenece a una vista (perfil) y se identifica con un ID de vista (perfil). Por lo tanto, cuando especificas una consulta para los datos de informes, también debes especificar el ID de vista (perfil) de la vista (perfil) desde la que deseas recuperar datos.

La API de Google Analytics Management proporciona acceso a todas las cuentas, propiedades web y entidades de vista (perfil) que pertenecen a un usuario. Cada una de estas entidades pertenece a una jerarquía, y puedes recorrerla de manera programática para recuperar un ID de vista (perfil) para el usuario autorizado.

Nota: Obtén más información sobre cómo se relacionan estas entidades entre sí en el documento Descripción general de la API de Management.

La segunda función que escribiremos recorrerá la jerarquía de la API de Management y mostrará la primera vista (perfil) del usuario. Copia y pega el siguiente código en tu proyecto de Apps Script:

function getFirstProfile() {
  var accounts = Analytics.Management.Accounts.list();
  if (accounts.getItems()) {
    var firstAccountId = accounts.getItems()[0].getId();

    var webProperties = Analytics.Management.Webproperties.list(firstAccountId);
    if (webProperties.getItems()) {

      var firstWebPropertyId = webProperties.getItems()[0].getId();
      var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId);

      if (profiles.getItems()) {
        var firstProfile = profiles.getItems()[0];
        return firstProfile;

      } else {
        throw new Error('No views (profiles) found.');
      }
    } else {
      throw new Error('No webproperties found.');
    }
  } else {
    throw new Error('No accounts found.');
  }
}

En esta función, primero se consulta la colección Cuentas con el método Analytics.Management.Accounts.list. Si el usuario autorizado tiene cuentas de Google Analytics, se recupera el ID de la primera cuenta. A continuación, para consultar la colección de propiedades web, se llama al método Analytics.Management.Webproperties.list y se pasa el método que recupera el ID de la cuenta en el paso anterior. Si existen propiedades web, finalmente se consulta la colección de vistas (perfil) con el método Analytics.Management.Profiles.list. Este método incluye tanto el ID de la cuenta como los IDs de propiedad web como parámetros. Si existen vistas (perfiles), se muestra la primera vista (perfil).

Nota: El servicio de la API de Google Analytics debe estar habilitado para que todos los métodos Analytics.* funcionen correctamente.

Si en algún momento se produce un error de la API o si la respuesta de la API no contiene resultados, se mostrará un error con un mensaje que indica que no se encontraron resultados. El bloque catch de la función runDemo anterior detectará este error y, luego, imprimirá el mensaje para el usuario.

Después de que la secuencia de comandos muestra resultados, puede consultar los datos de informes.

Consultar la API de Core Reporting para obtener datos

Una vez que tengas un ID de vista (perfil), usa la API de Core Reporting para consultar los datos de informes de Google Analytics. En esta sección, aprenderás a consultar esta API con Apps Script.

Agrega el siguiente código a tu proyecto de Apps Script:

function getReportDataForProfile(firstProfile) {

  var profileId = firstProfile.getId();
  var tableId = 'ga:' + profileId;
  var startDate = getLastNdays(14);   // 2 weeks (a fortnight) ago.
  var endDate = getLastNdays(0);      // Today.

  var optArgs = {
    'dimensions': 'ga:keyword',              // Comma separated list of dimensions.
    'sort': '-ga:sessions,ga:keyword',       // Sort by sessions descending, then keyword.
    'segment': 'dynamic::ga:isMobile==Yes',  // Process only mobile traffic.
    'filters': 'ga:source==google',          // Display only google traffic.
    'start-index': '1',
    'max-results': '250'                     // Display the first 250 results.
  };

  // Make a request to the API.
  var results = Analytics.Data.Ga.get(
      tableId,                    // Table id (format ga:xxxxxx).
      startDate,                  // Start-date (format yyyy-MM-dd).
      endDate,                    // End-date (format yyyy-MM-dd).
      'ga:sessions,ga:pageviews', // Comma seperated list of metrics.
      optArgs);

  if (results.getRows()) {
    return results;

  } else {
    throw new Error('No views (profiles) found');
  }
}

function getLastNdays(nDaysAgo) {
  var today = new Date();
  var before = new Date();
  before.setDate(today.getDate() - nDaysAgo);
  return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd');
}

La primera parte del código crea una consulta de la API de Core Reporting con el método Analytics.Data.Ga.get. El método acepta un conjunto de parámetros que especifican el tipo de informe que se recuperará. Cada consulta de la API de Core Reporting consta de un conjunto de parámetros obligatorios y opcionales. Los parámetros obligatorios se pasan al método como parámetros, mientras que los parámetros opcionales se pasan como un objeto.

El parámetro table ID es obligatorio y se forma mediante la combinación del prefijo ga: con el ID de la vista (perfil). El código crea el ID de la tabla con el ID de vista (perfil) recuperado en el paso anterior. Las fechas de inicio y finalización también son obligatorias, y especifican el período de los datos que se recuperarán. Ambos se calculan con base en la fecha de hoy mediante la función getLastNdays. Por último, todos los parámetros opcionales se pasan a la función con el objeto optArgs.

Nota: Puedes encontrar una lista completa de todos los parámetros y sus definiciones en el documento de referencia de la API de Core Reporting. Además, puedes encontrar una lista completa de todas las dimensiones y métricas posibles en la referencia de Dimensiones y métricas.

Cuando se ejecuta el método Analytics.Data.Ga.get, se realiza una solicitud a la API de Core Reporting. Si se produce un error, se captura en el bloque try...catch definido en el método runDemo externo. Si la solicitud tuvo éxito, se mostrarán los resultados.

Cómo insertar datos en una hoja de cálculo

El último paso de nuestra secuencia de comandos es enviar los resultados de la API de Core Reporting a Hojas de cálculo de Google. El método outputToSpreadsheet hace esto. Agrega el siguiente código a tu proyecto:

function outputToSpreadsheet(results) {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();

  // Print the headers.
  var headerNames = [];
  for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
    headerNames.push(header.getName());
  }
  sheet.getRange(1, 1, 1, headerNames.length)
      .setValues([headerNames]);

  // Print the rows of data.
  sheet.getRange(2, 1, results.getRows().length, headerNames.length)
      .setValues(results.getRows());
}

Esta función primero inserta una hoja nueva en la hoja de cálculo activa. Luego, inserta todos los datos de informes y encabezados en la hoja. Si deseas obtener más sugerencias para insertar datos en Hojas de cálculo de Google, lee Escribe datos de objetos JavaScript en una hoja de cálculo en el instructivo Cómo almacenar datos en hojas de cálculo.

Ejecuta la secuencia de comandos

Una vez que hayas agregado todo el código al proyecto, podrás ejecutarlo.

• En la barra de herramientas del editor de secuencia de comandos, en el menú desplegable para seleccionar función, selecciona runDemo.
• Luego, haz clic en el botón play.

La primera vez que ejecutes esto, aparecerá un cuadro emergente en el que se te solicitará que autorices el acceso de esta secuencia de comandos a los datos de tu cuenta de Google Analytics.

Haz clic en Autorizar.

Una vez que hagas clic, se abrirá una nueva página alojada en google.com y se te pedirá que otorgues a esta secuencia de comandos acceso a tus datos. Una vez que hagas clic en Permitir, se te redireccionará a una página de confirmación. En este punto, la secuencia de comandos podrá acceder a tus datos de Google Analytics y podrá seguir ejecutándose.

Nota: Solo debes permitir que la secuencia de comandos acceda a tus datos de Google Analytics la primera vez que la ejecutes.

Cuando se ejecute la secuencia de comandos, haz clic en la ventana donde se encuentra Hojas de cálculo de Google. Deberías ver todos los datos de las palabras clave que muestra la API, o bien un cuadro de mensaje con un mensaje de error.

Automatizar la secuencia de comandos

En este punto, debes tener una secuencia de comandos que consulte a la API de Google Analytics. Es posible que ahora quieras automatizar esta secuencia de comandos para recuperar datos nuevos cada noche. Apps Script facilita mucho la automatización con la función triggers.

Para automatizar esta secuencia de comandos, sigue estos pasos:

• En la barra de herramientas del editor de secuencia de comandos, haz clic en Resources -> All your triggers....
• Haz clic en Add a new trigger. Aparecerá el cuadro de diálogo de activadores.
• Configura el activador para ejecutar el método runDemo todas las noches.
  • El menú desplegable Run se debe establecer en: runDemo
  • El menú desplegable Events debe configurarse como Time-driven, Day timer y Midnight to 1am.
  
  

  

Una vez configurada, esta secuencia de comandos se ejecutará todas las noches, lo que te brindará datos actualizados por la mañana.

Si se produce algún error durante la noche, recibirás una notificación. Apps Script también te permite enviar una alerta por correo electrónico si se produce algún error. Para configurar esto, en el cuadro de diálogo del activador, haz clic en el vínculo notifications. Aparecerá un nuevo cuadro de diálogo que te permitirá configurar a qué correo electrónico deseas que se envíen los errores.

Conclusión

te registraste y autorizaste el acceso a tu secuencia de comandos correctamente. Consultaste la API de Management varias veces para recuperar un ID de vista (perfil). Luego, usaste el ID de vista (perfil) para consultar la API de Core Reporting y recuperar datos y exportarlos a Hojas de cálculo de Google.

Usar las técnicas descritas en el instructivo te permitirá realizar análisis más complejos, obtener más estadísticas, compilar paneles personalizados y reducir el tiempo de ejecución de informes manuales.

Estos son algunos instructivos interesantes que pueden resultarte útiles para aprovechar al máximo la API de Google Analytics y Google Apps Script:

• Lee datos de hojas de cálculo : Te permite especificar tus consultas a las APIs en una hoja de cálculo en lugar de en JavaScript.
• Inserta gráficos desde hojas de cálculo en un sitio de Google : Para que puedas crear paneles en Google Sites con tus datos de Analytics.
• Menús personalizados: Permite que otros usuarios de tu empresa usen las secuencias de comandos que escribes con más facilidad.