Google Maps Mobile SDK for Work anterior: Android

Para clientes com uma licença anterior do Google Maps APIs for Work ou do Google Maps API for Business, a Google Maps Android API é comprada como parte do Google Maps Mobile SDK for Work. Esta seção da documentação descreve a configuração desse SDK.

Esta página é destinada apenas a clientes que têm uma licença antiga do Maps APIs for Work ou do Maps API for Business. Esta página não se aplica a clientes com o novo Google Maps APIs Premium Plan, disponibilizado em janeiro de 2016.

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 APIs', 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 do Google Maps Mobile SDK for Work 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 Mobile SDK for Work 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.

Obter uma chave de API e adicioná-la ao aplicativo

Gere uma chave de API ao projeto e adicione-a ao AndroidManifest.xml, como descrito a seguir. Você precisa definir uma chave de API restrita ao Android.

A chave de API identifica você como cliente do Google Maps Mobile SDK for Work e ativa o suporte e as cotas adquiridos para o aplicativo. Você pode gerar a chave de API em uma conta com o serviço do Google Maps Mobile SDK ativado usando uma combinação do nome do pacote do aplicativo e de seu certificado digital.

A chave de API é baseada em uma versão reduzida do certificado digital do aplicativo. Todos os aplicativos Android são assinados com um certificado digital para o qual você detém a chave privada. (Consulte o guia do Android sobre assinatura de aplicativos para obter mais informações sobre certificados digitais.)

Exibir as informações do certificado do aplicativo

A restrição de chave da Android API se baseia em uma forma encurtada do certificado digital do seu aplicativo, conhecida como impressão digital SHA-1.

Como obter informações do certificado no Android Studio

Se você seguiu o guia de primeiros passos do Google Maps Android API, o Android Studio criou um arquivo muito útil, chamado google_maps_api.xml com as credenciais do seu aplicativo.

Escolha uma das maneiras a seguir para obter a chave de API no Android Studio:

  • A maneira fácil e rápida: Use o link fornecido no arquivo google_maps_api.xml que o Android Studio criou para você:
    1. Copie o link fornecido no arquivo google_maps_api.xml e cole no navegador. O link leva você ao Google API Console e fornece as informações necessárias ao Google API Console por meio de parâmetros de URL, reduzindo assim a necessidade de inserção manual.
    2. Siga as instruções para criar um novo projeto no Google API Console ou selecione um projeto existente.
    3. Crie uma chave de API restrita ao Android para o seu projeto.
    4. Copie a chave de API gerada, volte ao Android Studio e cole-a no elemento <string> do arquivo google_maps_api.xml.
  • Uma maneira que demora um pouco mais: Use as credenciais presentes no arquivo google_maps_api.xml que o Android Studio criou para você:
    1. Copie as credenciais presentes no arquivo google_maps_api.xml.
    2. Acesse o Google API Console no navegador.
    3. Use as credenciais copiadas para adicionar o aplicativo a uma chave de API ou criar uma nova chave de API.

Como obter informações do certificado por conta própria

Se você não seguiu o guia de primeiros passos ao criar o aplicativo, precisa obter a impressão digital SHA-1 para o certificado por conta própria. Primeiro, verifique se você está usando o certificado correto. Você pode ter dois certificados:

  • Um certificado de depuração: as ferramentas do Android SDK geram esse certificado automaticamente quando você cria uma versão de depuração. Use esse certificado apenas com aplicativos que esteja testando. Não tente publicar um aplicativo que esteja assinado com um certificado de depuração. O certificado de depuração é descrito em mais detalhes em Assinatura em modo de depuração na Documentação do Desenvolvedor para Android.
  • Um certificado de publicação: as ferramentas do Android SDK geram esse certificado quando você cria uma versão para publicação. Você também pode gerar esse certificado usando o programa keytool. Use esse certificado quando estiver pronto para lançar seu aplicativo para o mundo.

Realize as etapas abaixo para exibir a impressão digital SHA-1 de um certificado usando o programa keytool com o parâmetro -v. Para saber mais sobre o Keytool, consulte a documentação da Oracle.

Certificado de depuração

Exibir a impressão digital do certificado de depuração

  1. Localize o arquivo de armazenamento de chaves de depuração. O nome do arquivo é debug.keystore e ele é criado na primeira compilação do projeto. Por padrão, ele fica armazenado no mesmo diretório que os arquivos do Android Virtual Device (AVD):

    • macOS e Linux: ~/.android/
    • Windows Vista e Windows 7: C:\Users\your_user_name\.android\
  2. Liste a impressão digital SHA-1:

    • Para Linux ou macOS, abra uma janela do terminal e digite o seguinte:

      keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    • Para Windows Vista e Windows 7, execute:

      keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

Você deverá obter uma saída similar a:

Alias name: androiddebugkey
Creation date: Jan 01, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4aa9b300
Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033
Certificate fingerprints:
     MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9
     SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75
     Signature algorithm name: SHA1withRSA
     Version: 3
Certificado de publicação

Exibir a impressão digital do certificado de publicação

  1. Localize o arquivo de armazenamento de chaves do certificado de publicação. Não há local nem nome padrão para o armazenamento de chaves de publicação. Se não especificá-los ao compilar o aplicativo para lançamento, a versão deixará o .apk sem assinar e você terá que assiná-lo antes da publicação. Para o certificado de publicação, você também precisa do alias do certificado e das senhas do armazenamento de chaves e do certificado. Você pode listar os aliases de todas as chaves em um armazenamento de chaves digitando:

    keytool -list -keystore your_keystore_name

    Substitua your_keystore_name pelo caminho totalmente qualificado e o nome do armazenamento de chaves, incluindo a extensão .keystore. Será solicitada a senha do armazenamento de chaves. Em seguida, o keytool exibe todos os aliases no armazenamento de chaves.

  2. Digite o seguinte em um terminal ou prompt de comando:

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    Substitua your_keystore_name pelo caminho totalmente qualificado e o nome do armazenamento de chaves, incluindo a extensão .keystore. Substitua your_alias_name pelo alias que você atribuiu ao certificado ao criá-lo.

