Guia de início rápido do SDK do Maps para Android

Crie um app Android que mostre um mapa usando o modelo de visualizações do Google Maps para o Android Studio. Se você quiser configurar um projeto do Android Studio, consulte Configurar um projeto do Android Studio.

Este guia de início rápido é destinado a desenvolvedores familiarizados com o desenvolvimento básico no Android com Kotlin ou Java.

Sobre o ambiente de desenvolvimento

Este guia de início rápido foi desenvolvido usando o Android Studio Hedgehog e a versão 8.2 do Plug-in do Android para Gradle.

Observação: se o seu ambiente de desenvolvimento usa uma versão diferente do Android Studio ou do Gradle, recomendamos seguir as etapas respeitando suas necessidades. Para mais informações sobre as versões do Android Studio e do Gradle, consulte Compatibilidade entre o Plug-in do Android para Gradle e o Android Studio.

Configurar um dispositivo Android

Para executar um app que usa o SDK do Maps para Android, faça a implantação dele em um dispositivo Android ou Android emulador baseado no Android 5.0 ou superior e que inclua as APIs do Google.

• Para usar um dispositivo Android, siga as instruções no artigo Executar apps em um dispositivo de hardware.
• Para usar o Android Emulator, crie um dispositivo virtual e instale o emulador usando o AVD Manager que acompanha o Android Studio.
  Observação: se você quiser usar um Android Emulator, selecione um dispositivo com o ícone do Google Play , mostrado na coluna Play Store. Esse ícone indica que os perfis obedecem completamente ao CTS e podem usar imagens do sistema que incluem o app Play Store:

  

Criar um projeto do Google Maps no Android Studio

O procedimento para criar um projeto do Google Maps no Android Studio mudou na versão Flamingo e nas mais recentes do Android Studio.

1. Abra o Android Studio e clique em New Project no Janela Welcome to Android Studio.

2. Na janela New Project, na categoria Phone and Tablet, selecione a No Activity e clique em Next.

3. Preencha o formulário New Project:

   • Defina Language como Java ou Kotlin. As duas linguagens são totalmente compatíveis com o SDK do Maps para Android. Para saber mais sobre o Kotlin, consulte Desenvolver apps Android com Kotlin.

   • Defina Minimum SDK como uma versão do SDK compatível com seu dispositivo de teste. Você deve selecionar uma versão mais recente do que a mínima exigida pelo SDK do Maps para Android versão 19.0.x, que é a API de nível 21 do Android ("Lollipop"; Android 5.0) ou mais recente. Consulte as notas de lançamento para conferir as informações mais recentes sobre os requisitos da versão do SDK.

     Observação: se você não souber qual versão do SDK escolher, selecione o link Help me choose para consultar informações de distribuição sobre os SDKs do Android compatíveis. Por exemplo, se você escolher Android API de nível 21 ("Lollipop"; Android 5.0), o app precisa funcionar em mais de 99% dos dispositivos Android.

   • Defina a linguagem de configuração do build como Kotlin DSL ou Groovy DSL. Os snippets das duas linguagens de configuração são mostrados nos procedimentos a seguir.

4. Clique em Finish.

   O Android Studio inicia o Gradle e cria o projeto. Isso pode levar algum tempo.

5. Adicione Google Maps Views Activity:

   1. Clique com o botão direito na pasta app do seu projeto.

   2. Selecione New > Google > Google Maps Views Activity.

      

   3. Na caixa de diálogo New Android Activity, selecione a caixa de seleção Launcher Activity.

   4. Selecione Finish.

      Para mais informações, confira Adicionar código de um modelo

6. Quando a criação terminar, o Android Studio vai abrir os arquivos AndroidManifest.xml e MapsActivity. O nome da atividade pode ser diferente, mas é aquele que você definiu durante a configuração.

   Atenção: o arquivo AndroidManifest.xml contém instruções sobre como conseguir uma chave da API Google Maps e adicioná-la ao arquivo local.properties. Não adicione sua chave de API ao arquivo local.properties porque isso reduz a segurança do armazenamento. Em vez disso, siga as instruções em Configurar seu projeto do Google Cloud para criar um projeto e configurar uma chave de API.

Configurar seu projeto do Google Cloud

Conclua as etapas necessárias de configuração do console do Cloud clicando nas seguintes guias:

Etapa 1

Console

1. No console do Google Cloud, mais especificamente na página do seletor de projetos, clique em Criar projeto para elaborar um novo projeto do Cloud.

   Acessar a página do seletor de projetos

