Configurar seu projeto do Android Studio

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

Adicionar o SDK do Navigation ao seu projeto

O SDK do 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.

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

    Gradle

    Adicione o seguinte ao build.gradle 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>

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

    Gradle

    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 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 o build

Depois de criar o projeto, você pode definir as configurações para criar e usar o SDK do 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 diretrizes a seguir para atualizar as configurações de acordo com os 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

    1. Defina minSdkVersion como 24 ou mais recente.
    2. Defina targetSdkVersion como 36 ou mais.
    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 de navegação.
    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ódigos e recursos não utilizados das dependências. Se a etapa do R8/ProGuard demorar muito para ser executada, considere ativar o multidex para o trabalho 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ê realmente usa. Por padrão, o Gradle inclui strings de recursos para todos os idiomas compatíveis com o SDK de navegação.

    Adicionar simplificação para compatibilidade com o Java 8

    • 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 à simplificação do Java 8 para mais informações. Confira o snippet de exemplo do script de build abaixo para saber como compilar e as opções de dependência.
    • Use as versões do Gradle, do Plug-in do Android para Gradle (AGP) e da biblioteca Desugar que correspondem à versão do SDK de navegação. Veja a tabela a seguir:
    • A biblioteca Desugar precisa ser ativada para o módulo app e qualquer módulo que dependa diretamente do SDK de navegação.

A tabela a seguir lista as versões das bibliotecas do Gradle, do AGP e do Desugar necessárias para cada versão do SDK de navegação.

Versão do SDK Navigation Versão do Gradle Versão do AGP Biblioteca de simplificação
8.0.0 e versões mais recentes 9.1.0 9.0.1 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.7.0 a 7.9.0 8.13 8.13.2 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.3.0 a 7.6.0 8.11.1 8.10.0 com.android.tools:desugar_jdk_libs_nio:2.0.3

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 de 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.1.5'
}

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, e excluir esse arquivo do controle de versões. Para saber mais sobre os arquivos de propriedades do Gradle, consulte Arquivos de propriedades do Gradle.

Se quiser simplificar 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 de nível superior build.gradle.kts ou build.gradle e adicione o seguinte código ao bloco plugins.

    Kotlin

    plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. Abra o arquivo build.gradle.kts ou build.gradle no nível do módulo e adicione o seguinte código ao elemento plugins.

    Kotlin

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

    Groovy

    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 arquivo secrets.properties no seu diretório de nível superior e adicione o código a seguir. Substitua YOUR_API_KEY pela sua chave de API. Adicione secrets.properties ao arquivo .gitignore (ou exclua-o do sistema de controle de versões) para que sua chave de API não seja verificada no controle de versões. 
    MAPS_API_KEY=YOUR_API_KEY

  5. Crie o arquivo local.defaults.properties no seu diretório de nível superior, na mesma pasta que o arquivo secrets.properties, e depois adicione o seguinte código.

    MAPS_API_KEY=DEFAULT_API_KEY

    O objetivo desse arquivo é oferecer um local de backup para a chave de 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 omite secrets.properties e ainda não tiver criado um arquivo secrets.properties localmente para fornecer sua chave de API.

  6. Você pode adicionar a chave de API ao arquivo AndroidManifest.xml ou fornecê-la de forma programática.
    • Adicione sua chave de API a AndroidManifest.xml: 
      <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 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.

    • Forneça a chave de API de forma programática:

      O plug-in Secrets Gradle disponibiliza a chave na classe BuildConfig. Na inicialização do app (por exemplo, no método Application.onCreate()), chame o método da seguinte maneira:

      Kotlin

      1. Adicione as seguintes instruções de importação: 
        import com.google.android.libraries.navigation.NavigationApi
      2. Adicione o seguinte ao método Application.onCreate(): 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. Adicione as seguintes instruções de importação: 
        import com.google.android.libraries.navigation.NavigationApi;
      2. Adicione o seguinte ao método Application.onCreate(): 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      Observação:ao usar setApiKey(), tenha em mente o seguinte:
      • Forneça uma chave de API não nula e não vazia.
      • Chame setApiKey() apenas uma vez durante o ciclo de vida do aplicativo. O método gera um IllegalStateException se for chamado mais de uma vez.
      • Chame setApiKey() antes de inicializar qualquer outro componente do SDK do Navigation, como Navigator.
      • A chave fornecida com esse método substitui qualquer chave de API no AndroidManifest.xml.
      • Use a versão 7.6 ou mais recente do SDK de navegação.

  7. No Android Studio, abra o arquivo build.gradle.kts ou build.gradle no nível do módulo e edite a propriedade secrets. Se a propriedade secrets não existir, adicione-a.

    Edite as propriedades do plug-in para definir propertiesFileName como "secrets.properties", definir defaultPropertiesFileName como "local.defaults.properties" e definir 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 root directory (the same folder as the root 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"
}

    Groovy

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
}

Incluir as atribuições necessárias no app

Se você usa o SDK de Navegação 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.

O texto de atribuição obrigatório e as licenças de código aberto estão 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).

Dependências manuais (não Gradle/Maven)

Se o sistema de build não resolver dependências transitivas (como o Bazel) ou se você integrar o AAR manualmente, será necessário adicionar essas dependências ao projeto. O Gradle e o Maven as resolvem automaticamente.

  • androidx.datastore:datastore-core
  • androidx.datastore:datastore-guava
  • com.google.guava:listenablefuture
  • androidx.concurrent:concurrent-futures