API Multi-Channel Funnels Reporting – guia do desenvolvedor

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 cliente de Java para acessar a API de relatórios de funis multicanal. Cada biblioteca cliente fornece um único objeto de serviço "Analytics" para chamar a API Multi-Channel Funnels Reporting 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":

1. Registre seu aplicativo no console de APIs do Google.
2. Autorize o acesso aos dados do Google Analytics.
3. Grave 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, continuar a ler o próximo guia.

Por exemplo, o código a seguir cria um objeto de serviço "Analytics" autorizado:

Analytics analytics = initializeAnalytics();

Use o objeto de serviço analytics do Google Analytics para chamar a API Multi-Channel Funnels Reporting.

Visão geral

Para usar a API Multi-Channel Funnels Reporting para recuperar dados, grave um aplicativo para:

1. consultar a API de relatórios de funis multicanal;
2. trabalhar com os resultados retornados da API.

Consultar a API Multi-Channel Funnels Reporting

Para solicitar dados da API Multi-Channel Funnels Reporting:

1. Crie um objeto de consulta da API Multi-Channel Funnels Reporting.
2. 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, onde 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 (ou seja, setDimensions). Por exemplo:

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 recuperar dos funis multicanal. 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. Por exemplo:

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

HttpResponse response = apiQuery.executeUnparsed();

Se a consulta for bem-sucedida, os dados solicitados serão retornados. Se ocorrer um erro, o método execute lançará uma exceção que contém um código de status e uma descrição do erro. O aplicativo deve capturar e manipular 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 de consulta tem um campo de cabeçalho de coluna que contém as informações de cabeçalho de tabela. O campo é uma lista (ou uma matriz) de objetos ColumnHeaders, e cada um contém o nome da coluna, o tipo de coluna e o tipo de dados da coluna. A ordem das colunas é: dimensões e métricas, na mesma ordem especificada na consulta original. Por exemplo, o método a seguir imprime os cabeçalhos de colunas:

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 uma 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 de cada célula são retornados como uma string ou um tipo de sequência de funis multicanal, o campo DataType de cada objeto do cabeçalho da 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 linhas de tabela:

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:

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 do 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 de relatório:

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 amostragem da resposta da consulta. Como a amostragem pode afetar os resultados da consulta, os valores examinados retornados da consulta (API) não coincidem com aqueles apresentados 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, nome e ID da vista da propriedade (perfil), e o ID da conta do Google Analytics que contém a vista da propriedade (perfil). Por exemplo, o método a seguir os imprime no terminal (saída padrão):

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 de solicitação de dados. Por exemplo, o método a seguir imprime os valores desses parâmetros:

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 uma String. Por exemplo, query.getStartDate() retorna a data de início (a 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:

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 do 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 do método mcfData.getPreviousLink() retorna o link para a página anterior e mcfData.getNextLink() retorna o link para a página seguinte.

Totais de todos os resultados

Para ter os valores totais das métricas solicitadas de todos os resultados, e não apenas dos resultados retornados na resposta da consulta, chame o método getTotalsForAllResults() na resposta da consulta, um objeto McfData. Utilize os valores totais para o cálculo as médias.

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