Este guia lista os requisitos de configuração do build para usar o SDK Navigation para Android. As instruções presumem que você tenha um ambiente de desenvolvimento integrado do Android instalado e tenha familiaridade com o desenvolvimento para Android.
Requisitos mínimos para usar o SDK Navigation
Estes requisitos se aplicam ao SDK do Navigation para Android versão 4.99 e anteriores.
Um projeto do Console do Google Cloud com o SDK do Navigation ativado. Para o provisionamento, pergunte ao seu representante da Plataforma Google Maps.
O app precisa ter o nível desejado da API 30 ou mais recente.
Para executar um app criado com o SDK de navegação, o dispositivo Android precisa ter o Google Play Services instalado e ativado.
Textos de atribuição e licenciamento precisam ser adicionados ao app.
Configurar seus projetos: projeto do Console do Cloud e projeto Android
Antes de criar ou testar um app, você precisa criar um projeto do Cloud Console e adicionar credenciais de chave de API. O projeto precisa ter provisionamento para acessar o SDK de navegação. Todas as chaves no projeto do Console do Cloud recebem o mesmo acesso ao SDK do Navigation. Uma chave pode ter mais de um projeto de desenvolvimento associado a ela. Se você já tem um projeto no console, é possível adicionar uma chave ao projeto atual.
Para configurar
- No seu navegador da Web favorito, faça login no Console do Cloud e crie seu projeto do Console do Cloud.
- No IDE, como o Android Studio, crie um projeto de desenvolvimento de app Android e anote o nome do pacote.
- Entre em contato com seu representante da Plataforma Google Maps para conceder acesso ao SDK do Navigation para seu projeto do console do Cloud.
- No painel do Console do Cloud do seu navegador da Web, crie credenciais para gerar uma chave de API com restrições.
- Na página da chave de API, clique em "Apps para Android" na área Restrições do aplicativo.
- Clique em Adicionar o nome e a impressão digital do pacote e insira o nome do pacote do seu projeto de desenvolvimento e a impressão digital SHA-1 para essa chave.
- Clique em Salvar.
Adicionar o SDK de navegação ao seu projeto
O SDK do Navigation está disponível pelo Maven ou como um pacote AAR. Depois de criar seu projeto de desenvolvimento, é possível integrar o SDK a ele usando uma das abordagens abaixo.
Como usar o Maven para o SDK de navegação v4.5 e mais recentes (recomendado)
O exemplo a seguir usa o repositório Maven google()
, que é a maneira mais simples
e recomendada de adicionar o SDK Navigation ao seu
projeto.
Adicione a dependência a seguir à configuração do Gradle ou do Maven, substituindo o marcador de posição
VERSION_NUMBER
pela versão desejada do SDK Navigation para Android.Gradle
Adicione o código abaixo ao
build.gradle
do módulo:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER' }
Se você fizer upgrade do repositório Maven original, observe que os nomes do grupo e de artefatos foram alterados, e o plug-in
com.google.cloud.artifactregistry.gradle-plugin
não é mais necessário.E adicione o seguinte ao
build.gradle
de nível superior:allprojects { ... // Required: you must exclude the Google Play service Maps SDK from // your transitive dependencies. This is to ensure there won't be // multiple copies of Google Maps SDK in your binary, as the Navigation // SDK already bundles the Google Maps SDK. configurations { implementation { exclude group: 'com.google.android.gms', module: 'play-services-maps' } } }
Maven
Adicione o seguinte ao seu
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Se você tiver dependências que usam o SDK do Maps, será necessário excluir a dependência em cada dependência declarada que depende do SDK do Maps.
<dependencies> <dependency> <groupId>project.that.brings.in.maps</groupId> <artifactId>MapsConsumer</artifactId> <version>1.0</version> <exclusions> <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication--> <exclusion> <!-- declare the exclusion here --> <groupId>com.google.android.gms</groupId> <artifactId>play-services-maps</artifactId> </exclusion> </exclusions> </dependency> </dependencies>
Como usar o Maven para o SDK de navegação anterior à v4.5 ou com o SDK do Driver
O SDK de navegação continua disponível pelo
repositório Maven original nas versões restantes da v4. Essa é a
mesma biblioteca com as mesmas atualizações da versão acima e oferece
compatibilidade com o SDK do Driver e outras bibliotecas durante a transição. O uso
dessa dependência exige que você faça login no projeto da nuvem usando gcloud
durante a
compilação.
- Configure seu ambiente para acessar o repositório Maven do Google, conforme descrito na seção Pré-requisitos da documentação do SDK do consumidor. O acesso ao SDK de navegação é controlado por um grupo de espaços de trabalho.
Adicione a dependência abaixo à configuração do Gradle ou Maven, substituindo o marcador
VERSION_NUMBER
pela versão desejada do SDK do Navigation.Gradle
Adicione o seguinte ao
build.gradle
no nível do módulo:dependencies { ... implementation 'com.google.android.maps:navsdk:VERSION_NUMBER' }
E adicione o seguinte à sua
build.gradle
de nível superior:allprojects { ... // Required: you must exclude the Google Play service Maps SDK from // your transitive dependencies. This is to ensure there won't be // multiple copies of Google Maps SDK in your binary, as the Navigation // SDK already bundles the Google Maps SDK. configurations { implementation { exclude group: 'com.google.android.gms', module: 'play-services-maps' } } }
Maven
Adicione o seguinte ao seu
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.maps</groupId> <artifactId>navsdk</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Se você tiver dependências que usam o SDK do Maps, será necessário excluir a dependência em cada dependência declarada que depende do SDK do Maps.
<dependencies> <dependency> <groupId>project.that.brings.in.maps</groupId> <artifactId>MapsConsumer</artifactId> <version>1.0</version> <exclusions> <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication--> <exclusion> <!-- declare the exclusion here --> <groupId>com.google.android.gms</groupId> <artifactId>play-services-maps</artifactId> </exclusion> </exclusions> </dependency> </dependencies>
Usar um pacote de AARs baixado (não recomendado)
O SDK do Navigation também está disponível como um pacote AAR. Depois de criar o projeto de desenvolvimento, será possível integrar o SDK. Estas instruções pressupõem o uso do Android Studio para seu ambiente de desenvolvimento integrado.
Faça o download da versão mais recente do SDK Navigation no Google Drive compartilhado e descompacte-o. Se você não tiver acesso, entre em contato com seu representante.
No Android Studio, abra um projeto e adicione o pacote do Google Play Services usando o SDK Manager.
No diretório do arquivo ZIP, copie
libs/google_navigation_navmap.aar
para o diretórioapp/libs
do projeto.Adicione o seguinte ao
build.gradle
no nível do módulo:implementation(name: 'google_navigation_navmap', ext: 'aar')
E adicione o seguinte à sua
build.gradle
de nível superior:allprojects { ... // Required: you must exclude the Google Play service Maps SDK from // your transitive dependencies. This is to ensure there won't be // multiple copies of Google Maps SDK in your binary, as the Navigation // SDK already bundles the Google Maps SDK. configurations { implementation { exclude group: 'com.google.android.gms', module: 'play-services-maps' } } }
Configure o build
Depois de criar o projeto, você pode definir as configurações para criar e usar o SDK de navegação.
Atualizar propriedades locais
- Na pasta Gradle Scripts, abra o arquivo
local.properties
e adicioneandroid.useDeprecatedNdk=true
.
Atualizar o script de build do Gradle
Abra o arquivo
build.gradle (Module:app)
e use as diretrizes a seguir para atualizar as configurações e atender aos requisitos do SDK de navegação. Considere também definir as opções de otimização.Configurações necessárias para o SDK do Navigation
- Defina
minSdkVersion
como 23 ou mais. - Defina
targetSdkVersion
como 30 ou mais. - Adicione uma configuração
dexOptions
que aumente ojavaMaxHeapSize
. - Defina o local para outras bibliotecas.
- Adicione o
repositories
e odependencies
para o SDK Navigation. - Substitua os números de versão nas dependências pelas versões mais recentes disponíveis.
Configurações opcionais para diminuir o tempo de build
- Ative a redução de código e de recursos usando o R8/ProGuard para remover o código e os recursos não utilizados das dependências. Se a etapa do R8/ProGuard demorar muito para ser executada, ative o multidex para o trabalho de desenvolvimento.
- Reduza o número de traduções de idioma incluídas no build: defina
resConfigs
para um idioma durante o desenvolvimento. Para o build final, definaresConfigs
para os idiomas que você realmente usa. Por padrão, o Gradle inclui strings de recursos para todos os idiomas com suporte do SDK do Navigation.
- Defina
Confira abaixo um exemplo do script de build do Gradle para o aplicativo. Consulte os apps de exemplo para conferir conjuntos atualizados de dependências, já que a versão do SDK de navegação que você está usando pode estar um pouco à frente ou atrasada nesta documentação.
apply plugin: 'com.android.application'
apply plugin: 'com.google.cloud.artifactregistry.gradle-plugin'
ext {
androidxVersion = "1.0.0"
lifecycle_version = "1.1.1"
}
android {
compileSdkVersion 30
buildToolsVersion '28.0.3'
defaultConfig {
applicationId "<your id>"
// Navigation SDK supports SDK 23 and later.
minSdkVersion 23
targetSdkVersion 30
versionCode 1
versionName "1.0"
// Set this to the languages you actually use, otherwise you'll include resource strings
// for all languages supported by the Navigation SDK.
resConfigs "en"
multiDexEnabled true
}
dexOptions {
// This increases the amount of memory available to the dexer. This is required to build
// apps using the Navigation SDK.
javaMaxHeapSize "4g"
}
buildTypes {
// Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
// The configuration is included transitively by depending on the Navigation SDK.
// If the ProGuard step takes too long, consider enabling multidex for development work
// instead.
all {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
// This tells Gradle where to look to find additional libraries - in this case, the
// google_navigation_navmap.aar file.
repositories {
flatDir {
dirs 'libs'
}
google()
// Required for accessing the Navigation SDK on Google's Maven repository.
maven {
url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
}
}
dependencies {
// Include the Google Navigation SDK
implementation 'com.google.android.maps:navsdk:4.4.0'
// The included AAR file under libs can be used instead of the Maven repository.
// Uncomment the line below and comment out the previous dependency to use
// the AAR file instead. Ensure that you add the AAR file to the libs directory.
// implementation(name: 'google_navigation_navmap', ext: 'aar')
// These dependencies are required for the Navigation SDK to function
// properly at runtime.
implementation 'org.chromium.net:cronet-fallback:69.3497.100'
// Optional for Cronet users:
// implementation 'org.chromium.net:cronet-api:69.3497.100'
implementation 'androidx.appcompat:appcompat:${androidxVersion}'
implementation 'androidx.cardview:cardview:${androidxVersion}'
implementation 'com.google.android.material:material:${androidxVersion}'
implementation 'androidx.mediarouter:mediarouter:${androidxVersion}'
implementation 'androidx.preference:preference:${androidxVersion}'
implementation 'androidx.recyclerview:recyclerview:${androidxVersion}'
implementation 'androidx.legacy:legacy-support-v4:${androidxVersion}'
implementation 'com.github.bumptech.glide:glide:4.9.0'
implementation 'com.github.bumptech.glide:okhttp-integration:4.9.0'
implementation 'android.arch.lifecycle:common-java8:$lifecycle_version'
implementation 'com.android.support:multidex:1.0.3'
implementation 'com.google.android.datatransport:transport-api:2.2.0'
implementation 'com.google.android.datatransport:transport-backend-cct:2.2.0'
implementation 'com.google.android.datatransport:transport-runtime:2.2.0'
implementation 'joda-time:joda-time:2.9.9'
annotationProcessor 'androidx.annotation:annotation:1.1.0'
annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
}
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 secrets.properties
, que fica no diretório raiz do projeto. Para saber mais sobre o arquivo secrets.properties
, consulte Arquivos de propriedades do Gradle.
Se quiser otimizar essa tarefa, use o plug-in Secrets Gradle para Android.
Para instalar esse plug-in no seu projeto do Google Maps:
-
No Android Studio, abra o arquivo de nível superior
build.gradle.kts
oubuild.gradle
e adicione o seguinte código ao elementodependencies
embuildscript
.Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
Abra o arquivo
build.gradle.kts
oubuild.gradle
no nível do módulo e adicione este código ao elementoplugins
.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- No arquivo
build.gradle.kts
oubuild.gradle
no nível do módulo, verifique setargetSdk
ecompileSdk
estão definidos como 34. - Salve o arquivo e sincronize seu projeto com o Gradle.
-
Abra o arquivo
secrets.properties
no seu diretório de nível superior e adicione o código a seguir. SubstituaYOUR_API_KEY
pela sua chave de API. Armazene sua chave nesse arquivo porquesecrets.properties
não é verificado em um sistema de controle de versões.NAV_API_KEY=YOUR_API_KEY
- Salve o arquivo.
-
Crie o arquivo
local.defaults.properties
no seu diretório de nível superior, na mesma pasta que o arquivosecrets.properties
, e depois adicione o seguinte código.NAV_API_KEY=DEFAULT_API_KEY
O objetivo desse arquivo é oferecer um local de backup para a chave da API se o arquivo
secrets.properties
não for encontrado, para que os builds não apresentem falha. Isso pode acontecer se você clonar o app de um sistema de controle de versões que omitesecrets.properties
e ainda não tiver criado um arquivosecrets.properties
localmente para fornecer sua chave de API. - Salve o arquivo.
-
No seu arquivo
AndroidManifest.xml
, vá atécom.google.android.geo.API_KEY
e atualizeandroid:value attribute
. Se a tag<meta-data>
não existe, crie-a como um elemento filho da tag<application>
.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Observação:
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 Navigation para Android. Para garantir a compatibilidade com versões anteriores, a API também aceita o nomecom.google.android.maps.v2.API_KEY
. Esse nome legado 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. -
No Android Studio, abra o arquivo
build.gradle.kts
oubuild.gradle
no nível do módulo e edite a propriedadesecrets
. Se a propriedadesecrets
não existir, adicione-a.Edite as propriedades do plug-in para definir
propertiesFileName
comosecrets.properties
,defaultPropertiesFileName
comolocal.defaults.properties
e outras propriedades.Kotlin
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file. // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Groovy
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file. // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Incluir as atribuições necessárias no app
Se você usa o SDK do Navigation para Android no seu app, é necessário incluir texto de atribuição e licenças de código aberto como parte da seção de avisos legais do app.
O texto de atribuição necessário e as licenças de código aberto estão disponíveis no arquivo ZIP do SDK do Navigation para Android:
NOTICE.txt
LICENSES.txt