Configurar seu projeto: versão 4.99 e anteriores

**Importante** :este guia é válido APENAS para projetos que usam o SDK do Navigation para Android versões 4.99 e anteriores. Se você atualizou seu projeto para a versão 5.0 ou mais recente, siga as instruções de configuração para a instalação, versões e detalhes de dependência do pacote mais recente.

Este guia lista os requisitos de configuração do build para usar o SDK do Navigation para Android. As instruções pressupõem que você tenha um ambiente de desenvolvimento integrado (IDE) do Android instalado e esteja familiarizado com o desenvolvimento do Android.

Aviso: a partir do SDK do Navigation (versão 4.0), a API não oferece mais suporte ao Android KitKat ou Lollipop (4.4 a 5.1).

Requisitos mínimos para usar o SDK do Navigation

Esses 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 provisionamento, entre em contato com seu representante da Plataforma Google Maps.

• O app precisa segmentar o nível 30 da API ou mais recente.

• Para executar um app criado com o SDK do Navigation, o dispositivo Android precisa ter o Google Play Services instalado e ativado.

• As atribuições e o texto de licenciamento precisam ser adicionados ao app.

Configurar seus projetos: projeto do console do Cloud e projeto do Android

Antes de criar ou testar um app, é necessário criar um projeto do console do Cloud e adicionar credenciais de chave de API. O projeto precisa ter provisionamento para acessar o SDK do Navigation. 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á tiver um projeto do console, poderá adicionar uma chave ao projeto atual.

Informações necessárias para configurar um projeto:

• O nome do seu representante da Plataforma Google Maps.
• Um nome para o projeto do console do Cloud.
• Um nome para o projeto de desenvolvimento de apps Android que tenha um nome de pacote necessário mais tarde.
• A impressão digital do certificado SHA-1 da sua máquina de desenvolvimento.

Para configurar

1. No seu navegador da Web favorito, faça login no console do Cloud e crie o projeto do console do Cloud.
2. No seu IDE, como o Android Studio, crie um projeto de desenvolvimento de apps Android e anote o nome do pacote.
3. Entre em contato com seu representante da Plataforma Google Maps para fornecer acesso ao SDK do Navigation para o projeto do console do Cloud.
4. No painel do console do Cloud no navegador da Web, crie credenciais para gerar uma chave de API com restrições.
5. Na página da chave de API, clique em "Apps Android" na área Restrições de aplicativos.
6. Clique em Adicionar o nome do pacote e a impressão digital e insira o nome do pacote do projeto de desenvolvimento e a impressão digital SHA-1 dessa chave.
7. Clique em Salvar.

Adicionar o SDK do Navigation ao seu projeto

O SDK do Navigation está disponível usando o Maven ou como um pacote AAR. Depois de criar o projeto de desenvolvimento, você pode integrar o SDK usando uma das seguintes abordagens.

Importante: use dependências do Maven no seu projeto para vincular o SDK do Navigation para Android. O download do pacote AAR não estará disponível no futuro.

Usar o Maven para o SDK do Navigation v4.5 e mais recente (recomendado)

O exemplo a seguir usa o repositório Maven google(), que é a maneira mais simples e recomendada de adicionar o SDK do Navigation ao seu projeto.

Observação: essa abordagem é incompatível com algumas bibliotecas que dependem do SDK do Navigation usando o ID de artefato anterior. Isso inclui versões do SDK do Driver v4.4 ou anteriores.

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

   Gradle

   Adicione o seguinte ao build.gradle do módulo:

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

   Se você estiver fazendo upgrade do repositório Maven original, observe que os nomes do grupo e do artefato 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 to make nsure 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>
   

Usar o Maven para o SDK do Navigation anterior à v4.5 ou com o SDK do Driver

O SDK do Navigation continua disponível usando o repositório Maven original durante o restante das versões v4. Essa é a mesma biblioteca com todas 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 fazer login no projeto na nuvem usando gcloud ao compilar.

1. 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 do Navigation é controlado por um grupo de espaço de trabalho.

2. Adicione a seguinte dependência à configuração do Gradle ou do Maven, substituindo o marcador VERSION_NUMBER pela versão do SDK do Navigation.

   Gradle

   Adicione o seguinte ao build.gradle do módulo:

   dependencies {
   ...
   implementation 'com.google.android.maps:navsdk:VERSION_NUMBER'
   }
   

   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 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>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 AAR transferido por download (não recomendado)

O SDK do Navigation também está disponível como um pacote AAR. Depois de criar o projeto de desenvolvimento, você pode integrar o SDK. Essas instruções pressupõem o uso do Android Studio para seu IDE.

1. Faça o download da versão mais recente do SDK do Navigation no Google Drive compartilhado e extraia-o. Se você não tiver acesso, entre em contato com seu representante.

2. No Android Studio, abra um projeto e adicione o pacote Google Play Services usando o SDK Manager.

3. No diretório do arquivo ZIP, copie libs/google_navigation_navmap.aar para o diretório app/libs do projeto.

4. Adicione o seguinte ao build.gradle do módulo:

   implementation(name: 'google_navigation_navmap', ext: 'aar')
   

   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 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'
          }
      }
   }
   

Configurar a versão

Depois de criar o projeto, você pode configurar as definições para um build bem-sucedido 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 do Navigation e considere definir as opções de otimização também.

  Configurações necessárias para o SDK do Navigation

  1. Defina minSdkVersion como 23 ou mais recente.
  2. Defina targetSdkVersion como 30 ou mais recente.
  3. Adicione uma configuração dexOptions que aumente o javaMaxHeapSize.
  4. Defina o local para outras bibliotecas.
  5. Adicione repositories e dependencies para o SDK do 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ódigos e recursos não utilizados das dependências. Se a etapa R8/ProGuard levar muito tempo 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 com suporte no SDK do Navigation.

Confira abaixo um exemplo do script de build do Gradle para o aplicativo. Verifique os apps de exemplo para conjuntos atualizados de dependências, já que a versão do SDK do Navigation que você está usando pode estar um pouco à frente ou atrás desta 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. Make sure 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 o plug-in Secrets Gradle para Android e armazenar sua chave de API:

1. No Android Studio, abra o arquivo de nível raiz build.gradle 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. Abra o arquivo build.gradle do app e adicione o seguinte código ao plugins elemento.

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

   • Forneça a chave de API de maneira 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 uma IllegalStateException se for chamado mais de uma vez.
     • Chame setApiKey() antes de inicializar outros componentes do SDK do Navigation, como Navigator.
     • A chave fornecida com esse método substitui qualquer chave de API no seu AndroidManifest.xml.
     • Use o SDK do Navigation versão 7.6 ou mais recente.

Incluir as atribuições necessárias no app

Se você usa o SDK do 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.

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

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

• NOTICE.txt
• LICENSES.txt