Este documento explica como usar a API Multi-Channel Funnels Reporting para acessar os dados de funis multicanal.
Introdução
A API Multi-Channel Funnels Reporting fornece acesso aos dados tabulares nos relatórios padrão e personalizados dos funis multicanal. Para acessar os dados, crie uma consulta que especifica: a vista da propriedade (perfil), as datas de início e término, e as dimensões e métricas que compõem os cabeçalhos das colunas na tabela. Essa consulta é enviada para a API Multi-Channel Funnels Reporting, que retorna todos os dados na forma de uma tabela.
Se você for novo na API, leia a Visão geral da API Multi-Channel Funnels Reporting para uma introdução ao propósito dessa API e aos dados que ela fornece.
Antes de começar
Este guia usa a biblioteca de cliente Java para acessar a API de relatórios de funis multicanal. Cada biblioteca cliente fornece um único objeto de serviço do Google Analytics para chamar a API de relatórios de funis multicanal e acessar os dados. Se você não usa uma biblioteca cliente para acessar a API, leia o Guia de referência da API Multi-Channel Funnels Reporting.
Para criar o objeto de serviço "Analytics":
- Registre seu aplicativo no console de APIs do Google.
- Autorize o acesso aos dados do Google Analytics.
- Escreva o código para criar o objeto de serviço "Analytics".
Se você não tiver concluído essas etapas, pare e leia o Tutorial de introdução da API Google Analytics, que mostra as etapas iniciais da criação de um aplicativo da API Google Analytics. Depois de concluir o tutorial, continue a ler o guia a seguir.
Por exemplo, o código a seguir cria um objeto de serviço "Analytics" autorizado:
Java
Analytics analytics = initializeAnalytics();
Use o objeto de serviço analytics do Google Analytics para chamar a API de relatórios de funis multicanal.
Visão geral
Para usar a API Multi-Channel Funnels Reporting para recuperar dados, grave um aplicativo para:
- consultar a API de relatórios de funis multicanal;
- trabalhar com os resultados retornados da API.
Consultar a API Multi-Channel Funnels Reporting
Para solicitar dados da API Multi-Channel Funnels Reporting:
- Crie um objeto de consulta da API Multi-Channel Funnels Reporting.
- Use o objeto de consulta para solicitar os dados dos servidores de funis multicanal.
Criar uma consulta de API Multi-Channel Funnels Reporting
Para criar um objeto de consulta da API Multi-Channel Funnels Reporting, chame este método:
analytics.data.mcf.get() // analytics is the Analytics service object
O primeiro parâmetro fornecido para o método é um ID de tabela exclusivo na forma de ga:XXXX, em que XXXX é o ID de uma vista da propriedade (perfil) do Google Analytics que contém os dados solicitados.
Use o objeto de consulta para especificar parâmetros de consulta (por exemplo, setDimensions). Por exemplo:
Java
Get apiQuery = analytics.data().mcf()
.get(tableId,
"2012-01-01", // Start date
"2012-03-31", // End date
"mcf:totalConversions") // Metrics
.setDimensions("mcf:sourcePath")
.setSort("-mcf:totalConversions")
.setMaxResults(25);
Para ver uma lista de todos os parâmetros de consulta, consulte Resumo de parâmetros de consulta. Os parâmetros de métricas e dimensões permitem especificar quais dados dos funis multicanal recuperar. Para ver uma lista de todas as dimensões e métricas, consulte a Referência de dimensões e métricas.
Solicitação de dados da API Multi-Channel Funnels Reporting
Depois de criar o objeto de consulta, chame o método execute no objeto para solicitar dados dos servidores de funis multicanal. Exemplo:
Java
try {
apiQuery.execute();
// Success. Do something cool!
} catch (GoogleJsonResponseException e) {
// Catch API specific errors.
handleApiError(e);
} catch (IOException e) {
// Catch general parsing network errors.
e.printStackTrace();
}
Se você preferir acessar a resposta bruta da API, chame o método executeUnparsed() no objeto de consulta:
HttpResponse response = apiQuery.executeUnparsed();
Se a consulta for bem-sucedida, ela retornará os dados solicitados. Se ocorrer um erro, o método execute vai gerar uma exceção contendo um código de status e uma descrição do erro. O aplicativo
precisa capturar e processar a exceção.
Trabalhar com os resultados da API
Se a consulta da API Multi-Channel Funnels Reporting for bem-sucedida, ela retornará os dados do relatório e informações sobre os dados.
Dados do relatório de funis multicanal
A consulta retorna os seguintes dados de relatórios tabulares:
- Dados do cabeçalho da coluna
- Dados de linha
Dados do cabeçalho da coluna
A resposta da consulta tem um campo de cabeçalho de coluna que contém as informações
do cabeçalho da tabela. O campo é uma lista (ou uma matriz) de objetos ColumnHeaders, cada um contendo nome e tipo de coluna e de dados da coluna. A ordem das colunas são as de dimensões seguidas de colunas de métricas, na mesma ordem especificada na consulta original. Por exemplo, o método a seguir imprime os cabeçalhos das colunas:
Java
private static void printColumnHeaders(McfData mcfData) {
System.out.println("Column Headers:");
for (ColumnHeaders header : mcfData.getColumnHeaders()) {
System.out.println("Column Name: " + header.getName());
System.out.println("Column Type: " + header.getColumnType());
System.out.println("Column Data Type: " + header.getDataType());
}
}
Dados de linha
Os principais dados retornados da API são retornados como um List bidimensional de McfData.Rows. Cada McfData.Rows representa uma única célula, que é um valor primitivo do tipo String ou um valor de caminho de conversão do tipo McfData.Rows.ConversionPathValue. A ordem das células de uma linha é a mesma que os campos do objeto do cabeçalho da coluna descrito acima.
Como os dados em cada célula são retornados como uma string ou como um tipo de sequência de funis multicanal, o campo DataType em cada objeto de cabeçalho de coluna é particularmente útil para analisar valores em tipos apropriados.
Consulte o
guia de referência para ver todos os tipos de dados possíveis.
Por exemplo, o método a seguir imprime os cabeçalhos e as linhas da tabela:
Java
private static void printDataTable(McfData mcfData) {
System.out.println("Data Table:");
if (mcfData.getTotalResults() > 0) {
// Print the column names.
List<ColumnHeaders> headers = mcfData.getColumnHeaders();
for (ColumnHeaders header : headers) {
System.out.print(header.getName());
}
System.out.println();
// Print the rows of data.
for (List<McfData.Rows> row : mcfData.getRows()) {
for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
ColumnHeaders header = headers.get(columnIndex);
McfData.Rows cell = row.get(columnIndex);
if (header.getDataType().equals("MCF_SEQUENCE")) {
System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
} else {
System.out.print(cell.getPrimitiveValue());
}
}
System.out.println();
}
} else {
System.out.println("No rows found");
}
}
O exemplo a seguir mostra como analisar um objeto de tipo de sequência de funis multicanal e convertê-lo em uma string:
Java
private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
StringBuilder stringBuilder = new StringBuilder();
for (McfData.Rows.ConversionPathValue pathElement : path) {
if (stringBuilder.length() > 0)
stringBuilder.append(" > ");
stringBuilder.append(pathElement.getNodeValue());
}
return stringBuilder.toString();
}
Informações do relatório
Além dos dados de relatório, a consulta retorna informações (ID do relatório, por exemplo) sobre os dados. Por exemplo, o método a seguir imprime as informações do relatório:
Java
private static void printReportInfo(McfData mcfData) {
System.out.println("Report Info:");
System.out.println("ID:" + mcfData.getId());
System.out.println("Self link: " + mcfData.getSelfLink());
System.out.println("Kind: " + mcfData.getKind());
System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}
O campo containsSampledData informa se foi feito algum tipo de amostra da resposta da consulta.
Como a amostragem pode afetar os resultados da consulta, os valores da amostra retornados da consulta (API) não correspondem aos mostrados na interface da Web. Consulte Amostragem para mais detalhes.
Informações da vista da propriedade (perfil)
A resposta da consulta inclui o ID da propriedade da Web, o nome e o ID da vista (perfil) e o ID da conta do Google Analytics que contém a vista (perfil). Por exemplo, o método a seguir os imprime no terminal (saída padrão):
Java
private static void printProfileInfo(McfData mcfData) {
ProfileInfo profileInfo = mcfData.getProfileInfo();
System.out.println("View (Profile) Info:");
System.out.println("Account ID: " + profileInfo.getAccountId());
System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
System.out.println("Table ID: " + profileInfo.getTableId());
}
Informações da consulta
A resposta da consulta inclui um objeto Query que contém os valores de todos os parâmetros de consulta da solicitação de dados. Por exemplo,
o método a seguir imprime os valores desses parâmetros:
Java
private static void printQueryInfo(McfData mcfData) {
Query query = mcfData.getQuery();
System.out.println("Query Info:");
System.out.println("Ids: " + query.getIds());
System.out.println("Start Date: " + query.getStartDate());
System.out.println("End Date: " + query.getEndDate());
System.out.println("Metrics: " + query.getMetrics()); // List of Analytics metrics
System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
System.out.println("Sort: " + query.getSort()); // List of sorte metrics or dimensions
System.out.println("Segment: " + query.getSegment());
System.out.println("Filters: " + query.getFilters());
System.out.println("Start Index: " + query.getStartIndex());
System.out.println("Max Results: " + query.getMaxResults());
}
Métodos diferentes de query.getMetrics(),
query.getDimensions() e query.getSort()
retornam um String. Por exemplo, query.getStartDate()
retorna a data de início (uma String) do relatório.
Informações de paginação
Qualquer solicitação da API Multi-Channel Funnels Reporting pode corresponder a centenas de milhares de linhas de dados dos funis multicanal. A API Multi-Channel Funnels Reporting retorna apenas um subconjunto em determinado momento, conhecido como uma única página de dados. Para recuperar todas as páginas de dados, use o campo de paginação. O método a seguir imprime as informações de paginação:
Java
private static void printPaginationInfo(McfData mcfData) {
System.out.println("Pagination Info:");
System.out.println("Previous Link: " + mcfData.getPreviousLink());
System.out.println("Next Link: " + mcfData.getNextLink());
System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
System.out.println("Total Results: " + mcfData.getTotalResults());
}
A chamada do método mcfData.getTotalResults() retorna o número total de linhas para a consulta, que pode ser maior que o número total de linhas retornadas pela consulta. E a chamada do método
mcfData.getItemsPerPage() retorna o número máximo de linhas
que a resposta da consulta pode conter.
A chamada de método mcfData.getPreviousLink() retorna o link para a página anterior e mcfData.getNextLink() retorna o link para a próxima página.
Totais de todos os resultados
Para acessar os valores totais das métricas solicitadas em todos os resultados,
não apenas os resultados retornados na resposta da consulta, chame o
método getTotalsForAllResults() na resposta da consulta,
um objeto McfData. Use os valores totais para calcular as médias.
Java
private static void printTotalsForAllResults(McfData mcfData) {
System.out.println("Metric totals over all results:");
Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
System.out.println(entry.getKey() + " : " + entry.getValue());
}
}
Amostra de trabalho
Java
Biblioteca de cliente Java da API do Google Amostra da API Multi-Channel Funnels Reporting