Como provisionar contas controladas pelo usuário — Guia dos Desenvolvedores de API

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 Provisioning para uma introdução à API Provisioning.

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.

Cada biblioteca cliente fornece um único objeto de serviço de análise para acessar a API de provisionamento. Para criar o objeto de serviço, geralmente é necessário seguir estas etapas:

  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 sobre as etapas iniciais de criação de um aplicativo da API Google Analytics. 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. Caso seu aplicativo precise de acesso à API Google Analytics depois do ciclo de vida de um único token de acesso, você também poderá solicitar um token de atualização definindo access_type=offline. Um token de atualização precisa ser salvo em um armazenamento seguro de longo prazo para cada usuário, já que ele permite que o aplicativo receba novos tokens de acesso. Consulte Acesso off-line para mais detalhes.

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, em seguida, processe a resposta quando o usuário for redirecionado de volta ao seu serviço após concluir o fluxo de autenticação.

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. 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

Quando o usuário tomar a decisão de conceder acesso ao seu aplicativo, ele será redirecionado para o redirect_uri, conforme especificado no URL que você formou com um parâmetro de consulta que contém um código de autorização. Se o usuário aprovar a solicitação, a resposta do código de autorização poderá ser usada para trocá-lo por um token de acesso. Para isso, faça uma solicitação POST à API Google Accounts.

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ório.
  • Campos de 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 do usuário obtido durante a autenticação e autorização, é feita uma solicitação HTTP POST à API de provisionar.

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

Consulte o método createAccountTicket na Referência da API de provisionamento para detalhes sobre como fazer a solicitação.

Resposta da API de aprovisionamento

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 Provisioning para ver detalhes sobre a resposta.

O aplicativo também precisa gerenciar 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 (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://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Gerenciamento da resposta dos TOS

Depois de realizar alguma ação na página de TOS, o usuário será redirecionado de volta para o redirectUri especificado durante a criação do tíquete de conta. A resposta da página de TOS será incluída como parte da string de consulta.

Respostas bem-sucedidas retornarão dados sobre a estrutura de 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 tíquetes de conta. O gerenciador de TOS do seu aplicativo precisa esperar e processar corretamente as solicitações HTTP GET que contêm os parâmetros de consulta accountId, webPropertyId, profileId e accountTicketId, para os casos em que o tíquete de conta é válido e o usuário aceitou 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 precisa gerenciar corretamente solicitações HTTP GET que contêm um parâmetro de consulta error, indicando que algo deu errado. 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 limite 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.