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.

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 compatível ou Android Emulator com base no Android 5.0 ou uma versão mais recente 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.

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 na 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ê precisa 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 (Lollipop e Android 5.0) ou mais atual. Consulte as notas de lançamento para conferir as informações mais recentes sobre os requisitos da versão do SDK.

   • 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.

Configurar seu projeto do Google Cloud

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

gcloud projects create "PROJECT"

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

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

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.

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

   plugins {
       alias(libs.plugins.android.application) apply false
       alias(libs.plugins.jetbrains.kotlin.android) apply false
       alias(libs.plugins.kotlin.compose) apply false
       alias(libs.plugins.secrets.gradle.plugin) apply false
   }

   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 seguinte código ao elemento plugins.

   Kotlin

   plugins {
       // ...
       alias(libs.plugins.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 como 34.
4. 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.

   MAPS_API_KEY=YOUR_API_KEY

6. 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.

   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.

7. 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árias APIs do Google Maps na plataforma Android, incluindo o SDK do Maps para Android. Para garantir a compatibilidade com versões anteriores, a API também aceita o nome com.google.android.maps.v2.API_KEY. Esse nome herdado permite autenticação apenas na API Android Maps v2. Um aplicativo pode especificar somente um dos nomes de metadados da chave de API. Se ambos forem especificados, a API vai gerar uma exceção.

8. No Android Studio, abra o arquivo build.gradle.kts ou build.gradle no nível do módulo e edite a propriedade secrets. Se a propriedade secrets não existir, adicione-a.

   Edite as propriedades do plug-in para definir propertiesFileName como secrets.properties, defaultPropertiesFileName como local.defaults.properties e 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"
   }
           

   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"
   }
           

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(libs.play.services.maps)
}

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.