2. Verifique se o faturamento está ativado para seu projeto do Cloud. Confirme se o faturamento está ativado no projeto.

   É possível testar o Google Cloud sem pagar nada. O teste expira em 90 dias ou quando a conta acumular US$ 300 em cobranças, o que ocorrer primeiro. É possível cancelar a qualquer momento. A Plataforma Google Maps disponibiliza um crédito mensal recorrente de US$ 200. Para mais informações, consulte Créditos da conta de faturamento e Faturamento.

SDK Cloud

gcloud projects create "PROJECT"

Saiba mais sobre o SDK Google Cloud, a instalação do SDK Cloud e os seguintes comandos:

• gcloud projects create

Observação: se você não pretende manter os recursos criados neste exercício, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir o exercício, exclua o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

Etapa 2

Para utilizar a Plataforma Google Maps, ative as APIs ou os SDKs que você planeja usar com seu projeto.

Console

Ativar o SDK do Maps para Android

SDK Cloud

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

Saiba mais sobre o SDK Google Cloud, a instalação do SDK Cloud e os seguintes comandos:

• gcloud services enable
• gcloud services disable

Etapa 3

Essa etapa só passa pelo processo de criação da chave de API. Se você usa sua chave de API na produção, recomendamos restringi-la. Para mais informações, consulte a página Como usar chaves de API específica do produto.

A chave de API é um identificador exclusivo que autentica solicitações associadas ao seu projeto para fins de uso e faturamento. Você precisa ter pelo menos uma chave de API associada ao projeto.

Para criar uma chave de API, siga estas etapas:

Console

1. Acesse a página Plataforma Google Maps > Credenciais.

   Acessar a página "Credenciais"

2. Na página Credenciais, clique em Criar credenciais > Chave de API.
   A caixa de diálogo Chave de API criada exibirá sua chave recém-criada.
3. Clique em Fechar.
   A nova chave vai aparecer na página Credenciais, em Chaves de API.
   Lembre-se de restringir a chave de API antes de usar na produção.

SDK Cloud

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Saiba mais sobre o SDK Google Cloud, a instalação do SDK Cloud e os seguintes comandos:

• gcloud alpha services api-keys create

Adicionar a chave de API ao seu app

Nesta seção, descrevemos como armazenar sua chave de API para que ela possa ser referenciada com segurança pelo seu app. Não faça a verificação dela no sistema de controle de versões. Recomendamos armazenar no arquivo secrets.properties, que fica no diretório raiz do projeto. Para saber mais sobre o arquivo secrets.properties, consulte Arquivos de propriedades do Gradle.

Se quiser otimizar essa tarefa, use o plug-in Secrets Gradle para Android.

Observação: consulte a documentação do plug-in Secrets Gradle para Android (link em inglês) no GitHub para conferir os requisitos mais recentes do sistema e instruções de instalação.

Para instalar esse plug-in no seu projeto do Google Maps:

1. No Android Studio, abra o arquivo de nível superior build.gradle.kts ou build.gradle e adicione o seguinte código ao elemento dependencies em buildscript.

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }
   

2. Abra o arquivo build.gradle.kts ou build.gradle no nível do módulo e adicione o código a seguir ao elemento plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. No arquivo build.gradle.kts ou build.gradle no nível do módulo, verifique se targetSdk e compileSdk estão definidos para 34.
4. Salve o arquivo e sincronize seu projeto com o Gradle.
5. Abra o arquivo secrets.properties no seu diretório de nível superior e adicione o código a seguir. Substitua YOUR_API_KEY pela sua chave de API. Armazene sua chave nesse arquivo porque secrets.properties não é verificado em um sistema de controle de versões.
   Observação: se o arquivo secrets.properties não existe, crie-o na mesma pasta que o arquivo local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Salve o arquivo.

7. Crie o arquivo local.defaults.properties no seu diretório de nível superior, na mesma pasta que o arquivo secrets.properties, e depois adicione o seguinte código.

   Observação: insira o código conforme mostrado. Não substitua DEFAULT_API_KEY pela sua chave de API.

   MAPS_API_KEY=DEFAULT_API_KEY

   O objetivo desse arquivo é oferecer um local de backup para a chave da API se o arquivo secrets.properties não for encontrado, para que os builds não apresentem falha. Isso pode acontecer se você clonar o app de um sistema de controle de versões que omite secrets.properties e ainda não tiver criado um arquivo secrets.properties localmente para fornecer sua chave de API.

