Primeiros passos com o Plano premium no Android

Sua licença do Google Maps APIs Premium Plan oferece suporte aprimorado para a Google Maps Android API. Este documento ensina a criar um aplicativo Android que usa a Google Maps Android API com o Premium Plan.

Visão geral

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

  1. Baixe o SDK.
  2. Adicione o SDK a um projeto Android novo ou existente.
  3. Adicione a chave de API ao manifesto do aplicativo.
  4. Especifique as permissões necessárias do Android e o OpenGL ES versão 2.
  5. Adicione um mapa.

Baixar o SDK

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

Opção 1: baixar o SDK como uma biblioteca estática

Baixe a versão mais recente como uma biblioteca estática.

Opção 2: baixar o SDK usando o Android SDK Manager

No Android Studio:

  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 soma (+) para adicionar 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 em OK para concluir 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 obter instruções sobre o uso do Android SDK Manager como ferramenta independente.

Adicionar o SDK ao projeto

Veja abaixo as instruções para fazer isso no Android Studio. Se estiver usando outra ferramenta, leia as instruções da documentação do Android referentes ao uso da linha de comando.

A Google Maps Android API para o Premium Plan 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). Você pode escolher o formato mais adequado.

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

Faça o seguinte para incluir o pacote aar (google-maps-sdk-m4b.aar) no projeto do Android Studio:

  1. Navegue até o Google Maps APIs Premium Plan no seguinte local:

    <android-sdk>/extras/google/maps_for_business_sdk

  2. Copie o arquivo google-maps-sdk-m4b.aar para o diretório libs do projeto. (crie o diretório, caso ele não exista).

  3. Adicione o código a seguir no arquivo build.gradle:

    dependencies {
        compile(name:'google-maps-sdk-m4b', ext:'aar')
    
    }
    
    repositories {
        flatDir{
            dirs 'libs'
        }
    }
    
  4. Realize as etapas de configuração como descrito abaixo.

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

Em vez de usar o arquivo aar para adicionar o módulo de biblioteca do SDK (google-maps-sdk-m4b_lib) a um projeto do Android Studio, você pode fazer o seguinte:

  1. No Android Studio, selecione 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 uma dependência de módulo ao arquivo build.gradle do aplicativo:

    compile project(':googlemapssdkm4b_lib')

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

  1. Se você já tiver um aplicativo 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 aos atributos XML de layout. Por exemplo: m4b_mapType e m4b_cameraZoom.

Especificar definições no manifesto do arquivo

Um aplicativo Android que usa Google Maps Android API deve especificar as seguintes definições no arquivo de manifesto, AndroidManifest.xml:

Chave de API

Gere uma chave de API para o projeto e adicione-a a AndroidManifest.xml, como descrito no guia de autenticação.

Permissões

Especifique as permissões necessárias para o aplicativo adicionando elementos <uses-permission> como filhos do elemento <manifest> em AndroidManifest.xml.

Permissões de localização

Se o aplicativo acessar a localização atual do usuário ativando a camada My Location, será necessário solicitar permissões de localização como descrito no guia de dados de localização.

Permissão de armazenamento externo

Se você pretende oferecer suporte à versão 8.3 ou posterior do SDK do Google Play Services, não é mais necessária a permissão WRITE_EXTERNAL_STORAGE para usar a Google Maps Android API.

Se você pretende oferecer suporte a versões anteriores do SDK do Google Play Services, é necessário solicitar a permissão android.permission.WRITE_EXTERNAL_STORAGE.

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

Observação: se o aplicativo oferecer suporte ao nível de API 23 (Android 6.0), que exige o uso de permissões em tempo de execução, será necessário oferecer suporte à versão 8.3 ou posterior do SDK do Google Play Services.

Permissões incorporadas automaticamente ao manifesto

As permissões a seguir são definidas no manifesto do Google Play Services e automaticamente incorporadas ao manifesto do aplicativo durante a compilação. Não é necessário adicioná-las explicitamente ao manifesto:

Versão 2 do OpenGL ES

