Configurar seu projeto do Android Studio

Nesta página, explicamos como integrar o SDK Navigation ao seu projeto de desenvolvimento.

Adicionar o SDK Navigation ao seu projeto

O SDK Navigation está disponível no repositório Maven do Google. É possível adicionar o SDK ao seu projeto usando a configuração do Gradle build.gradle ou do Maven pom.xml.

Observação: esse método é incompatível com algumas bibliotecas que dependem do SDK Navigation pelo ID do artefato anterior. Isso inclui versões do SDK Driver v4.4 ou anteriores.

1. Adicione a seguinte dependência à sua configuração do Gradle ou Maven, substituindo o marcador de posição VERSION_NUMBER pela versão desejada do SDK Navigation para Android.

   Gradle

   Adicione o seguinte ao seu build.gradle no nível do módulo:

   dependencies {
           ...
           implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
   }
   

   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>
   

   Observação: se você é um cliente do Mobility Services fazendo upgrade do repositório privado original do Maven, observe que os nomes de grupo e artefato mudaram e o plug-in com.google.cloud.artifactregistry.gradle-plugin não é mais necessário.

2. Se você tiver dependências que usam o SDK do Maps, exclua a dependência em cada dependência declarada que depende do SDK do Maps.

   Gradle

   Adicione o seguinte ao seu build.gradle de nível superior:

   allprojects {
           ...
           // Required: you must exclude the Google Play service Maps SDK from
           // your transitive dependencies to make sure 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>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>
   

Configurar a versão

Depois de criar o projeto, configure as definições para uma compilação e uso bem-sucedidos do SDK Navigation.

Atualizar propriedades locais

• Na pasta "Gradle Scripts", abra o arquivo local.properties e adicione android.useDeprecatedNdk=true.

Atualizar o script de build do Gradle

• Abra o arquivo build.gradle (Module:app) e use as seguintes diretrizes para atualizar as configurações e atender aos requisitos do SDK Navigation. Considere também definir as opções de otimização.

  Configurações obrigatórias para o SDK Navigation

  1. Defina minSdkVersion como 23 ou mais recente.
  2. Defina targetSdkVersion como 34 ou mais recente.
  3. Adicione uma configuração dexOptions que aumente o javaMaxHeapSize.
  4. Defina o local para outras bibliotecas.
  5. Adicione o repositories e o dependencies para o SDK Navigation.
  6. 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 código e recursos não utilizados das dependências. Se a etapa do R8/ProGuard levar muito tempo para ser executada, considere ativar o multidex para trabalhos de desenvolvimento.
  • Reduza o número de traduções de idiomas incluídas no build: defina resConfigs para um idioma durante o desenvolvimento. Para o build final, defina resConfigs para os idiomas que você usa. Por padrão, o Gradle inclui strings de recursos para todos os idiomas compatíveis com o SDK Navigation.

  Adicionar desaçucaramento para compatibilidade com Java8

  • Se você estiver criando o app usando o Plug-in do Android para Gradle 4.0.0 ou mais recente, o plug-in vai ampliar o suporte para o uso de várias APIs da linguagem Java 8. Consulte Suporte à desaçucaragem do Java 8 para mais informações. Confira o exemplo de snippet de script de build abaixo para saber como compilar e usar opções de dependência.
  • Recomendamos usar o Gradle 8.4, o Plug-in do Android para Gradle versão 8.3.0 e a biblioteca Desugar com.android.tools:desugar_jdk_libs_nio:2.0.3. Essa configuração é compatível com o SDK Navigation para Android versão 6.0.0 e mais recentes.
  • A biblioteca Desugar precisa ser ativada para o módulo app e qualquer módulo que dependa diretamente do SDK Navigation.

Confira abaixo um exemplo do script de build do Gradle para o aplicativo. Confira os apps de exemplo para ver conjuntos atualizados de dependências, já que a versão do SDK Navigation que você está usando pode estar um pouco à frente ou atrás desta documentação.

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        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 {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.0.3'
}

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 o plug-in Secrets Gradle para Android e armazenar sua chave de API:

1. No Android Studio, abra o arquivo build.gradle no nível raiz e adicione o seguinte código ao elemento dependencies em buildscript.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

2. Depois, abra o arquivo build.gradle no nível do app e adicione o seguinte código ao elemento plugins.

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. Se você usa o Android Studio, 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. No seu arquivo AndroidManifest.xml, acesse com.google.android.geo.API_KEY e atualize o atributo android:value da seguinte maneira:

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

Incluir as atribuições necessárias no app

Se você usa o SDK Navigation para Android no seu app, precisa incluir o texto de atribuição e as licenças de código aberto como parte da seção de avisos legais do app.

Importante: para incluir as atribuições, adicione-as como um item de menu independente ou em um menu "Sobre".

Você encontra o texto de atribuição necessário e as licenças de código aberto no arquivo ZIP do SDK de navegação para Android:

• NOTICE.txt
• LICENSES.txt

Se você é cliente do Mobility ou do Fleet Engine Deliveries

Se você é cliente do Mobility ou do Fleet Engine Deliveries, saiba mais sobre o faturamento na documentação do Mobility. Para mais informações sobre como registrar transações, consulte Configurar o faturamento, Registrar transações faturáveis, Relatórios e Registrar transações faturáveis (Android).