Você deverá obter uma saída similar a:

Alias name: <alias_name>
Creation date: Feb 02, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4cc9b300
Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
Certificate fingerprints:
    MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
    SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
    Signature algorithm name: SHA1withRSA
    Version: 3

A linha que inicia com SHA1 contém a impressão digital SHA-1 do certificado. A impressão digital é a sequência de 20 números hexadecimais de dois dígitos separados por vírgulas.

Consulte o guia do Android para aprender a assinar aplicativos e saber mais sobre os certificados digitais.

Verifique se a conta está ativada para o serviço do

Google Maps Mobile SDKA equipe do

Google Maps Mobile SDK ativa o serviço do Google Maps Mobile SDKquando você se inscreve no Google Maps Mobile SDK for Work. O serviço é ativado em um novo projeto. Em seguida, você pode obter uma chave de API no Google API Console.

Observação: somente o proprietário inicial do projeto poderá ver o serviço Google Maps Mobile SDK. Para solicitar autorização para que mais proprietários do projeto vejam o serviço, registre um caso não técnico no Google Cloud Support Portal.

Verifique se a conta foi ativada da seguinte forma:

  1. Acesse o Google API Console e faça login com a conta do Google.
  2. Selecione o projeto do Google Maps Mobile SDK for Work criado quando você comprou o Google Maps Mobile SDK for Work. O nome do projeto é iniciado por Google Maps APIs for Business or Google Maps for Work or Google Maps. Se você ainda não adquiriu o acesso ao SDK, entre em contato com o [departamento de vendas].
  3. No Dashboard, na lista de APIs, verifique se o Google Maps Mobile SDK* está ativado.

Obter uma chave de API no Google API Console

Depois que o serviço do Google Maps Mobile SDK for Work for ativado para o projeto, será preciso gerar uma nova chave.

  1. Acesse a página de credenciais do Google API Console e faça login com a conta do Google.
  2. Selecione o projeto do Google Maps Mobile SDK for Work que foi criado quando você comprou o Google Maps Mobile SDK for Work. O nome do projeto é iniciado por Google Maps APIs for Business or Google Maps for Work or Google Maps. Se você ainda não adquiriu o acesso ao SDK, entre em contato com o [departamento de vendas].
  3. Na lista de chaves de API, procure uma chave com restrição ao Android.
  4. Se o projeto ainda não tiver uma chave de API restrita ao Android, crie uma agora selecionando Create credentials > API key.
  5. Na caixa de diálogo exibida, selecione Restrict key.
  6. Na seção Restrictions, selecione Android apps e insira a impressão digital SHA-1 e o nome do pacote do aplicativo. Por exemplo:

    BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
    com.example.android.mapexample
    
  7. Clique em Save.

    A nova chave de API restrita ao Android aparece na lista de chaves de API do projeto. Uma chave de API é uma string de caracteres, similar a:

    AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
    

Adicionar a chave de API ao aplicativo

Siga as etapas abaixo para incluir a chave de API no manifesto do seu aplicativo, contido no arquivo AndroidManifest.xml.

  1. Em AndroidManifest.xml, adicione o seguinte elemento como filho do elemento <application>, inserindo antes da tag de fechamento </application>:
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="YOUR_API_KEY"/>
        

    Substitua sua chave de API por YOUR_API_KEY no atributo value. Esse elemento define a chave com.google.android.geo.API_KEY como o valor da sua chave de API.

  2. Salve AndroidManifest.xml e recompile o aplicativo.

Observação: como é mostrado acima, com.google.android.geo.API_KEY é o nome de metadados recomendado para a chave de API. Uma chave com esse nome pode ser usada para autenticação em várias APIs do Google Maps na plataforma Android, incluindo a Google Maps Android API. Para garantir a compatibilidade com versões anteriores, a API também permite o nome com.google.android.maps.v2.API_KEY. Esse nome herdado permite autenticação apenas na Android Maps API v2. Um aplicativo pode especificar apenas um dos nomes de metadados da chave de API. Se ambos forem especificados, a API gerará uma exceção.

Especificar permissões de aplicativos

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:

Especificar OpenGL ES versão 2

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 Mobile SDK for Work.

  • 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 Google Maps Mobile SDK for Work 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 Google Maps Mobile SDK for Work 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 Google Maps Mobile SDK for Work.

  Google Maps Android API padrão Google Maps Mobile SDK for Work
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.
Local do download Incluída com o 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 Mobile SDK for Work.

Google Play Services

A Google Maps Android API padrão requer o APK e a biblioteca do cliente do Google Play Services. No entanto, quando usado com o Google Maps Mobile SDK for Work, o SDK exige apenas a que o APK do Google Play Services esteja instalado no dispositivo de destino. A biblioteca cliente não é necessária.

Na migração do aplicativo para o Google Maps Mobile SDK for Work, 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 Google Play Service em um aplicativo para utilizar outras Google APIs, certifique-se de usar apenas o SDK do Google Maps Mobile SDK for Work (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 Google Maps Mobile SDK for Work. 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 Mobile SDK for Worké a documentação do desenvolvedor e de referência disponíveis em outros locais do nosso site.