Como fazer upgrade do aplicativo da API Maps JavaScript da V2 para a V3

A API Maps JavaScript v2 não está mais disponível desde 26 de maio de 2021. Como resultado, os mapas da v2 do seu site deixarão de funcionar e retornarão erros de JavaScript. Para continuar usando mapas no seu site, migre para a API Maps JavaScript v3. Este guia ajudará você nesse processo.

Visão geral

Todo aplicativo terá um processo de migração um pouco diferente. No entanto, há algumas etapas comuns a todos os projetos:

  1. Receba uma nova chave. A API Maps JavaScript agora usa o Console do Google Cloud para gerenciar chaves. Se você ainda estiver usando uma chave v2, consiga a nova chave de API antes de iniciar a migração.
  2. Atualize o bootstrap da API. A maioria dos aplicativos carrega a API Maps JavaScript v3 com o seguinte código:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. Atualize seu código. O número de mudanças necessárias dependerá muito do seu aplicativo. Estas são algumas das mudanças comuns:
    • Sempre faça referência ao namespace google.maps. Na v3, todo o código da API Maps JavaScript é armazenado no namespace google.maps.* em vez de no namespace global. A maioria dos objetos também foi renomeada como parte desse processo. Por exemplo, em vez de GMap2, você carregará google.maps.Map.
    • Remova todas as referências a métodos obsoletos. Vários métodos de utilitários de uso geral foram removidos, como GDownloadURL e GLog. Substitua essa funcionalidade por bibliotecas de utilitários de terceiros ou remova essas referências do seu código.
    • (Opcional) Adicionar bibliotecas ao código. Muitos recursos foram externalizados em bibliotecas de utilitários para que cada app precise carregar apenas as partes da API que serão usadas.
    • (Opcional) Configurar seu projeto para usar funções externas da v3. As instâncias externas da v3 podem ser usadas para ajudar a validar seu código com o Compiler de fechamento ou para acionar o preenchimento automático no seu ambiente de desenvolvimento integrado. Saiba mais sobre Compilação avançada e recursos externos.
  4. Teste e itere. Você ainda precisa fazer algumas coisas, mas a boa notícia é que já está no caminho certo para começar a usar seu novo aplicativo de mapas da v3.

Mudanças na V3 da API Maps JavaScript

Antes de planejar sua migração, reserve um tempo para entender as diferenças entre a API Maps JavaScript v2 e a API Maps JavaScript v3. A versão mais recente da API Maps JavaScript foi escrita do zero, com foco em técnicas modernas de programação JavaScript, aumento do uso de bibliotecas e uma API simplificada. Muitos recursos novos foram adicionados à API, e vários recursos conhecidos foram alterados ou até mesmo removidos. Esta seção destaca algumas das principais diferenças entre as duas versões.

Algumas das mudanças na API v3 incluem:

  • Uma biblioteca principal otimizada. Muitas das funções suplementares foram movidas para bibliotecas, ajudando a reduzir os tempos de carregamento e análise da API Core, o que permite que o mapa seja carregado rapidamente em qualquer dispositivo.
  • Melhor desempenho de vários recursos, como renderização de polígonos e colocação de marcadores.
  • Uma nova abordagem de limites de uso do lado do cliente para acomodar melhor os endereços compartilhados usados por proxies para dispositivos móveis e firewalls corporativos.
  • Adição de compatibilidade com vários navegadores modernos e navegadores para dispositivos móveis. A compatibilidade com o Internet Explorer 6 foi removida.
  • Remoção de muitas das classes auxiliares de uso geral ( GLog ou GDownloadUrl). Atualmente, existem muitas bibliotecas JavaScript excelentes que oferecem funcionalidades semelhantes, como Interdição ou jQuery.
  • Uma implementação do Street View em HTML5 que pode ser carregada em qualquer dispositivo móvel.
  • Panoramas personalizados do Street View com suas próprias fotos, permitindo que você compartilhe panoramas de montanhas de esqui, casas à venda ou outros lugares interessantes.
  • Personalizações de mapas estilizados que permitem mudar a exibição de elementos no mapa básico para corresponder ao seu estilo visual exclusivo.
  • Suporte a vários serviços novos, como ElevationService e Distance Matrix.
  • Um serviço de rotas aprimorado fornece rotas alternativas, otimização de rotas (soluções aproximadas para o problema do vendedor de viagens), rotas de bicicleta (com camada de bicicleta), rotas de transporte público e rotas arrastáveis.
  • Um formato de geocodificação atualizado que fornece informações de tipo mais precisas que o valor accuracy da API Geocoding v2.
  • Suporte a várias janelas de informações em um único mapa

Fazer upgrade do aplicativo

Sua nova chave

A API Maps JavaScript v3 usa um novo sistema de chaves da v2. Talvez você já esteja usando uma chave da v3 com seu aplicativo. Nesse caso, nenhuma mudança é necessária. Para verificar, verifique o URL de onde você carrega a API Maps JavaScript para o parâmetro key. Se o valor da chave começar com 'ABQIAA' você está usando uma chave v2. Se você tiver uma chave v2, faça upgrade para uma chave v3 como parte da migração, que:

  • Permite monitorar o uso da API no Console do Google Cloud.
  • Permite que você compre mais cota quando necessário.
  • Oferece ao Google uma forma de entrar em contato com você sobre seu aplicativo.

A chave é transmitida ao carregar a API Maps JavaScript v3. Saiba mais sobre como gerar chaves de API.

Se você é um cliente das APIs Google Maps for Work, pode estar usando um ID do cliente com o parâmetro client em vez de usar o parâmetro key. Os IDs do cliente ainda são compatíveis com a API Maps JavaScript v3 e não precisam passar pelo processo de upgrade de chave.

