Configurar um projeto do Android Studio

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Nesta página, descrevemos como configurar um projeto do Android Studio para usar o SDK do Maps para Android sem o modelo do Google Maps detalhado no guia de início rápido.

O modelo do Google Maps configura e adiciona automaticamente um mapa básico a um novo projeto do Android Studio. No entanto, você também pode adicionar um mapa a um projeto Android com um modelo diferente do Android Studio. Para fazer isso, é preciso configurar manualmente seu projeto e adicionar o mapa.

Etapa 1: configurar o Android Studio

  1. É preciso usar o Android Studio Arctic Fox ou versões mais recentes. Faça o download e instale o Android Studio, caso ainda não tenha feito isso.
  2. Verifique se você está usando o Plug-in do Android para Gradle versão 7.0 ou mais recente no Android Studio.

Etapa 2: configurar o SDK

A biblioteca do SDK do Maps para Android está disponível no repositório Maven do Google. Para adicionar o SDK ao app, faça o seguinte:

  1. No arquivo settings.gradle de nível superior, inclua o portal do plug-in do Gradle, o repositório Maven do Google e o repositório Maven central no bloco pluginManagement. O bloco pluginManagement precisa aparecer antes de qualquer outra instrução no script.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. No arquivo settings.gradle de nível superior, inclua o repositório Maven do Google e o repositório Maven central no bloco dependencyResolutionManagement:
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. No arquivo build.gradle no nível do módulo, adicione a dependência do Google Play Services no SDK do Maps para Android.
    dependencies {
        implementation 'com.google.android.gms:play-services-maps:18.1.0'
        // ...
    } 
  4. No arquivo build.gradle no nível do módulo, defina compileSdk e minSdk como os seguintes valores:
    android {
        compileSdk 31
    
        defaultConfig {
            minSdk 19
            // ...
        }

Etapa 3: adicionar sua chave de API ao projeto

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 local.properties, que fica no diretório raiz do projeto. Para saber mais sobre o arquivo local.properties, consulte Arquivos de propriedades do Gradle.

Se quiser otimizar essa tarefa, use o plug-in Secrets Gradle para Android. Para instalar o plug-in e armazenar sua chave de API, siga estas instruções:

  1. No Android Studio, abra o arquivo build.gradle no nível do projeto e adicione o seguinte código ao elemento dependencies em buildscript.
    plugins {
        // ...
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
    }
  2. Depois, abra o arquivo build.gradle no nível do módulo e adicione o seguinte código ao elemento plugins.
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. Salve o arquivo e sincronize seu projeto com o Gradle.
  4. Abra o local.properties no diretório do nível do projeto e adicione o seguinte código. Substitua YOUR_API_KEY pela sua chave de API.
    MAPS_API_KEY=YOUR_API_KEY
        
  5. Salve o arquivo.
  6. No seu arquivo AndroidManifest.xml, acesse com.google.android.geo.API_KEY e atualize android:value attribute da seguinte maneira:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Observação: conforme 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 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.

Etapa 4: atualizar o manifesto do app

Nesta seção, falamos sobre as configurações que você pode adicionar ao seu arquivo AndroidManifest.xml.

Número da versão do Google Play Services

Inclua a seguinte declaração no elemento application. Isso incorpora a versão do Google Play Services com que o app foi compilado.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Permissão de localização

Caso o app tenha que acessar o local do usuário, você precisa pedir a permissão no arquivo AndroidManifest.xml. As opções são ACCESS_FINE_LOCATION, que fornece a localização exata do usuário, e ACCESS_COARSE_LOCATION, que tem uma precisão menor. Para saber mais detalhes, consulte o guia de dados de localização.

Para pedir a permissão de ACCESS_FINE_LOCATION, adicione este código ao elemento manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Permissão de armazenamento externo

Se você segmentar a versão 8.3 ou mais recente do SDK do Google Play Services, a permissão WRITE_EXTERNAL_STORAGE deixa de ser necessária. Caso segmente versões anteriores do SDK do Google Play Services, você precisa pedir a permissão WRITE_EXTERNAL_STORAGE no elemento manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Biblioteca legada Apache HTTP

Se você estiver usando a com.google.android.gms:play-services-maps:16.0.0 ou versões anteriores e seu app segmentar o nível da API 28 (Android 9.0) ou mais recente, vai ser necessário incluir a seguinte declaração no elemento <application> do AndroidManifest.xml. Caso contrário, pule esta declaração.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Etapa 5: 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 4.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.

Próximas etapas

Depois de configurar o projeto, você poderá adicionar um mapa.