Configurar um projeto do Android Studio

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

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

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()
    }
} 
```
No arquivo settings.gradle de nível superior, inclua o repositório Maven do Google e o repositório Maven central (links em inglês) no bloco dependencyResolutionManagement:
```
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
} 
```
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'
    // ...
} 
```
No arquivo build.gradle no nível do módulo, defina compileSdk e minSdk como os seguintes valores:
Observação: verifique se compileSdk está definido como 31 ou mais alto, e se minSdk está definido como 19 ou mais alto.
```
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:

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
}
```
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'
    
```
Salve o arquivo e sincronize seu projeto com o Gradle.
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
    
```
Salve o arquivo.
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 dispositivo, 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.
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:

Próximas etapas

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