API de aprovisionamento – guia do desenvolvedor

Neste documento, você encontra explicações importantes sobre como usar a API de provisionamento para criar novas contas do Google Analytics.

Introdução

A API de aprovisionamento pode ser usada para criar novas contas do Google Analytics e permitir seu uso para clientes em grande escala. Ela é destinada a grandes parceiros e provedores de serviço qualificados. Consulte a Visão geral da API de aprovisionamento para uma introdução à API de aprovisionamento.

Antes de começar

Todas as Google Analytics APIs são acessadas de maneira semelhante. Antes de começar a usar a API de aprovisionamento:

  • 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.
  • Leia o Guia de referência para saber mais sobre a interface da API e sobre como acessar dados sem uma biblioteca cliente.

Todas as bibliotecas cliente fornecem um único objeto de serviço "Analytics" para acessar a API de aprovisionamento. Para criar o objeto de serviço, geralmente é necessário seguir as etapas a seguir:

  1. Registre seu aplicativo no console de APIs do Google.
  2. Autorize a criação de uma nova conta 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.

Visão geral

Há dois fluxos diferentes a serem considerados para a criação de contas do Google Analytics usando a API de aprovisionamento:

  • Fluxo técnico: o fluxo completo para provisionar uma conta do Google Analytics programaticamente para um usuário.
  • Fluxo do usuário: as considerações de implementação que você deve conhecer sobre o fluxo de criação de conta a partir da perspectiva do usuário.

Este documento contém a descrição dos requisitos e etapas de alto nível de cada fluxo.

Fluxo técnico

As etapas de alto nível para usar a API de aprovisionamento para criar uma nova conta e integrá-la ao Google Analytics são:

  1. Solicitar que o usuário autentique e autorize o aplicativo/serviço usando OAuth 2.0.
  2. Criar um chamado de conta usando a API de aprovisionamento.
  3. Redirecionar o usuário para aceitar os Termos de Serviço (TOS, na sigla em inglês) do Google Analytics e agir de acordo com a resposta.
  4. (Opcional) Configurar a conta e as oportunidades de integração.

Se todas essas etapas forem concluídas, a conta do Google Analytics será criada para o usuário, e você terá os IDs de conta, propriedade e vista da propriedade (perfil) da nova conta.

Para cada etapa abaixo, há requisitos para a conclusão, resultados e uma descrição do fluxo técnico.

1. Autenticação e autorização

Cada usuário precisa autorizar seu aplicativo e conceder a ele a capacidade de provisionar uma conta do Google Analytics em seu nome. O fluxo de aplicativo do servidor da Web OAuth 2.0 é sugerido para concluir essa etapa.

O que é necessário para concluir essa etapa

Resultado dessa etapa

Assim que o fluxo de OAuth 2.0 for concluído, o usuário terá autorizado o aplicativo a provisionar uma conta no próprio nome, e você terá um token de acesso para o usuário.

Observação sobre tokens e escopos:

  • Se você pretende fazer solicitações adicionais para os dados dos relatórios ou configuração da conta do usuário depois da sua criação, convém autorizar também escopos adicionais durante essa etapa. Por exemplo, os escopos readonly ou edit.
  • Os tokens de acesso têm duração limitada. Se seu aplicativo precisa de acesso à Google Analytics API, além de do tempo de duração de um token de acesso único, recomendamos também solicitar um token de atualização configurando access_type=offline. Um token de atualização deve ser salvo com armazenamento em longo prazo seguro para cada usuário, já que permite que seu aplicativo obtenha novos tokens de acesso. Consulte Acesso off-line para detalhes adicionais.

Fluxo técnico dessa etapa

Você precisa conseguir um token de acesso para o usuário. Com base no fluxo descrito no servidor da Web OAuth 2.0, envie o usuário para o serviço de Contas do Google e, então, lidar com a resposta quando o usuário retornar ao seu serviço depois de completar o fluxo de Auth.

Formação do URL de OAuth 2.0 para o usuário a visitar

Quando o usuário clica em um botão ou link "Começar" ou "Criar uma conta", o link deve direcionar ao início do fluxo de OAuth 2.0 para solicitar que o usuário conceda acesso às permissões de provisionamento. Por exemplo:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Gerenciamento da resposta do serviço de Contas do Google

Assim que o usuário tomar a decisão de conceder acesso ao seu aplicativo, ele será redirecionado para redirect_uri, como especificado no URL que você formou com um parâmetro de consulta com um código de autorização. Se o usuário aprovar a solicitação, a resposta do código de autorização poderá ser usado para trocá-lo por um token de acesso para uma solicitação POST para a API de Contas do Google.

Salvamento do token de atualização (se aplicável)

O token de acesso será usado na próxima etapa, então, você pode armazená-lo temporariamente. Caso tenha solicitado também um token de atualização para o usuário, armazene-o de forma segura para uso em longo prazo. Um token de atualização tem longa duração e pode ser usado para emitir novos tokens de acesso.

