Configuração

Esta página descreve o que você precisa fazer para começar a criar com o SDK do Maps 3D para Android. O processo de configuração envolve a configuração de um projeto do Google Cloud e uma API para uso com o SDK e, em seguida, a configuração de um projeto do Android Studio. Conclua estas etapas antes de adicionar seu primeiro mapa 3D ao app.

Pré-requisitos

Para usar o SDK do Maps 3D para Android, seu projeto e dispositivos de destino precisam atender aos seguintes requisitos:

• Nível mínimo da API: nível 24 da API Android (Android 7.0) ou mais recente. Seu app precisa segmentar um minSdk de 24 ou mais recente.
• Google Play Services: o SDK do Maps 3D para Android depende de Google Play Services. Os dispositivos de destino (e emuladores com APIs do Google) precisam ter o Google Play Services instalado.

Configurar um projeto do Google Cloud e uma chave de API

Antes de começar a criar com o SDK do Maps 3D para Android, você precisa configurar um projeto na nuvem do Google Cloud e uma chave de API para usar com o SDK do Maps 3D para Android seguindo estas etapas:

Etapa 1

Console

1. No console do Google Cloud, na página do seletor de projetos, clique Criar projeto para começar a criar 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.

   É possível testar o Google Cloud sem pagar nada. 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. Para mais informações, consulte Créditos da conta de faturamento e Faturamento.

SDK Cloud

gcloud projects create "PROJECT"

Saiba mais sobre o SDK Google Cloud, a instalação do SDK Cloud e os seguintes comandos:

• gcloud projects create

Observação: se você não pretende manter os recursos criados neste exercício, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir o exercício, exclua o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

Etapa 2

Para utilizar a Plataforma Google Maps, ative as APIs ou os SDKs que você planeja usar com seu projeto.

É preciso ativar vários SDKs/APIs para algumas integrações. Se você não souber quais APIs ou SDKs ativar, use o Capabilities Explorer ou consulte a documentação da API/SDK que gostaria de usar.

Para ativar uma ou mais APIs ou SDKs, faça o seguinte:

Console

1. Veja as APIs e os SDKs da Plataforma Google Maps que você pode habilitar acessando a página Biblioteca de APIs Maps no console do Cloud:

   Acessar a página Biblioteca de APIs Maps

2. Clique na API ou no SDK que você quer ativar.
   • Se o botão disser ATIVAR, clique no botão para ativar a API ou o SDK.
   • Se houver um botão GERENCIAR, a API ou o SDK já está ativado e você não precisa fazer mais nada.
   • Quando você clica em um desses botões, o painel da API ou do SDK é exibido. Clique em DESATIVAR para remover a API ou o SDK do projeto.

SDK Cloud

O comando abaixo ativa todas as APIs Maps, Routes e Places:

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

Saiba mais sobre o SDK Google Cloud , a instalação do SDK Cloud e os seguintes comandos:

• gcloud services enable
• gcloud services disable

Use este comando para ativar as APIs Environment:

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

Observação: ao ativar a API Places, você também habilita a biblioteca Places, a API Maps JavaScript e os SDKs do Places para Android e para iOS.

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

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Saiba mais sobre o SDK Google Cloud , a instalação do SDK Cloud e os seguintes comandos:

• gcloud services api-keys create

Para ativar o SDK, consulte a página SDK do Maps 3D para Android no console do Google Cloud. Para mais informações sobre como concluir essas etapas, consulte Introdução à Plataforma Google Maps.

Configurar um projeto do Android Studio

Esta seção explica como criar e configurar um projeto do Android Studio para uso com o SDK do Maps 3D para Android.

Parte 1: configurar o projeto e a configuração do Gradle

1. Crie um novo projeto do Android Studio usando o modelo Empty Views Activity. Na configuração do projeto, defina o SDK mínimo como API 24 ou mais recente.

2. Se você estiver usando o Git para controle de origem, modifique o arquivo .gitignore do projeto para impedir que o arquivo de secrets seja confirmado no controle de versão:

   • No diretório raiz do projeto, abra o arquivo .gitignore.
   • Adicione a linha abaixo:

   secrets.properties
   

3. Atualize o arquivo build.gradle.kts no nível do projeto:

   • No diretório raiz do projeto, abra o arquivo build.gradle.kts.
   • No bloco plugins, adicione o plug-in de secrets do Gradle:

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. Atualize o arquivo gradle/libs.versions.toml:

   • Abra o arquivo gradle/libs.versions.toml, que geralmente está localizado no diretório gradle no diretório raiz do projeto.
   • Na seção [versions], adicione as versões do SDK e do plug-in de secrets do Gradle:

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.0"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • Na seção [library], adicione a biblioteca do SDK:

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • Na seção [plugins], adicione o plug-in de secrets do Gradle:

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. Atualize o arquivo app/build.gradle.kts no nível do módulo:

   • Abra o arquivo build.gradle.kts no nível do módulo, que geralmente está localizado no diretório app.
   • Na parte de cima do arquivo, adicione o plug-in de secrets do Gradle ao bloco plugins:

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • No bloco dependencies, adicione a dependência do Google Play Services para o SDK do Maps 3D para Android:

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • No final do arquivo, fora dos blocos android e dependencies, adicione a configuração de secrets:

   secrets {
       // Optionally specify a different filename containing your secrets.
       // The plugin defaults to "local.properties"
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
   

Parte 2: adicionar sua chave de API ao projeto

1. Crie um arquivo secrets.properties:

   • No diretório raiz do módulo do app (geralmente o diretório app), crie um novo arquivo chamado secrets.properties.
   • Adicione a chave de API ao arquivo:

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

   Observação: substitua YOUR_API_KEY_HERE pela chave de API que você configurou para uso com o SDK do Maps 3D para Android.

2. Crie um arquivo local.defaults.properties: - No diretório raiz do módulo do app, crie um novo arquivo chamado local.defaults.properties. Adicione uma chave de API padrão ou de marcador de posição ao arquivo. Esse arquivo pode ser confirmado no controle de versão:

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

Parte 3: atualizar o arquivo AndroidManifest.xml

1. Abra o arquivo app/src/main/AndroidManifest.xml.

2. Dentro da tag <application>, antes da tag <activity>, adicione o seguinte <meta-data> elemento para declarar sua chave de API:

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   Durante o processo de build, o plug-in de secrets do Gradle vai substituir o marcador de posição ${MAPS3D_API_KEY} pela chave do arquivo secrets.properties.

Inicialização da visualização programática (opcional)

Se você preferir inicializar a visualização do mapa de maneira programática em vez de layouts XML, use Map3DInitConfig.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

Próximas etapas

Agora que você tem um projeto na nuvem do Google Cloud, uma chave de API e um projeto do Android Studio configurado para uso com o SDK do Maps 3D para Android, é possível adicionar um mapa 3D ao seu app.