Solucionar problemas de autorização de URL do Google Maps APIs Premium Plan

Os IDs do cliente do Google Maps APIs Premium Plan são restritos a URLs autorizados específicos. Se você tentar usar um ID do cliente em um URL não autorizado, receberá uma mensagem de erro.

Este artigo é destinado a clientes do Google Maps APIs Premium Plan que experimentam esse problema e precisam descobrir o URL exato que deve ser autorizado.

Conceitos básicos

Para impedir que terceiros usem seu ID de cliente em seus próprios sites, o uso desse ID de cliente é restrito a uma lista de URLs que você tem de autorizar. Um URL pode ser específico, como uma única página da Web, ou genérico, como um domínio inteiro.

Para obter uma lista dos URLs autorizados, ou para autorizar URLs adicionais:

  1. Faça login no Google Cloud Support Portal.
  2. No menu à esquerda, clique em Maps: Manage Client ID.

Você pode adicionar até 100 URLs por vez, até um total máximo de 3.000 URLs. Se precisar de limites maiores, entre em contato com o Google Cloud Support.

Há mais informações disponíveis sobre a autorização de URLs no guia do desenvolvedor.

O problema

Um aplicativo que reside em um URL não autorizado para o seu ID do cliente não poderá usar as Google Maps APIs com esse ID do cliente. Um usuário que tentar usar esse aplicativo receberá uma mensagem de erro que depende da API específica que o aplicativo tentar carregar. Os usuários não poderão usar recursos que dependem da Google Maps JavaScript API.

  • A Google Maps JavaScript API exibirá esta mensagem:

    Esta página não conseguiu exibir um elemento do Google Maps. Esse URL não está autorizado a usar o ID de cliente do Google Maps fornecido. Error Code: UnauthorizedURLForClientIdMapError

  • Se você estiver usando a Google Maps JavaScript API v3.18 ou anterior, a mensagem exibida será:

    O Google desativou o uso das Google Maps APIs para este aplicativo. Este site não está autorizado a usar o ID de cliente do Google Maps fornecido. Se você é proprietário desse aplicativo, saiba mais sobre como registrar URLs no guia do desenvolvedor.

A remoção do ID do cliente do aplicativo não é uma correção válida.* A remoção provocará a perda de todos os privilégios do Google Maps APIs Premium Plan para esse aplicativo. Isso significa que você não terá direito a:

  • Um acordo de nível de serviço (ANS) robusto.
  • Suporte ao cliente.
  • Maiores limites para serviços Web.
  • Termos e condições de nível comercial.
  • Suporte a aplicativos de intranet no seu local de trabalho.

Isso significa que aplicativos exclusivamente internos ou não gratuitos que não usam um ID do cliente do Google Maps APIs Premium Plan corretamente não estarão cumprindo os termos de serviço das Google Maps APIs gratuitas.

A solução

A solução correta é encontrar e autorizar os URLs corretos para uso com seu ID do cliente.

Na maioria dos casos, você precisa autorizar um aplicativo a usar seu ID do cliente. Muitas vezes, os aplicativos usam vários URLs que compartilham um padrão comum. Por exemplo, um localizador de lojas pode residir em example.com/stores ou stores.example.com. Você precisa encontrar um URL que corresponda a todos os URLs usados pelo aplicativo.

Observação: a autorização de www.example.com não autorizará stores.example.com ou qualquer outro subdomínio de example.com.

Cada URL autorizado pode ser específico, como uma única página da Web, ou genérico, como um domínio inteiro, incluindo seus subdomínios. Consulte o guia do desenvolvedor para obter mais informações. Recomendamos autorizar URLs que correspondam a um conjunto de URLs razoavelmente amplo, desde que você os administre.

Observação: a autorização de todo um domínio não é recomendada, a menos que sua organização tenha controle completo sobre todo o conteúdo desse domínio. Por exemplo, a autorização de todo o domínio blogspot.com permitiria que todos usassem o seu ID do cliente nesse domínio à sua custa. Em vez disso, autorize apenas um blog específico como, por exemplo, googlegeodevelopers.blogspot.com, ou até mesmo uma página específica nesse blog.

Como encontrar o URL correto

