Guia do desenvolvedor sobre importação de dados

A API de gerenciamento do Google Analytics permite acesso programático ao recurso de importação de dados do Google Analytics.

Introdução

Com a API de gerenciamento, você pode fazer o upload, listar, excluir e ver arquivos enviados, além de listar conjuntos de dados. Para uma visão geral de alto nível das vantagens do recurso de importação de dados, consulte o artigo da Central de Ajuda Sobre a importação de dados.

Os dois recursos na API de gerenciamento que ativam a importação de dados são:

  • Recurso de origem de dados personalizada, chamado de "conjunto de dados na interface da Web". Ele funciona como um contêiner para seus arquivos enviados. Um conjunto de origens de dados personalizadas representa todos os conjuntos de dados associados a uma propriedade do Google Analytics.
  • Recurso de upload, que representa um arquivo enviado. Um conjunto de recursos de upload representa todos os arquivos dos quais você fez o upload para um conjunto de dados.

Casos de uso

O recurso de importação de dados tem três categorias de nível principais, cada uma com seu próprio caso de uso. A organização é a seguinte:

Importação de dados de hits

Dados de reembolso

As transações de comércio eletrônico que foram total ou parcialmente reembolsadas podem ser enviadas para o Google Analytics. Assim, fica mais fácil reconciliar automaticamente os dados nos seus Relatórios de comércio eletrônico do Google Analytics com reembolsos processados.

Para saber como importar dados de reembolso para o Google Analytics, consulte Exemplo de importação de dados de reembolso.

Importação de dados estendidos

Dados do usuário

Você pode fazer o upload de dados do usuário sem identificação pessoal a partir de ferramentas externas do CRM (Gerenciamento de relacionamento com clientes) e criar públicos de remarketing do Google AdWords para seus segmentos de usuários mais valiosos.

Para saber como importar dados do usuário para o Google Analytics com a finalidade de criar públicos de remarketing do Google AdWords, consulte:

Dados da campanha

Você pode importar os dados da campanha para o Google Analytics e personalizar a análise de desempenho da campanha para sua empresa.

Para saber como importar dados da campanha para o Google Analytics, consulte Importação de dados da campanha usando a API de gerenciamento.

Dados geográficos

Você pode importar mapeamentos de IDs geográficos para as regiões, permitindo a geração de relatórios sobre dados do Google Analytics por região personalizada. Por exemplo, nos Estados Unidos, você pode operar nos grupos de estados das regiões leste, central e oeste. Na Europa, você pode operar nos grupos de países das regiões norte, central e sul. Ao importar dados, você pode usar ga:regionId, ga:cityId, ga:countryIsoCode ou ga:subContinentCode como chaves. Os IDs de cidade e país estão listados na tabela "Segmentação geográfica". O código do país ISO e o subcódigo do continente estão listados nas tabelas ISO-3166-1 alpha-2 e UN M.49, respectivamente.

Para mais informações sobre a importação de dados geográficos, consulte o exemplo de importação de dados geográficos.

Dados de conteúdo

Faça o upload de metadados relacionados ao conteúdo, como autor e assunto, para aproveitar o Google Analytics e fazer uma análise aprofundada de artigos publicados em um website.

Para saber como importar dados de conteúdo para o Google Analytics, consulte o exemplo de importação de dados de conteúdo.

Dados do produto

A importação de dados do produto para o Google Analytics simplifica e reduz a quantidade de dados de comércio eletrônico que você precisa enviar com os hits, como exibições de página e eventos. Um único ID do produto ou SKU pode ser agregado aos seus dados importados do produto para preencher as dimensões e métricas do produto nos seus relatórios.

Para saber como importar seus dados do produto para o Google Analytics, consulte Importação de dados do produto usando a API de gerenciamento.

Importação de dados resumidos

Dados de custo

Você pode fazer o upload de dados de custo para campanhas pagas que não são do Google e aproveitar a plataforma Google Analytics para realizar análises de ROI (retorno do investimento) e comparar o desempenho da campanha de todos os investimentos de publicidade e de marketing on-line.

Para saber como importar dados de custo para o Google Analytics, consulte Importação de dados de custo usando a API de gerenciamento.

Conceitos

Status do processamento

Depois de fazer o upload de um arquivo, o status do envio será PENDING até que o upload seja validado e processado. Se o processamento for bem-sucedido, o status mudará para COMPLETED.

Se ocorrer um erro durante o processamento, e o upload não for realizado, o status do upload será FAILED. Será fornecida uma lista de erros para ajudar você a identificar os problemas com o arquivo. Veja a seguir um exemplo de resposta para a validação com erro:

{
  id: "YU4DersR_ORzyzXC_AoWw",
  kind: "analytics#upload",
  accountId: "12345",
  customDataSourceId: "poaU7EPcR4WGU-dkNghYKQ",
  status: "FAILED",
  errors:
  [
    "Invalid cell data 12.99 at row 1 column 6. expected data type LONG.",
    "Invalid cell data 12.99 at row 2 column 6. expected data type LONG.",
    "Invalid cell data 23.81 at row 3 column 6. expected data type LONG.",
    "Invalid cell data 199.99 at row 4 column 6. expected data type LONG."
  ]
}

Soma x substituição dos dados de custo

Ao criar uma origem de dados personalizada / um conjunto de dados para os dados de custo, você tem a opção de especificar como lidar com os casos em que um arquivo enviado tiver uma linha de dados com uma chave (por exemplo, data, origem, mídia) que corresponda a uma linha existente. As opções são:

  • summation (padrão): os novos dados serão adicionados aos dados correspondentes anteriores, e as métricas serão somadas.
  • overwrite: os novos dados substituirão os dados correspondentes anteriores.

Para saber qual tipo foi definido para um conjunto de dados, use o método lista de origem de dados personalizada para verificar se a propriedade importBehavior está definida como OVERWRITE ou SUMMATION.

Soma x substituição no nível da linha dos dados de custo

Você também tem a opção de substituir o comportamento do conjunto de dados para cada arquivo que enviar, incluindo a coluna ga:importBehavior no cabeçalho. Em cada linha, você pode definir o valor de ga:importBehaviour como SUMMATION ou OVERWRITE.

Por exemplo, o arquivo a seguir substituirá os dados de custo anteriores para Facebook/cpc e Yahoo/cpc, mas a linha Bing/cpc será adicionada a todos os dados de custo existentes para essa combinação específica de origem/mídia e data.

ga:date,ga:source, ga:medium,ga:adCost,ga:importBehavior
20140604,facebook,cpc,12.23,OVERWRITE
20140604,bing,cpc,3.23,SUMMATION
20140604,yahoo,cpc,11.23,OVERWRITE

Formato e restrições

Para fazer o upload dos dados no Google Analytics, eles precisam estar em um arquivo CSV formatado adequadamente. Esta seção descreve as restrições que precisam ser cumpridas de forma que eles sejam considerados válidos para o upload em todos os tipos de importação de dados.

Se alguma das restrições abaixo for violada ou se houver um erro de análise, haverá falha na solicitação de upload, e serão exibidas mensagens de erro. A API informará até dez erros em uma única resposta para ajudar os usuários a reduzir o número de uploads inválidos.

Restrições de arquivo

  • Codificação: UTF-8
  • Limite de tamanho de arquivo: 1 GB

Restrições de cabeçalho

  • A primeira linha é considerada um cabeçalho de coluna e é obrigatória. Ela precisa definir as dimensões e métricas que essa coluna específica conterá.

Restrições de linha

  • Há um limite de 1 MB para as linhas.

Formatação das células

  • As células podem ter no máximo 2.048 caracteres.
  • Os espaços à esquerda e à direita de uma célula serão removidos.
  • Para especificar uma vírgula em uma célula, o valor dela deve ficar entre aspas. Por exemplo, em source1,"medium,ether",group1,100, o segundo valor da célula é "medium,ether".
  • Para especificar aspas duplas em uma célula, além de começar e terminar com aspas duplas, use duas aspas duplas. Por exemplo, em source1,"medium""ether",group1,100, o segundo valor da célula é medium"ether.