Crie um app Android que exiba um mapa usando o modelo do Google Maps para o Android Studio. Se você quiser configurar um projeto do Android Studio, consulte Configuração do projeto.
Este guia de início rápido é destinado a desenvolvedores familiarizados com o desenvolvimento básico no Android com Java ou Kotlin.
Configurar o ambiente para desenvolvedores
O Android Studio é obrigatório. Faça o download e instale esse ambiente de desenvolvimento integrado, caso ainda não tenha feito isso.
Adicione o SDK do Google Play Services ao Android Studio. O SDK do Maps para Android é distribuído como parte do SDK do Google Play Services, que você pode adicionar usando o SDK Manager.
Configurar um dispositivo Android
Para executar um app que usa o SDK do Maps para Android, você precisa implantá-lo 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.
Criar um projeto do Google Maps no Android Studio
Abra o Android Studio e clique em Create New Project na janela Welcome to Android Studio.
Na janela New Project, na categoria Phone and Tablet, selecione a Google Maps Activity e clique em Next.
Preencha o formulário Google Maps Activity:
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 18.0.x, que atualmente é a API de nível 19 (Android 4.4, KitKat) ou mais atual. Consulte as notas da versão para ver as informações mais recentes sobre os requisitos da versão do SDK.
Clique em Finish.
O Android Studio inicia o Gradle e cria o projeto. Isso pode levar algum tempo.
Quando a criação terminar, o Android Studio vai abrir os arquivos
google_maps_api.xmleMapsActivity. O nome da atividade pode ser diferente, mas é igual ao que você definiu durante a configuração.O arquivo
google_maps_api.xmlcontém instruções sobre como gerar uma chave da API Google Maps para adicionar ao arquivo. Não inclua sua chave de API no arquivogoogle_maps_api.xml, porque isso reduz a segurança do armazenamento. Sendo assim, siga as etapas nas próximas seções para criar um projeto do Cloud e configurar uma chave de API.
Configurar no Console do Cloud
Conclua as etapas necessárias de configuração do Console do Cloud clicando nas seguintes guias:
Etapa 1
Console
-
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.
-
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 custo financeiro. 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 do Cloud
gcloud projects create "PROJECT"
Leia mais sobre o SDK do Google Cloud, a instalação do SDK do 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
SDK do Cloud
gcloud services enable \
--project "PROJECT" \
"maps-android-backend.googleapis.com"
Leia mais sobre o SDK do Google Cloud, a instalação do SDK do 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
-
Acesse a página Plataforma Google Maps > Credenciais.
-
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. -
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 do Cloud
gcloud alpha services api-keys create \
--project "PROJECT" \
--display-name "DISPLAY_NAME"
Leia mais sobre o SDK do Google Cloud, a instalação do SDK do 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 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.gradleno nível do projeto e adicione o seguinte código ao elementodependenciesembuildscript.buildscript { dependencies { // ... classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0" } } - Depois, abra o arquivo
build.gradleno 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.propertiesno diretório do nível do projeto e adicione o seguinte código. SubstituaYOUR_API_KEYpela sua chave de API.MAPS_API_KEY=YOUR_API_KEY - Salve o arquivo.
- No seu arquivo
AndroidManifest.xml, acessecom.google.android.geo.API_KEYe atualizeandroid:value attributeda 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.
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 contém o código para gerenciar e exibir 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
SupportMapFragmentgerencia o ciclo de vida do mapa e é o elemento pai da IU do app.O objeto
GoogleMapfornece 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 objetosSupportMapFragmenteGoogleMapem mais detalhes.A função
moveCameracentraliza o mapa nas coordenadasLatLngpara 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
addMarkeradiciona um marcador às coordenadas de Sydney. Consulte o guia Marcadores para mais detalhes.
O arquivo de atividades no Google Maps contém o seguinte código:
Java
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;
public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {
private GoogleMap mMap;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_maps);
// Obtain the SupportMapFragment and get notified when the map is ready to be used.
SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
.findFragmentById(R.id.map);
mapFragment.getMapAsync(this);
}
/**
* Manipulates the map once available.
* This callback is triggered when the map is ready to be used.
* This is where we can add markers or lines, add listeners or move the camera. In this case,
* we just add a marker near Sydney, Australia.
*
* If Google Play services is not installed on the device, the user will be prompted to install
* it inside the SupportMapFragment. This method will only be triggered once the user has
* installed Google Play services and returned to the app.
*/
@Override
public void onMapReady(GoogleMap googleMap) {
mMap = googleMap;
// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
mMap.addMarker(new MarkerOptions()
.position(sydney)
.title("Marker in Sydney"));
mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
}
}
Kotlin
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions
internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {
private lateinit var mMap: GoogleMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_maps)
// Obtain the SupportMapFragment and get notified when the map is ready to be used.
val mapFragment = supportFragmentManager
.findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)
}
/**
* Manipulates the map once available.
* This callback is triggered when the map is ready to be used.
* This is where we can add markers or lines, add listeners or move the camera. In this case,
* we just add a marker near Sydney, Australia.
* If Google Play services is not installed on the device, the user will be prompted to install
* it inside the SupportMapFragment. This method will only be triggered once the user has
* installed Google Play services and returned to the app.
*/
override fun onMapReady(googleMap: GoogleMap) {
mMap = googleMap
// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
mMap.addMarker(MarkerOptions()
.position(sydney)
.title("Marker in Sydney"))
mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
}
}
Arquivo Gradle do módulo
O arquivo build.gradle do módulo inclui a seguinte dependência do Maps, que é exigida pelo SDK do Maps para Android.
dependencies {
implementation 'com.google.android.gms:play-services-maps:18.0.2'
// ...
}
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 IU do app. Ele fica no diretório res/layout.
O arquivo activity_maps.xml declara um fragmento que inclui os seguintes elementos:
tools:contextdefine a atividade padrão do fragmento comoMapsActivity, que é definida no arquivo de atividades no Google Maps.android:namedefine o nome de classe do fragmento comoSupportMapFragment, 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:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:id="@+id/map"
tools:context=".MapsActivity"
android:name="com.google.android.gms.maps.SupportMapFragment" />
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:
- No Android Studio, clique na opção de menu Run ou no ícone do botão de reprodução para executar o app.
- 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.
- Clique em OK. O Android Studio executará o Gradle para criar o app e exibir 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 IU e os gestos.
Adicionar um mapa ao seu app Android (Kotlin): este codelab mostra como criar um app usando alguns recursos adicionais do SDK do Maps para Android.
Usar a biblioteca Android KTX do Maps: essa biblioteca de extensões Kotlin (KTX) permite que você aproveite vários recursos na linguagem Kotlin ao usar o SDK do Maps para Android.