Automated Access to Google Analytics Data in Google Sheets

Nick Mihailovski, equipe da API Google Analytics – agosto de 2012

Este tutorial descreve como acessar as APIs de gerenciamento e de relatórios principais nas Planilhas Google usando Apps Script.


Introdução

Você pode usar a Google Analytics API e Script do Google Apps para acessar seus dados do Google Analytics nas Planilhas Google. Isso é eficiente porque, assim, você pode utilizar todos os ótimos recursos das Planilhas Google com seus dados de análise, como compartilhamento simples, colaboração, geração de gráficos e ferramentas de visualização.

Este tutorial orientará você pelo código necessário para acessar seus dados do Google Analytics nas Planilhas Google usando o Script do Google Apps.

Informações gerais

Este tutorial mostra como se registrar e configurar o ambiente do Apps Script para usar a API Google Analytics. Depois de configurado, o tutorial explica como recuperar um ID da vista (perfil) para o usuário autorizado usando a API Management. Depois, como usar o ID da vista (perfil) para consultar a API de relatórios principais e recuperar as 250 principais palavras-chave da pesquisa para dispositivos móveis do Google. Por fim, os resultados serão inseridos em uma Planilha Google. Depois de você ter os dados, o tutorial também discute como automatizar a recuperação de dados.

Quando cria um aplicativo usando a Google Analytics API e o Script do Google Apps, você geralmente passa pelas seguintes etapas:

  • Ativar as Google Analytics APIs em Planilhas Google
  • Trabalhar com as Google Analytics APIs

Vamos analisar cada etapa em detalhe.

Ativar a Google Analytics API no Script do Google Apps

Siga estas etapas para permitir o acesso aos seus dados do Google Analytics das Planilhas Google:

  1. Crie um arquivo das Planilhas Google. Dê a ele um nome interessante.
  2. Crie um novo Script do Google Apps.
    1. No menu, acesse Extensões > Apps Script.
    2. Se um menu aparecer, basta clicar em Projeto em branco.
    3. Dê um nome ao projeto. Verifique se o nome é interessante.

Quando tiver um novo script, você precisará ativar o serviço do Google Analytics.

  1. No editor de scripts, selecione Recursos > Serviços avançados do Google...
  2. Na caixa de diálogo que aparece, clique no botão liga/desliga ao lado da Google Analytics API.
  3. Na parte inferior da caixa de diálogo, clique no link para o Google Developers Console.
  4. No novo console, clique novamente na chave Ativar/Desativar ao lado da API Google Analytics. Depois de ativado, ele vai para o topo da página.
  5. Volte ao editor de script e clique em OK na caixa de diálogo.

Uma pequena caixa de diálogo amarela é exibida e informa que você adicionou um novo serviço das APIs do Google para seu script. Agora você está pronto para começar a escrever seu primeiro script.

Trabalhar com a Google Analytics API

O script neste tutorial consultará na Google Analytics API as 250 principais palavras-chave de pesquisa para dispositivos móveis do Google. Depois, exportará os resultados para Planilhas Google. Para isso, o script realizará as seguintes etapas:

  • Recuperar a primeira vista da propriedade (perfil) do usuário autorizado
  • Consultar dados na API de relatórios principais
  • Inserir dados em uma planilha

Adicione a função a seguir no projeto em branco.

function runDemo() {
  try {

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

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

No código acima, um bloco try...catch é usado para lidar com qualquer erro de API. Se ocorrer algum erro, a execução do programa será interrompida e o erro será exibido em uma caixa de mensagem. No bloco try, uma função é usada para executar cada uma das etapas que o script realizará. Agora, vamos adicionar o código para cada uma dessas funções.

Recuperar a primeira vista da propriedade (perfil) do usuário autorizado

No Google Analytics, cada relatório pertence a uma vista da propriedade (perfil) e é identificado por um ID da vista (perfil). Portanto, quando você especifica uma consulta para dados de relatório, também precisa especificar o ID da vista (perfil) da vista da qual você deseja recuperar dados.

A API de gerenciamento do Google Analytics fornece acesso a todas as entidades de contas, propriedades da Web e vista da propriedade (perfil) que pertencem a um usuário. Cada uma dessas entidades pertence a uma hierarquia, e você pode programaticamente transferir essa hierarquia para recuperar um ID da vista da propriedade (perfil) para o usuário autorizado.

A segunda função que criaremos será transferida pela hierarquia da API de gerenciamento e retornará a primeira vista da propriedade (perfil) do usuário. Copie e cole o código a seguir no seu projeto do Script do Google Apps:

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.');
  }
}

Nessa função, o conjunto de contas é consultado pela primeira vez usando o método Analytics.Management.Accounts.list. Se o usuário autorizado tem contas do Google Analytics, o ID da primeira conta é recuperado. Em seguida, o conjunto de propriedades da Web é consultado chamando o método Analytics.Management.Webproperties.list e transmitindo o método que o ID da conta recuperou na etapa anterior. Se existirem propriedades da Web, o conjunto de vistas (perfis) é consultado pela última vez usando o método Analytics.Management.Profiles.list. O ID da conta e os IDs da propriedade da Web são transmitidos como parâmetros para esse método. Se existirem vistas da propriedade (perfis), a primeira vista da propriedade (perfil) será retornada.