Normalmente, o URL pode ser encontrado na barra de localização do navegador. Em sites públicos que não usam tags <iframe>, isso normalmente é fácil. Em caso de dúvida, use a abordagem a seguir para a verificação.

Aplicativos complexos podem carregar as Google Maps APIs de um URL diferente do que está na barra de localização dos usuários. Isso ocorre com tags <iframe> ou quando o URL da página que carrega as APIs é gerado dinamicamente no servidor e enviado ao navegador. Para encontrar os URLs corretos nesses casos, é necessário inspecionar algumas solicitações HTTP do navegador para os servidores do Google.

O URL que precisa ser autorizado é o que está no cabeçalho Referer das solicitações enviadas pelo navegador ao Google para carregar a API. Cada API é carregada de um URL diferente:

Todas as solicitações para maps.googleapis.com podem ser enviadas para maps.google.com ou maps-api-ssl.google.com dependendo de como o aplicativo é configurado para carregar a API. Portanto, ao procurar pelas solicitações acima, normalmente o caminho importante é o que está em negrito.

Nos cabeçalhos HTTP no navegador

Antes de inspecionar o cabeçalho Referer nas solicitações acima, é preciso antes capturá-lo no navegador. Há várias ferramentas gratuitas disponíveis para capturar cabeçalhos HTTP em todos os principais navegadores:

Observação: é necessário configurar o Fiddler2 para capturar tráfego HTTPS. Veja os detalhes aqui.

Se não puder capturar cabeçalhos HTTP diretamente do navegador, você poderá tentar capturar tráfego HTTP usando um analisador de protocolo de rede, como o Wireshark. Essa ferramenta pode ser mais complexa para operar que as ferramentas acima. Se não estiver familiarizado com ela, confira alguns tutoriais do Wireshark na Web.

Com a ferramenta escolhida, siga as etapas a seguir para encontrar o URL que precisa ser autorizado:

  1. Inicie a ferramenta de captura. Verifique se ela está capturando solicitações HTTP no navegador.
  2. Aponte o navegador para o aplicativo que não consegue carregar as Google Maps APIs que usa o seu ID do cliente. Você deve receber uma das mensagens de erro descritas acima.
  3. Interrompa a captura de tráfego HTTP. Isso facilita a inspeção do tráfego capturado.
  4. Encontre a solicitação que tenta carregar as Google Maps APIs usando seu ID do cliente. Por exemplo, se o aplicativo tentar carregar a Google Maps JavaScript API, procure uma solicitação como esta:
    GET /maps/api/js?client=gme-yourclientid HTTP/1.1
  5. Os cabeçalhos da solicitação HTTP estão logo depois dessa linha, sem quebras de linha. Encontre um como este:
    Referer: http://www.example.com/stores/find?zip=94043
  6. O URL dessa linha é o que precisa ser autorizado para usar o seu ID do cliente.

No console do JavaScript no navegador

Se você usar a chave de API ou o ID do cliente em um site não autorizado, a Google Maps JavaScript API gravará mensagens de erro no window.console. Encontre o URL correto na mensagem de erro. No console, procure mensagens de erro como esta:

Google Maps APIs error: UnauthorizedURLForClientIdMapError ...
Your site URL to be authorized: http://www.example.com/stores/find?zip-94043

Se precisar de ajuda para encontrar as mensagens de erro, leia a seção sobre verificar erros do seu navegador.

Encontrar o padrão comum

Para assegurar que todo o aplicativo consiga carregar as Google Maps APIs usando seu ID do cliente, você precisa encontrar um padrão comum em todos os URLs usados pelo aplicativo e autorizar um URL que represente esse padrão, seguindo as regras explicadas no guia do desenvolvedor.

Muitas vezes, esse padrão será simplesmente um diretório (por exemplo, example.com/stores) ou um subdomínio (por exemplo, stores.example.com). Esses padrões geralmente podem ser deduzidos facilmente com apenas alguns URLs.

Ao lidar com aplicativos complexos, pode ser necessário repetir as etapas acimas com diversos URLs voltados ao usuário que exibem um mapa. No entanto, esse processo pode ser muito trabalhoso e ainda resulta em um conjunto de URLs incompleto. Para aplicativos desse tipo, provavelmente os desenvolvedores serão a melhor opção para fornecer o padrão de URLs.