Carregando a API

A primeira modificação que você precisa fazer no código envolve a forma como a API é carregada. Na v2, você carrega a API Maps JavaScript por meio de uma solicitação para http://maps.google.com/maps. Se você estiver carregando a API Maps JavaScript v3, será necessário fazer as seguintes alterações:

  1. Carregar a API de //maps.googleapis.com/maps/api/js
  2. Remova o parâmetro file.
  3. Atualize o parâmetro key com a nova chave v3. Os clientes das APIs Google Maps for Work precisam usar um parâmetro client.
  4. (Somente no Plano Premium da Plataforma Google Maps) Verifique se o parâmetro client é fornecido conforme explicado no Guia do desenvolvedor do Plano Premium da Plataforma Google Maps.
  5. Remova o parâmetro v para solicitar a versão mais recente ou altere o valor de acordo com o esquema de controle de versões v3.
  6. (Opcional) Substitua o parâmetro hl por language e preserve o valor dele.
  7. (Opcional) Adicione um parâmetro libraries para carregar bibliotecas opcionais.

No caso mais simples, o bootstrap da v3 especificará apenas o parâmetro da chave de API:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

O exemplo abaixo solicita a versão mais recente da API Maps JavaScript v2 em alemão:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

O exemplo abaixo é uma solicitação equivalente para a v3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Apresentação do namespace google.maps

A mudança mais perceptível na API Maps JavaScript v3 é a introdução do namespace google.maps. Por padrão, a API v2 coloca todos os objetos no namespace global, o que pode resultar em conflitos de nomenclatura. Na v3, todos os objetos estão localizados no namespace google.maps.

Ao migrar o aplicativo para a v3, será necessário alterar o código para usar o novo namespace. Infelizmente, pesquisar ""G" e substituir por "google.maps." não funcionará' totalmente funciona. No entanto, é uma boa regra prática a ser aplicada ao analisar seu código. Veja abaixo alguns exemplos das classes equivalentes na v2 e na v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Remover código obsoleto

A API Maps JavaScript v3 tem paralelos para a maioria das funcionalidades na v2. No entanto, algumas classes não são mais compatíveis. Como parte da migração, é necessário substituir essas classes por bibliotecas de utilitários de terceiros ou remover essas referências do seu código. Há várias bibliotecas JavaScript excelentes que oferecem funcionalidades semelhantes, como Interdição ou jQuery.

As seguintes classes não têm paralelo na API Maps JavaScript v3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Comparar código

Vamos comparar dois aplicativos, bem simples, que foram escritos com as APIs v2 e v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

Como você pode ver, existem várias diferenças entre os dois aplicativos. As principais mudanças incluem:

  • O endereço de onde a API é carregada foi alterado.
  • Os métodos GBrowserIsCompatible() e GUnload() não são mais necessários na v3 e foram removidos da API.
  • O objeto GMap2 é substituído por google.maps.Map como o objeto central na API.
  • Agora, as propriedades são carregadas por meio das classes Options. No exemplo acima, definimos as três propriedades necessárias para carregar um mapa (center, zoom e mapTypeId) por meio de um objeto MapOptions in-line.
  • Na v3, a IU padrão é ativada por padrão. É possível desativar isso definindo a propriedade disableDefaultUI como true no objeto MapOptions.

Resumo

Neste ponto, você já conheceu alguns dos principais pontos envolvidos na sua migração da v2 para a v3 da API Maps JavaScript. Talvez você precise de mais informações, mas isso depende do seu aplicativo. Nas seções a seguir, incluímos instruções de migração para casos específicos que você pode encontrar. Além disso, há vários recursos que podem ser úteis durante o processo de upgrade.

Caso tenha algum problema ou dúvida sobre este artigo, use o link ENVIAR FEEDBACK na parte superior desta página.

Referência detalhada

Esta seção apresenta uma comparação detalhada dos recursos mais usados da v2 e da v3 da API Maps JavaScript. Cada seção da referência foi projetada para ser lida individualmente. Recomendamos que você não leia toda a referência. Em vez disso, use esse material para ajudar na migração caso a caso.

  • Eventos - como registrar e tratar eventos.
  • Controles: manipula os controles de navegação que aparecem no mapa.
  • Sobreposições: adicionar e editar objetos no mapa.
  • Tipos de mapa - os blocos que compõem o mapa de base.
  • Camadas: adição e edição de conteúdo como um grupo, como camadas KML ou Tráfego.
  • Serviços: trabalhando com geocodificação, rotas ou serviços do Street View do Google.

Eventos

O modelo de eventos da API Maps JavaScript v3 é semelhante ao usado na v2, embora muita coisa tenha mudado internamente.

Controles

A API Maps JavaScript mostra controles de IU que permitem aos usuários interagir com o mapa. Você pode usar a API para personalizar a aparência desses controles.

Sobreposições

As sobreposições refletem objetos que você adiciona ao mapa para designar pontos, linhas, áreas ou coleções de objetos.

Tipos de mapa

Os tipos de mapas disponíveis na v2 e v3 são um pouco diferentes, mas todos os tipos básicos de mapas estão disponíveis nas duas versões da API. Por padrão, a v2 usa blocos de mapa de via padrão "quot;painted" quot; No entanto, a v3 exige que um tipo específico de mapa seja fornecido ao criar um objeto google.maps.Map.

da imagem

Camadas são objetos no mapa que consistem em uma ou mais sobreposições. Eles podem ser manipulados como uma única unidade e refletem geralmente coleções de objetos.

Serviços