Guia de início rápido do SDK do Maps para Android

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

  1. O Android Studio é obrigatório. Faça o download e instale esse ambiente de desenvolvimento integrado, caso ainda não tenha feito isso.

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

Criar um projeto do Google Maps

  1. Abra o Android Studio e clique em Create New Project na janela Welcome to Android Studio.

  2. Na janela New Project, na categoria Phone and Tablet, selecione a Google Maps Activity e clique em Next.

  3. 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 do Android compatível com seu dispositivo de teste.

  4. Clique em Finish.

Quando você terminar de criar o projeto, o Android Studio abrirá o Gradle e criará o projeto. Isso pode levar algum tempo. Quando a criação terminar, o Android Studio abrirá os arquivos google_maps_api.xml e MapsActivity. O nome da atividade pode ser diferente, mas corresponde àquele que você definiu durante a configuração.

Para mais informações sobre como criar um projeto, consulte Criar um projeto no Android.

O arquivo google_maps_api.xml contém instruções sobre como gerar uma chave da API Google Maps e adicioná-la ao arquivo. Não adicione sua chave de API ao arquivo, porque isso reduz a segurança do armazenamento. Sendo assim, siga as instruções na próxima seção.

Configurar no Console do 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.

    O Google Cloud oferece US$ 300 para um teste gratuito, e a Plataforma Google Maps, 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

Ativar o SDK do Maps para Android

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

  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 aparecerá na página Credenciais, em Chaves de API.
    Lembre-se de restringir a chave de API antes de usá-la 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 mais segurança pelo seu app. Não faça a verificação dela no sistema de controle de versões. Recomendamos armazená-la no arquivo local.properties, que fica no diretório raiz do projeto. Para saber mais sobre o arquivo local.properties, consulte Arquivos de propriedade do Gradle.

Para 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 raiz e adicione o seguinte código ao elemento dependencies no buildscript.
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
        }
    }
        
  2. Depois, abra o arquivo build.gradle no nível do app 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 e sincronize seu projeto com o Gradle.
  6. No seu arquivo AndroidManifest.xml, acesse com.google.android.geo.API_KEY e atualize o 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 Maps SDK for 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 SupportMapFragment gerencia o ciclo de vida do mapa e é o elemento pai da IU 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 do mapa e as configurações da câmera, como ângulo de visão, orientação do mapa 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.

O arquivo de atividades no Google Maps contém o seguinte código:

Java

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

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;

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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.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
import com.google.maps.example.R

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 no nível do app

O arquivo build.gradle no nível do app inclui a seguinte dependência do Maps, que é exigida pelo SDK do Maps para Android.

dependencies {
    implementation 'com.google.android.gms:play-services-maps:17.0.1'
    // ...
}

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

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