2. Criação de um chamado de conta pela API de aprovisionamento

Assim que você tiver um token de acesso para o usuário autorizado, poderá usá-lo para fazer uma solicitação à API de aprovisionamento e criar um chamado de conta para o usuário. O chamado de conta é a primeira etapa da criação de uma conta para o usuário.

O que é necessário para concluir essa etapa

Um token de acesso para o usuário autorizado, conforme descrito em Autenticação e autorização e os seguintes detalhes de provisionamento:

  • URI de redirecionamento
    • Define para onde o usuário é redirecionado depois da página de Termos de Serviço (TOS) do Google Analytics. Ele pode ser diferente do URI de redirecionamento especificado durante o fluxo de autorização de OAuth 2.0.
    • O valor do parâmetro do URI de redirecionamento precisa corresponder exatamente aos valores registrados no Google Developers Console (incluindo os esquemas "http" ou "https", letras maiúsculas e minúsculas e delimitadores "/").
  • Campos da conta
    • Uma propriedade name é obrigatória para a conta.
  • Campos da propriedade da Web
    • Uma propriedade name é obrigatória para a propriedade.
    • Uma websiteUrl é obrigatória.
  • Campos do perfil
    • Uma propriedade name é obrigatória para o perfil.
    • Uma timezone pode ser fornecida opcionalmente. O padrão é America/Los_Angeles.

Ao criar um chamado de conta, apenas os campos básicos identificados acima podem ser definidos. Depois da criação da conta, é possível realizar alterações adicionais de configuração à propriedade ou vista da propriedade (perfil) pela API de gerenciamento.

Consulte a referência da API para contas, propriedades e vistas da propriedade (perfis) para detalhes adicionais sobre esses campos.

Resultado dessa etapa

Depois que uma solicitação é feita à API de aprovisionamento, você terá um chamado de conta de curta duração para o usuário. O ID do chamado de conta é usado na etapa final para solicitar que o usuário aceite os Termos de Serviço (TOS) e ative a conta. A conta só poderá ser usada depois que o usuário aceitar os TOS.

Fluxo técnico dessa etapa

Com o token de acesso ao usuário obtido durante a autenticação e autorização, é feita uma solicitação HTTP POST à API de provisionamento.

Solicitação à API de provisionamento para criar o chamado de conta

Consulte o método createAccountTicket na referência da API de provisionamento para detalhes so como fazer uma solicitação.

Resposta da API de provisionamento

Um solicitação bem-sucedida retorna uma resposta 200. O corpo da resposta contém um chamado de conta de curta duração. O chamado de conta consiste em um ID e detalhes da árvore da nova conta.

Consulte Account Ticket resource na referência da API de provisionamento para detalhes sobre a resposta.

O aplicativo também precisa lidar com respostas de erro.

3. O usuário aceita os Termos de Serviço (TOS) do Google Analytics

Depois de conseguir um ID de chamado de conta para o usuário, você poderá usá-lo com a solicitação TOS para solicitar que o usuário aceite os Termos de Serviço do Google Analytics.

O que é necessário para concluir essa etapa

Um ID de chamado de conta para o usuário autorizado.

Resultado dessa etapa

Após a conclusão do fluxo dos TOS usando o ID de chamado de conta, a conta, a propriedade e a vista da propriedade (perfil) serão criados. Assim, o usuário terá uma conta ativa. A resposta da página de TOS incluirá os ID da conta, propriedade e vista da propriedade (perfil).

Fluxo técnico dessa etapa

Com o ID de chamado da conta, redirecione o usuário para a página de TOS do Google Analytics, onde ele poderá aceitar os Termos de Serviço. Depois, você precisará lidar com a resposta da API.

Formação do URL de TOS para o usuário visitar

Redirecione o usuário à página de TOS e inclua o ID de chamado de conta como parte do URL:

https://www.google.com/analytics/web/?provisioningSignup=false#management/TermsOfService//?
  api.accountTicketId={account_ticket_id}
Gerenciamento da resposta dos TOS

Depois que o usuário fizer alguma ação na página de TOS, ele será redirecionado novamente para o redirectUri especificado durante a criação do chamado de conta. A resposta da página de TOS será incluída como parte da string de consulta.

As respostas bem-sucedidas retornarão dados sobre a estrutura da conta recém-criada, bem como o accountTicketId original:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Por exemplo, se o gerenciador de TOS do seu aplicativo estiver em http://www.your-app.com/gaTOS, ele deverá ser definido como redirectUri ao criar chamados de conta. O gerenciador de TOS do seu aplicativo deve esperar e gerenciar de forma adequada as solicitações HTTP GET que contêm parâmetros de consulta accountId, webPropertyId, profileId e accountTicketId para casos em que o chamado de conta é válido, e o usuário aceita os TOS.

