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

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

   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 seguinte código 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 como 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.

   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.

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

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle.kts or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

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

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.