Primeiros passos com o plano Premium no Android

Observação: o plano Premium da Plataforma Google Maps não está mais disponível para inscrições ou novos clientes.

Sua licença do plano Premium da Plataforma Google Maps oferece suporte avançado para o SDK do Maps para Android. Neste documento, mostramos como criar um app Android que usa o SDK do Maps para Android com o plano Premium.

Visão geral

Siga as instruções nesta página para fazer o download do SDK, configurar o projeto e adicionar um mapa. Veja a seguir um resumo das etapas necessárias:

  1. Fazer download do SDK
  2. Adicionar o SDK a um projeto Android novo ou existente
  3. Adicionar a chave de API ao manifesto do app
  4. Especificar as permissões necessárias do Android e o OpenGL ES versão 2
  5. Adicionar um mapa

Fazer download do SDK

Você pode fazer o download do SDK como uma biblioteca estática ou usar o Android SDK Manager.

Opção 1: fazer download do SDK como uma biblioteca estática

Faça o download da versão mais recente como uma biblioteca estática.

Opção 2: fazer download do SDK usando o Android SDK Manager

No Android Studio, faça o seguinte:

  1. Selecione Tools > Android > SDK Manager.
  2. Selecione Appearance & Behavior > System Settings > Android SDK.
  3. Clique na guia SDK Update Sites.
  4. Clique no sinal de adição (+) para incluir um novo site.
  5. Insira um nome, como "Google Maps for Work" e o URL: https://dl.google.com/geosdk/android-m4b-addon.xml
  6. Clique em OK.
  7. Clique na guia SDK Tools.
  8. Selecione Google Maps Mobile SDK for Work e clique OK para fazer o download.

O Android Studio instala a biblioteca em <android-sdk-folder>/extras/google/maps_for_business_sdk/.

Consulte o guia do Android SDK Manager para ver instruções de uso como uma ferramenta autônoma.

Adicionar o SDK ao seu projeto

Veja abaixo as instruções do Android Studio. Se você estiver utilizando outra ferramenta, consulte as instruções da documentação do Android referentes ao uso da linha de comando.

O SDK do Maps para Android referente ao plano Premium está disponível em dois formatos: um pacote aar (google-maps-sdk-m4b.aar) e um módulo de biblioteca (google-maps-sdk-m4b_lib). Escolha o formato mais adequado às suas necessidades.

Opção 1: importar o SDK do pacote aar

Siga as etapas abaixo para incluir o pacote aar (google-maps-sdk-m4b.aar) no seu projeto do Android Studio:

  1. Navegue até o plano Premium da Plataforma Google Maps neste local:

    <android-sdk>/extras/google/maps_for_business_sdk

  2. Copie o arquivo google-maps-sdk-m4b.aar no diretório libs do seu projeto. Se o diretório não existir, crie-o agora.

  3. Adicione o seguinte código ao arquivo build.gradle do seu app:

    dependencies {
        implementation(name:'google-maps-sdk-m4b', ext:'aar')
        implementation 'com.android.support:support-v4:+'
        implementation 'com.android.support:appcompat-v7:+'
        implementation 'com.google.android.gms:play-services-basement:15.0.1'
        implementation 'com.google.android.gms:play-services-base:15.0.1'
    }
    
    repositories {
        flatDir{
            dirs 'libs'
        }
    }
    
  4. No arquivo build.gradle do aplicativo, defina compileSdkVersion para a versão mais recente.

  5. Siga as etapas de configuração conforme descrito abaixo.

Opção 2: importar o SDK como um módulo de biblioteca