8. Salve o arquivo.
9. No seu arquivo AndroidManifest.xml, vá até com.google.android.geo.API_KEY e atualize android:value attribute. Se a tag <meta-data> não existe, crie-a como um elemento filho da tag <application>.

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   Observação: 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 autenticar vários APIs do Google Maps na plataforma Android, incluindo as SDK do Maps para Android. Para garantir a compatibilidade com versões anteriores, a API também suporta o nome com.google.android.maps.v2.API_KEY. O fluxo de trabalho permite a autenticação apenas na API Android Maps v2. Um aplicativo pode especificar apenas um dos nomes de metadados da chave de API. Se ambos forem especificados, a API gera uma exceção.

10. No Android Studio, abra o nível do módulo build.gradle.kts ou build.gradle e edite a propriedade secrets. Se o A propriedade secrets não existe, adicione-a.

    Edite as propriedades do plug-in para definir propertiesFileName como secrets.properties, defina defaultPropertiesFileName como local.defaults.properties e defina outras propriedades.

    Kotlin

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Groovy

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

Analisar o código

Examine o código fornecido no modelo. Mais especificamente, avalie os arquivos a seguir no projeto do Android Studio.

Arquivo de atividades no Google Maps

O arquivo de atividades no Google Maps é a principal atividade do app e inclui o código para gerenciar e mostrar o mapa. Por padrão, o arquivo que define a atividade é denominado MapsActivity.java ou, se você definir o Kotlin como a linguagem do app, MapsActivity.kt.

Os principais elementos das atividades do Google Maps:

• O objeto SupportMapFragment gerencia o ciclo de vida do mapa e é o elemento pai da interface do app.

• O objeto GoogleMap fornece acesso aos dados e à visualização do mapa. Esta é a classe principal do SDK do Maps para Android. O guia Objetos do mapa descreve os objetos SupportMapFragment e GoogleMap em mais detalhes.

• A função moveCamera centraliza o mapa nas coordenadas LatLng para Sydney, na Austrália. As primeiras configurações a serem definidas ao adicionar um mapa geralmente incluem a localização dele e as configurações da câmera, como ângulo de visão, orientação e nível de zoom. Consulte o guia Câmera e visualização para ver mais detalhes.

• A função addMarker adiciona um marcador às coordenadas de Sydney. Consulte o guia Marcadores para mais detalhes.

Arquivo Gradle do módulo

O arquivo build.gradle.kts do módulo inclui a seguinte dependência do Maps, que é exigida pelo SDK do Maps para Android.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Observação: a versão exata pode mudar com base na versão atual do SDK do Maps para Android.

Para saber mais sobre como gerenciar a dependência do Maps, consulte Controle de versões.

Arquivo de layout XML

O activity_maps.xml é o arquivo de layout XML que define a estrutura da interface do app. Ele fica no diretório res/layout. O arquivo activity_maps.xml declara um fragmento que inclui os seguintes elementos:

• tools:context define a atividade padrão do fragmento como MapsActivity, que é definida no arquivo de atividades no Google Maps.
• android:name define o nome de classe do fragmento como SupportMapFragment, que é o tipo de fragmento usado no arquivo de atividades no Google Maps.

O arquivo de layout XML contém o seguinte código:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Implantar e executar o app

Quando o app for executado, ele exibirá um mapa centralizado em Sydney, na Austrália, com um marcador na cidade, como mostra a captura de tela a seguir.

Para implantar e executar o app:

1. No Android Studio, clique na opção de menu Run ou no ícone do botão de reprodução para executar o app.
2. Na hora de escolher um dispositivo, selecione uma das seguintes opções:
   • Selecione o dispositivo Android conectado ao computador.
   • Você também pode selecionar o botão de opção Launch emulator e escolher o dispositivo virtual configurado.
3. Clique em OK. O Android Studio vai executar o Gradle para criar o app e mostrar os resultados no seu dispositivo ou emulador. O app pode levar alguns minutos até abrir.

Próximas etapas

• Configurar um mapa: este tópico descreve como definir as configurações iniciais e de tempo de execução, como a posição da câmera, o tipo de mapa, os componentes da interface e os gestos.

• Adicionar um mapa ao seu app Android (Kotlin): este codelab mostra um app que apresenta alguns outros recursos do SDK do Maps para Android.

• Usar a biblioteca Android KTX do Maps: esta biblioteca de extensões Kotlin (KTX) permite que você aproveite vários recursos na linguagem Kotlin ao usar o SDK do Maps para Android.