Respostas sem sucesso incluem a resposta de erro:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

Seu gerenciador de TOS também deve gerenciar adequadamente solicitações HTTP GET que contêm o parâmetro de consulta error, indicando que ocorreu algum erro. O valor do parâmetro de consulta pode ser usado para outras ações ou para exibir uma mensagem ao usuário:

  • error=user_cancel: o usuário não aceitou os Termos de Serviço.
  • error=max_accounts_reached: o usuário atingiu o número máximo de contas do Google Analytics.
  • error=backend_error: um erro geral. O servidor retornou um erro que não se enquadra nas categorias acima.

4. (Opcional) Oportunidades de integração

Se você seguir o fluxo técnico acima, criará uma conta para o usuário e terá os IDs de conta, propriedade e Vista (perfil). Além disso, se solicitar permissões adicionais, também terá um token de atualização para o usuário. Com esses dados, você pode:

Fluxo do usuário

Nesta seção, você encontra a descrição das considerações de implementação relacionadas às etapas do fluxo de criação da conta a partir da perspectiva do usuário.

O fluxo começa com a oferta das duas opções a seguir para o usuário ativar a análise da sua propriedade:

  1. Criar uma conta do Google Analytics.
  2. Usar uma conta existente do Google Analytics. Observação: Esse fluxo não é coberto neste documento. Consulte a API de gerenciamento para detalhes sobre como acessar os dados de configuração do Google Analytics de um usuário.

Ao criar uma nova conta do Google Analytics, há informações que você deve obrigatoriamente enviar com a solicitação de provisionamento, como nome da conta, nome da propriedade etc. Dependendo das informações que você tiver sobre o usuário e o fluxo que preferir para exibi-las, há três opções principais para iniciar o fluxo do usuário depois que ele clica em "criar conta":

Solicitação de detalhes da conta depois da autorização

Nesse caso, solicita-se ao usuário detalhes da conta no meio do processo. O fluxo seria semelhante a este:

  1. Para o fluxo OAuth 2.0, o usuário é redirecionado para o serviço de Conta do Google. Se o usuário não tiver uma Conta do Google ou não estiver conectado, ele será solicitado a criar uma conta ou fazer login.
  2. O usuário é solicitado a autorizar o aplicativo a "criar contas do Google Analytics".
  3. O usuário aceita solicitações de permissão para o aplicativo.
  4. O usuário é redirecionado para o provedor de serviços. Lembre-se de que, se o usuário negar a autorização, ele ainda será redirecionado para o provedor de serviços.
  5. Um formulário é apresentado ao usuário para coletar detalhes sobre a conta para a ser criada (por exemplo, nome da conta, da propriedade e do perfil, além do fuso horário, URL do website etc.).
  6. O usuário preenche e envia o formulário e é redirecionado para o Google/vê os Termos de Serviço (TOS) do Google Analytics.
  7. O usuário aceita os TOS.
  8. O usuário é redirecionado ao provedor de serviços e recebe uma mensagem de confirmação da criação da conta com detalhes sobre ela e como acessá-la. Mesmo que o usuário não aceite os TOS, ele será redirecionado ao provedor de serviços.

Solicitação de detalhes da conta antes da autorização

Nesse caso, solicita-se ao usuário com antecedência detalhes da configuração da conta prestes a ser criada. O fluxo seria semelhante a este:

  1. No site do provedor de serviços, um formulário é apresentado ao usuário para coletar detalhes sobre a conta a ser criada (por exemplo, nome da conta, da propriedade e do perfil, além de fuso horário e URL do website).
  2. Para o fluxo OAuth 2.0, o usuário preenche o formulário, clica em "Enviar" e é redirecionado ao serviço da Conta do Google. Se o usuário não tiver uma Conta do Google ou não estiver conectado, será solicitado que ele crie uma conta ou faça login.
  3. É solicitado que o usuário autorize o aplicativo a "criar contas do Google Analytics".
  4. O usuário aceita as permissões solicitadas para o aplicativo.
  5. O usuário é redirecionado para o provedor de serviços.
  6. O usuário é redirecionado para o Google/vê os Termos de Serviço (TOS) do Google Analytics.
  7. O usuário aceita os TOS.
  8. O usuário é redirecionado ao provedor de serviços e recebe uma mensagem de confirmação da criação da conta do Google Analytics com detalhes sobre ela e como acessá-la.

Preenchimento prévio de detalhes da conta ou formulários ignorados

Se as informações sobre a conta do usuário já estiverem disponíveis (por exemplo, URL e nome do website, além de fuso horário etc.), as duas opções acima poderão ser resumidas a:

  • Preencher previamente o formulário e permitir que o usuário faça edições, se ele quiser.
  • Ignorar todas as etapas do formulário e criar automaticamente a conta com as informações existentes.