Em vez de usar o arquivo aar, siga as etapas abaixo para adicionar o módulo de biblioteca do SDK (google-maps-sdk-m4b_lib) a um projeto existente no Android Studio:

  1. No Android Studio, escolha a opção de importar um novo módulo (File -> New -> Import Module).
  2. Navegue até o SDK no seguinte local:

    <android-sdk>/extras/google/maps_for_business_sdk

  3. Selecione o diretório google-maps-sdk-m4b_lib e clique em Choose.

  4. Aceite os valores padrão no assistente de importação.

  5. Clique em Finish. Você verá um arquivo de texto com o resumo dos resultados do processo de importação.

  6. Verifique se a biblioteca está incluída no arquivo settings.gradle:

    include ':googlemapssdkm4b_lib'

  7. Adicione o seguinte código ao arquivo build.gradle do seu app:

    dependencies {
        implementation project(':googlemapssdkm4b_lib')
        implementation 'com.android.support:support-v4:+'
        implementation 'com.android.support:appcompat-v7:+'
        implementation 'com.google.android.gms:play-services-basement:15.0.1'
        implementation 'com.google.android.gms:play-services-base:15.0.1'
    }
    
  8. No arquivo build.gradle do aplicativo, defina compileSdkVersion para a versão mais recente.

Converter todas as configurações atuais que usam o Google Play Services

  1. Se você já tiver um app que usa o Google Play Services, substitua todas as referências ao pacote com.google.android.gms.maps por com.google.android.m4b.maps.
  2. Insira o prefixo m4b_ em todas as referências dos atributos de layout XML. Por exemplo, m4b_mapType e m4b_cameraZoom.

Especificar as configurações no manifesto do app

Um app Android que usa o SDK do Maps para Android precisa especificar as seguintes configurações no arquivo de manifesto AndroidManifest.xml:

Chave de API

Gere uma chave de API para seu projeto e inclua-a em AndroidManifest.xml, conforme descrito no guia de autenticação.

Permissões

Especifique quais permissões são necessárias para seu aplicativo adicionando os componentes <uses-permission> como filhos do elemento <manifest> em AndroidManifest.xml.

Permissões de localização

Se seu aplicativo acessa o local atual do usuário ativando a camada "My Location", solicite permissões de localização, conforme descrito no guia sobre dados de local.

Permissão de armazenamento externo

Se você segmentar a versão 8.3 ou superior do Google Play Services SDK, não precisará mais da permissão WRITE_EXTERNAL_STORAGE para usar o Maps SDK for Android.

Se você segmentar as versões anteriores do Google Play Services SDK, solicite a permissão android.permission.WRITE_EXTERNAL_STORAGE.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Observação: se seu app segmenta o nível de API 23 (Android 6.0), que exige o uso de permissões de tempo de execução, você precisa referenciar a versão 8.3 ou superior do Google Play Services SDK.

Permissões incorporadas automaticamente ao seu manifesto

As permissões a seguir são definidas no manifesto do Google Play Services e automaticamente incorporadas ao manifesto do seu app no tempo de compilação. Você não precisa adicioná-las explicitamente:

OpenGL ES versão 2

O SDK do Maps para Android usa o OpenGL ES versão 2 para renderizar o mapa. A configuração a seguir é definida no manifesto do Google Play Services e é vinculada automaticamente ao manifesto do seu app no tempo de compilação. Você não precisa adicioná-la explicitamente:

<uses-feature
        android:glEsVersion="0x00020000"
        android:required="true"/>

Com isso, os requisitos são informados aos serviços externos, e a Google Play Store é impedida de exibir o app em dispositivos não compatíveis com o OpenGL ES versão 2.

Adicionar um mapa

A maneira mais fácil de testar se o seu app está configurado corretamente é adicionar um mapa simples.

  1. Em activity_main.xml, adicione este fragmento:

    <?xml version="1.0" encoding="utf-8"?>
    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
              android:id="@+id/map"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              android:name="com.google.android.m4b.maps.MapFragment"/>
    
  2. Em MainActivity.java, adicione o seguinte código:

    package com.example.mapdemo;
    
    import android.app.Activity;
    import android.os.Bundle;
    
    public class MainActivity extends Activity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
        }
    }
    

Criar e executar o app

Compile e execute seu aplicativo. Você verá um mapa.

Solução de problemas:

  • Se o mapa não aparecer, confirme se você realizou todas as etapas exibidas neste documento. Especificamente, verifique se a chave de API está correta e se o serviço do plano Premium da Plataforma Google Maps está ativado na conta.

  • Se o número de métodos no projeto exceder o limite, você poderá receber um erro:

    Unable to execute dex: method ID not in [0, 0xffff]: 65536

    Para ver informações sobre causas e soluções, consulte o guia do desenvolvedor Android sobre como criar apps com mais de 65 mil métodos.

  • Se o projeto já depende do Guava, poderão ocorrer erros de colisão de classes, como este:

    com.android.dex.DexException: Multiple dex files define Lcom/google/common/annotations/Beta

    Para resolver esse problema, exclua a cópia do Guava do diretório google-maps-sdk-m4b_lib/libs.

Mais informações

Como migrar um app existente

A API Android disponível com o plano Premium é muito semelhante ao SDK do Maps para Android padrão. Sendo assim, o processo de migração é bem simples.

  1. Faça o download do SDK do Maps para Android no plano Premium. Em seguida, adicione o SDK ao projeto, conforme descrito acima.
  2. Substitua todas as referências ao pacote com.google.android.gms.maps por com.google.android.m4b.maps.
  3. Insira o prefixo m4b_ em todas as referências dos atributos de layout XML. Por exemplo, m4b_mapType e m4b_cameraZoom.
  4. Gere uma nova chave de API para seu projeto e inclua-a em AndroidManifest.xml, conforme descrito no guia de autenticação.
  5. Compile o aplicativo.

Comparativo de versões

Na tabela a seguir, descrevemos as principais diferenças entre o SDK do Maps para Android padrão e a API com o plano Premium.

  SDK do Maps para Android padrão Plano Premium
Nome do pacote com.google.android.gms.maps com.google.android.m4b.maps
Atributos XML no arquivo de layout Use o nome do atributo sem prefixo (por exemplo: mapType). Adicione o prefixo a todos os nomes de atributo com m4b_ (por exemplo: m4b_mapType). Para ver detalhes, consulte a documentação sobre atributos XML.
Local do download Incluído no Google Play Services. Disponível como uma biblioteca estática.
Canais de suporte Suporte com base na comunidade. Acesso ao Suporte Premium
Termos Sujeito aos Termos de Serviço da Plataforma Google Maps. Sujeito aos termos do plano Premium da Plataforma Google Maps.

Google Play Services

O SDK do Maps para Android padrão requer o APK do Google Play Services e a biblioteca de cliente maps do Google Play Services (com.google.android.gms:play-services-maps). No entanto, quando usado com o plano Premium da Plataforma Google Maps, o SDK só exige que o APK do Google Play Services esteja instalado no dispositivo de destino. A biblioteca de cliente maps não é necessária.

Ao migrar seu aplicativo para o plano Premium, remova a biblioteca de cliente maps do projeto, com todas as referências ao pacote com.google.android.gms.maps. Use apenas o SDK do plano Premium (o pacote com.google.android.m4b.maps) para acessar o Google Maps.

Você pode incluir outras bibliotecas de cliente do Google Play Services para aproveitar outras APIs do Google, como o Google Analytics, Location e Activity Recognition.

Exemplo de código

O repositório do Google Maps no GitHub inclui vários exemplos que demonstram o uso do SDK do Maps para Android no seu app Android. Os apps de amostra contêm o pacote com.google.android.gms.maps, e não o com.google.android.m4b.maps utilizado no plano Premium. Eles também exigem o SDK do Google Play Services, já que utilizam as APIs Location em partes da demonstração.

Além disso, cada página do guia do desenvolvedor contém snippets de código.

Documentação

As principais fontes de informações sobre o plano Premium da Plataforma Google Maps são as documentações do desenvolvedor e de referência disponíveis em outros locais do nosso site.