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 blocopluginManagement
. O blocopluginManagement
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 no blocodependencyResolutionManagement
: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.0.2' // ... }
- No arquivo
build.gradle
no nível do módulo, definacompileSdk
eminSdk
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 usada como referência de maneira segura 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 elementodependencies
embuildscript
.id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
- Depois, abra o arquivo
build.gradle
no nível do módulo e adicione o seguinte código ao elementoplugins
.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. SubstituaYOUR_API_KEY
pela sua chave de API.MAPS_API_KEY=YOUR_API_KEY
- Salve o arquivo.
- No seu arquivo
AndroidManifest.xml
, acessecom.google.android.geo.API_KEY
e atualizeandroid: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 a localização do usuário, você precisará solicitar 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 solicitar a permissão do 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, será preciso solicitar 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, 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, você precisa fazer a implantação 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.