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

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 (Android 5.0 Lollipop) 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.

      Adicione uma atividade no Google Maps.

    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:

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:

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:

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:

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

    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 a propriedade secrets não existir, 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")
}

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

Captura de tela com o mapa e o marcador centralizados em Sydney, Austrália.

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.