Se ocorrer algum erro de API ou se a resposta da API não tiver um resultado, é emitido um erro com uma mensagem que descreve que nenhum resultado foi encontrado. O bloco catch na função runDemo acima vai capturar esse erro e mostrar a mensagem ao usuário.

Depois do retorno do script, é possível consultar os dados do relatório.

Consultar dados na API de relatórios principais

Depois de você ter um ID da vista da propriedade (perfil), use a API de relatórios principais para consultar os dados do relatório do Google Analytics. Nesta seção, você aprenderá como consultar essa API usando o Apps Script.

Adicione o código a seguir ao seu projeto do 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');
}

A primeira parte do código cria uma consulta da API de relatórios principais usando o método Analytics.Data.Ga.get. Ele aceita diversos parâmetros que especificam o tipo de relatório a ser recuperado. Cada API de relatórios principais é composto por um conjunto de parâmetros obrigatórios e opcionais. Os parâmetros obrigatórios são transmitidos para o método como parâmetros, enquanto os parâmetros opcionais são transmitidos como um objeto.

O parâmetro table ID é obrigatório e formado ao combinar o prefixo ga: com o ID da vista (perfil). O código cria o ID da tabela usando o ID da vista (perfil) recuperado na etapa anterior. As datas de início e de término também são obrigatórias e especificam o período dos dados a serem recuperados. Elas são calculadas com base na data de hoje usando a função getLastNdays. Por fim, todos os parâmetros opcionais são transmitidos para a função usando o objeto optArgs.

Quando o método Analytics.Data.Ga.get é executado, uma solicitação é feita à API Core Reporting. Se ocorrer um erro, ele será capturado no bloco try...catch definido no método runDemo externo. Se a solicitação for bem-sucedida, os resultados são retornados.

Inserir dados em uma planilha

A etapa final do nosso script é a exportação dos resultados da API de relatórios principais para as Planilhas Google. O método outputToSpreadsheet faz isso. Adicione o seguinte código ao seu projeto:

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());
}

Essa função primeiro insere uma nova folha para a planilha ativa. Em seguida, insere todos os dados do cabeçalho e dos relatórios à folha. Para mais dicas sobre como inserir dados nas Planilhas Google, consulte Gravação de dados dos objetos JavaScript em uma planilha no tutorial Armazenamento de dados em planilhas.

Executar o script

Depois de adicionar todos os códigos ao projeto, você pode executá-lo.

  • Na barra de ferramentas do editor de script, no menu suspenso de seleção da função, escolha runDemo.
  • Em seguida, clique no botão play.

A primeira vez que executar essa função, será exibida uma caixa de pop-up na qual você precisa autorizar que o script acesse os dados da sua conta do Google Analytics.

Clique para autorizar.

Depois disso, será aberta uma nova página hospedada em google.com.br e você deverá conceder a esse script acesso aos seus dados. Ao clicar para permitir, você será redirecionado a uma página de confirmação. Neste ponto, o script será capaz de acessar seus dados do Google Analytics e poderá continuar a execução.

Depois que o script for executado, clique na janela com as Planilhas Google. Você verá todos os dados de palavras-chave retornados da API ou uma caixa de mensagem com uma mensagem de erro.

Automatizar o script

Neste ponto, você deve ter um script que consulta a API Google Analytics. Agora você pode automatizar esse script para recuperar novos dados todas as noites. O Apps Script facilita muito a automação usando o recurso triggers.

Para automatizar esse script, realize as etapas a seguir:

  • Na barra de ferramentas do editor de scripts, clique em Resources -> All your triggers....
  • Clique em Add a new trigger. A caixa de diálogo de acionadores é exibida.
  • Configure o gatilho para executar o método runDemo todas as noites.
    • O menu suspenso Run precisa ser definido como: runDemo
    • O menu suspenso Events precisa ser definido como: Time-driven, Day timer e Midnight to 1am.

Depois de configurado, esse script será executado todas as noites, fornecendo dados novos nas manhãs.

Você deseja ser notificado caso ocorram erros durante a noite. Com o Apps Script, você também pode enviar um e-mail alertando sobre a ocorrência de falhas. Para configurar isso, clique no link notifications na caixa de diálogo de acionadores. Uma nova caixa de diálogo é aberta e nela você pode configurar o e-mail para o qual os erros serão enviados.

Conclusão

Você registrou e autorizou o acesso ao seu script. Você consultou a API Management várias vezes para recuperar o ID de uma vista (perfil). Em seguida, você usou o ID da vista (perfil) para consultar a API Core Reporting, recuperar dados e exibi-los nas Planilhas Google.

Usando as técnicas descritas no tutorial, você poderá fazer análises mais complexas, obter informações melhores, criar painéis personalizados e reduzir bastante o tempo de geração de relatórios manuais.

Veja outros tutoriais interessantes que você pode achar úteis para aproveitar melhor a Google Analytics API e os Scripts do Google Apps: