Importação de dados - guia do desenvolvedor

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Este documento explica aos desenvolvedores os conceitos avançados sobre como usar a API de gerenciamento para importar dados para sua conta do Google Analytics.

Introdução

Com o recurso de importação de dados na API de gerenciamento, você pode fazer o upload, listar, excluir e receber dados importados da sua conta do Google Analytics. Para uma visão geral e para saber mais sobre as vantagens do recurso de importação de dados, consulte Sobre 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 todas as origens de dados associadas 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 uma origem de dados personalizada / conjunto de dados.

Antes de começar

Todas as Google Analytics APIs são acessadas de maneira semelhante. Antes de começar com a API de gerenciamento, leia:

  • A página Bibliotecas cliente para ver uma lista completa de bibliotecas cliente específicas de linguagens de programação que funcionam com a API.
  • O Guia de referência para aprender a usar a interface da API para acessar dados sem uma biblioteca cliente.

Cada biblioteca cliente fornece um único objeto de serviço "Analytics" para acessar todos os dados da API de gerenciamento. Para criar o objeto de serviço:

  1. Registre seu aplicativo no Google Developers Console.
  2. Autorize o acesso aos dados do Google Analytics.
  3. Crie um objeto de serviço "Analytics".

Se você não tiver concluído essas etapas, pare e leia o Tutorial de apresentação da Google Analytics API. Ele orienta você sobre as etapas iniciais de criação de um aplicativo da Google Analytics API. Depois de concluí-lo, você saberá como acessar Google Analytics APIs para realizar tarefas reais.

Casos de uso

O recurso de importação de dados pode ser usado para integrar os dados da sua empresa aos dados do Google Analytics. Por exemplo, é possível usar:

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 estendida

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 no Google Analytics com o objetivo criar listas de remarketing do Google AdWords, consulte Importação de dados do usuário para criar públicos de remarketing do Google AdWords.

Dados de 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 no 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 alfa-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 para 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 no Google Analytics, consulte Importação de dados do produto usando a API de gerenciamento.

Importação de dados resumida

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), além de comparar o desempenho da campanha de todos os investimentos de publicidade e de marketing on-line.

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

Conceitos

Status de processamento

Depois de fazer o upload de um arquivo, o status do envio será PENDING até que o upload tenha sido 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/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 contém uma linha de dados com uma chave (por exemplo, data, origem, mídia) que corresponde 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 uma origem de dados personalizada / 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 da origem de dados personalizada / 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 da importação de dados

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 satisfeitas de forma que ele seja considerado válido 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 mensagens de erro serão exibidas. A API informará até 10 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
  • 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 contém.

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 precisa ficar entre aspas. Por exemplo, em source1,"medium,ether",group1,100, o segundo valor da célula é "medium,ether".
  • Para especificar as aspas duplas em uma célula, além de começar e terminar com elas, duplique-as. Por exemplo, em source1,"medium""ether",group1,100, o segundo valor da célula é "medium"ether".

Exemplos de códigos

Com o recurso upload, um usuário autorizado pode fazer o upload, listar, receber e excluir dados importados. Com o recurso customDataSource, um usuário autorizado pode listar quaisquer origens de dados personalizadas. Para usar qualquer um desses métodos, você precisa criar um objeto de serviço Analytics, conforme descrito na seção Antes de começar.

Para exemplos de código que mostram como trabalhar com o recurso de upload, acesse as referências de método a seguir.

Uploads

  • list: lista os uploads aos quais o usuário tem acesso.
  • get: recebe os uploads aos quais o usuário tem acesso.
  • deleteUploadData: exclui os dados associados a um upload anterior.
  • uploadData: faz o upload de dados para uma origem de dados personalizada.

Origens de dados / conjuntos de dados personalizados

  • list: lista as origens de dados personalizadas às quais o usuário tem acesso.