O Google Maps Android API 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 aplicativo em tempo de compilação. Você não precisa adicioná-la explicitamente ao manifesto:

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

Com isso, os serviços externos serão notificados sobre o requisito. Em especial, ela impede a Google Play Store de exibir seu aplicativo em dispositivos não compatíveis com a versão 2 do OpenGL ES.

Adicionar um mapa

A maneira mais fácil de verificar se o aplicativo está configurado corretamente é adicionar um mapa simples.

Observação: esse código não deve ser usado em um aplicativo em fase de produção.

  1. Em activity_main.xml, adicione o fragmento a seguir.

    <?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 código a seguir.

    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);
        }
    }
    

Compilar e executar seu aplicativo

Compile e execute o aplicativo. Um mapa deve ser exibido.

Solução de problemas:

  • Caso o mapa não seja exibido, verifique se você realizou todas as etapas já mencionadas neste documento. Especificamente, verifique se a chave de API está correta e se a conta pode receber o serviço do Google Maps APIs Premium Plan.

  • Se o número de métodos do projeto exceder o limite, poderá ocorrer um erro:

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

    Para saber mais sobre causas e soluções, leia o guia do desenvolvedor Android sobre como criar aplicativos 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 aplicativo

A Android API disponibilizada com o Premium Plan foi projetada para ser bastante semelhante à Google Maps Android API padrão. Sendo assim, o processo de migração é bem simples.

  1. Baixe a Google Maps Android API para o Premium Plan e adicione o SDK ao projeto, como 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 aos atributos XML de layout. Por exemplo: m4b_mapType e m4b_cameraZoom.
  4. Gere uma nova chave de API para o projeto e adicione-a a AndroidManifest.xml, como descrito no guia de autenticação.
  5. Compile o aplicativo.

Comparação de versões

A tabela a seguir descreve as principais diferenças entre o uso da Google Maps Android API padrão e o uso da API com o Premium Plan.

  Google Maps Android API padrão Premium Plan
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. Insira o prefixo m4b_ em todos os nomes de atributo. Por exemplo: m4b_mapType. Para obter mais detalhes, consulte a documentação sobre atributos XML.
Baixar localização Incluída no Google Play Services. Disponível como uma biblioteca estática.
Canais de suporte Suporte da comunidade Acesso a suporte premium
Termos Sujeito aos Termos de serviço das Google Maps APIs. Sujeito aos termos do Google Maps APIs Premium Plan.

Google Play Services

A Google Maps Android API padrão requer o APK e a biblioteca do cliente do Google Play Services. Quando usada com o Google Maps APIs Premium Plan, no entanto, o SDK só exige que o APK do Google Play Services esteja instalado no dispositivo de destino — a biblioteca do cliente não é necessária.

Ao migrar seu aplicativo para o Premium Plan, não é necessário remover o SDK do Google Play Services do projeto. No entanto, é preciso remover todas as referências ao pacote com.google.android.gms.maps. O Google Play Services contém uma versão da Google Maps Android API e de outros serviços do Google. Se você usar o Play Services em um aplicativo para utilizar outras Google APIs, certifique-se de usar apenas o SDK do Premium Plan (o pacote com.google.android.m4b.maps) para acessar o Maps.

Embora a biblioteca do cliente do Google Play Services não seja necessária, pode ser útil incluí-la para poder usar outras Google APIs, como a do Google+ ou a Location API.

Exemplo de código

O repositório do Google Maps no GitHub contém diversos exemplos que demonstram o uso da Google Maps Android API em aplicativos Android. Observe que os aplicativos de exemplo usam o pacote com.google.android.gms.maps e não o pacote com.google.android.m4b.maps usado com o Premium Plan. Os aplicativos de exemplo também exigem o SDK do Google Play Services, pois usam as Location APIs em partes da demonstração.

Além disso, existem snippets de código em todas as páginas do guia do desenvolvedor.

Documentação

A principal fonte de informações sobre o Google Maps APIs Premium Plan é a documentação do desenvolvedor e de referência disponíveis em outros locais do nosso site.