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.
Visão geral
Este tutorial mostra como registrar e configurar o ambiente do Apps Script para usar a Google Analytics API. Depois de configurada, o tutorial explica como recuperar um ID de vista da propriedade (perfil) para o usuário autorizado usando a API Management. Em seguida, como usar o ID da vista (perfil) para consultar a API de relatórios principais e recuperar as 250 principais palavras-chave da rede de 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:
- Crie um arquivo das Planilhas Google. Dê a ele um nome interessante.
- Crie um novo Script do Google Apps.
- No menu, acesse Extensões > Apps Script.
- Se um menu aparecer, clique em Projeto em branco.
- Dê um nome ao projeto. Verifique se o nome é interessante.
Quando tiver um novo script, você precisará ativar o serviço do Google Analytics.
- No editor de scripts, selecione Recursos > Serviços avançados do Google...
- Na caixa de diálogo que aparece, clique no botão liga/desliga ao lado da Google Analytics API.
- Na parte inferior da caixa de diálogo, clique no link para o Google Developers Console.
- No novo console, clique novamente no botão liga/desliga ao lado da API Google Analytics. Depois de ativado, ele vai para o topo da página.
- Retorne 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 processar todos os erros 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 de vista da propriedade (perfil). Portanto, ao especificar uma consulta para dados de relatório, você também precisa especificar o ID da vista da propriedade (perfil) 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 primeiro, 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, a coleção de propriedades da Web é consultada 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 da propriedade (perfil) é 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 capturará esse erro e exibirá 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 pela combinação do prefixo ga:
ao 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 passados 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 script, 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
eMidnight to 1am
.
- O menu suspenso
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 gatilhos.
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 de gerenciamento várias vezes para recuperar o ID de uma vista da propriedade (perfil). Em seguida, você usou o ID da vista da propriedade (perfil) para consultar a API de relatórios principais, recuperar dados e enviá-los para as 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:
- Leitura de dados de planilhas: para você especificar suas consultas de API em uma planilha, em vez de JavaScript.
- Inserção de gráficos de planilhas em um site Google: para você criar painéis em sites Google com seus dados do Google Analytics.
- Menus personalizados: para que os outros usuários na sua empresa usem os scripts que você cria com mais facilidade.