Configurer votre projet Android Studio

Cette page explique comment intégrer le SDK Navigation à votre projet de développement.

Ajouter le SDK Navigation à votre projet

Le SDK Navigation est disponible via le dépôt Maven de Google. Vous pouvez ajouter le SDK à votre projet à l'aide de la configuration Gradle build.gradle ou Maven pom.xml.

Remarque :Cette méthode n'est pas compatible avec certaines bibliothèques qui dépendent du SDK Navigation via l'ID d'artefact précédent. Cela inclut les versions du SDK Driver 4.4 ou antérieures.

1. Ajoutez la dépendance suivante à votre configuration Gradle ou Maven, en remplaçant l'espace réservé VERSION_NUMBER par la version souhaitée du SDK Navigation pour Android.

   Gradle

   Ajoutez les éléments suivants à votre build.gradle au niveau du module:

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

   Maven

   Ajoutez les éléments suivants à votre pom.xml :

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.navigation</groupId>
       <artifactId>navigation</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

   Remarque :Si vous êtes un client Mobility Services qui met à niveau à partir du dépôt Maven privé d'origine, notez que les noms de groupe et d'artefact ont changé et que le plug-in com.google.cloud.artifactregistry.gradle-plugin n'est plus nécessaire.

2. Si vous avez des dépendances qui utilisent le SDK Maps, vous devez exclure la dépendance dans chaque dépendance déclarée qui dépend du SDK Maps.

   Gradle

   Ajoutez les éléments suivants à votre build.gradle de niveau supérieur:

   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

   Ajoutez les éléments suivants à votre 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>
   

Configurer la compilation

Une fois le projet créé, vous pouvez configurer les paramètres pour compiler et utiliser correctement le SDK Navigation.

Mettre à jour les propriétés locales

• Dans le dossier Scripts Gradle, ouvrez le fichier local.properties et ajoutez android.useDeprecatedNdk=true.

Mettre à jour les propriétés Gradle

• Dans le dossier Scripts Gradle, ouvrez le fichier gradle.properties et ajoutez les éléments suivants s'ils ne sont pas déjà présents:

  1. android.useAndroidX=true
  2. android.enableJetifier=true

Mettre à jour le script de compilation Gradle

• Ouvrez le fichier build.gradle (Module:app) et utilisez les consignes suivantes pour mettre à jour les paramètres afin qu'ils répondent aux exigences du SDK Navigation. Pensez également à définir les options d'optimisation.

  Paramètres requis pour le SDK Navigation

  1. Définissez minSdkVersion sur 23 ou une version ultérieure.
  2. Définissez targetSdkVersion sur 34 ou une version ultérieure.
  3. Ajoutez un paramètre dexOptions qui augmente le javaMaxHeapSize.
  4. Définissez l'emplacement des bibliothèques supplémentaires.
  5. Ajoutez repositories et dependencies pour le SDK Navigation.
  6. Remplacez les numéros de version des dépendances par les dernières versions disponibles.

  Paramètres facultatifs pour réduire le temps de compilation

  • Activez la minification du code et des ressources à l'aide de R8/ProGuard pour supprimer le code et les ressources inutilisés des dépendances. Si l'étape R8/ProGuard prend trop de temps à s'exécuter, envisagez d'activer le multidex pour le travail de développement.
  • Réduire le nombre de traductions linguistiques incluses dans le build: définissez resConfigs pour une langue pendant le développement. Pour le build final, définissez resConfigs pour les langues que vous utilisez réellement. Par défaut, Gradle inclut des chaînes de ressources pour toutes les langues prises en charge par le SDK Navigation.

  Ajout de la désucrage pour la prise en charge de Java 8

  • Si vous compilez votre application à l'aide du plug-in Android Gradle 4.0.0 ou version ultérieure, vous pouvez utiliser un certain nombre d'API en langage Java 8. Pour en savoir plus, consultez la page Compatibilité avec le désucrage Java 8. Consultez l'exemple d'extrait de script de compilation ci-dessous pour découvrir comment utiliser les options de compilation et de dépendance.
  • Nous vous recommandons d'utiliser Gradle 8.4, le plug-in Android Gradle version 8.3.0 et la bibliothèque Desugar com.android.tools:desugar_jdk_libs_nio:2.0.3. Cette configuration est compatible avec le SDK Navigation pour Android version 6.0.0 et ultérieure.
  • La bibliothèque Desugar doit être activée pour le module app et tout module qui dépend directement du SDK Navigation.

Vous trouverez ci-dessous un exemple de script de compilation Gradle pour l'application. Vérifiez les exemples d'applications pour obtenir des ensembles de dépendances mis à jour, car la version du SDK Navigation que vous utilisez peut être légèrement en avance ou en retard sur cette documentation.

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

Ajouter la clé API à votre application

Cette section explique comment stocker votre clé API pour qu'elle puisse être référencée de manière sécurisée par votre application. Vous ne devez pas enregistrer votre clé API dans votre système de contrôle des versions. Nous vous recommandons donc de la stocker dans le fichier secrets.properties, qui se trouve dans le répertoire racine de votre projet. Pour en savoir plus sur le fichier secrets.properties, consultez Fichiers de propriétés Gradle.

Pour vous faciliter la tâche, nous vous recommandons d'utiliser le plug-in Secrets Gradle pour Android.

Remarque : Consultez la documentation du plug-in Secrets Gradle pour Android sur GitHub pour connaître la configuration système requise et lire les instructions d'installation.

Pour installer le plug-in Secrets Gradle pour Android dans votre projet Google Maps :

1. Dans Android Studio, ouvrez votre fichier build.gradle.kts ou build.gradle de premier niveau et ajoutez le code suivant à l'élément dependencies sous buildscript.

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

2. Ouvrez votre fichier build.gradle.kts ou build.gradle au niveau du module, puis ajoutez le code suivant à l'élément plugins.

   Kotlin

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

   Groovy

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

3. Dans votre fichier build.gradle.kts ou build.gradle au niveau du module, assurez-vous que targetSdk et compileSdk sont définis sur 34.
4. Enregistrez le fichier et synchronisez votre projet avec Gradle.
5. Ouvrez le fichier secrets.properties dans votre répertoire de premier niveau et ajoutez le code suivant. Remplacez YOUR_API_KEY par votre clé API. Stockez votre clé dans ce fichier, car secrets.properties n'est pas vérifié dans un système de contrôle des versions.
   Remarque : Si le fichier secrets.properties n'existe pas, créez-le dans le même dossier que le fichier local.properties.

   NAV_API_KEY=YOUR_API_KEY

6. Enregistrez le fichier.

7. Créez le fichier local.defaults.properties dans votre répertoire de premier niveau (même dossier que le fichier secrets.properties), puis ajoutez le code suivant.

   Remarque : Saisissez le code comme indiqué. Ne remplacez pas DEFAULT_API_KEY par votre clé API.

   NAV_API_KEY=DEFAULT_API_KEY

   Ce fichier a pour but de fournir un emplacement de sauvegarde de la clé API, à utiliser si le fichier secrets.properties est introuvable pour éviter l'échec des créations. Cette situation peut se produire si vous clonez l'application à partir d'un système de contrôle des versions qui omet secrets.properties et que vous n'avez pas encore créé de fichier secrets.properties localement pour fournir votre clé API.

8. Enregistrez le fichier.
9. Dans votre fichier AndroidManifest.xml, accédez à com.google.android.geo.API_KEY, puis modifiez le android:value attribute. Si le tag <meta-data> n'existe pas, créez-le comme enfant du tag <application>.

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

   Remarque:com.google.android.geo.API_KEY est le nom de métadonnées recommandé pour la clé API. Une clé portant ce nom peut être utilisée pour l'authentification auprès de diverses API basées sur Google Maps et s'exécutant sur la plate-forme Android, y compris le SDK Navigation pour Android. Pour assurer la rétrocompatibilité, l'API accepte également le nom com.google.android.maps.v2.API_KEY. Cet ancien nom autorise l'authentification auprès de l'API Google Maps Android v2 uniquement. Une application ne peut spécifier qu'un seul des noms de métadonnées de clé API. Si les deux noms sont spécifiés, l'API génère une exception.

10. Dans Android Studio, ouvrez votre fichier build.gradle.kts ou build.gradle au niveau du module, puis modifiez la propriété secrets. Si la propriété secrets n'existe pas, ajoutez-la.

    Modifiez les propriétés du plug-in pour définir propertiesFileName sur secrets.properties, defaultPropertiesFileName sur local.defaults.properties et d'autres propriétés.

    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.*"
    }
            

Inclure les attributions requises dans votre application

Si vous utilisez le SDK Navigation pour Android dans votre application, vous devez inclure le texte d'attribution et les licences Open Source dans la section des mentions légales de votre application.

Point clé: Pour inclure les attributions, ajoutez-les en tant qu'élément de menu indépendant ou dans un menu "À propos".

Vous trouverez le texte d'attribution et les licences Open Source requis dans le fichier ZIP du SDK Navigation pour Android:

• NOTICE.txt
• LICENSES.txt

Si vous êtes client Mobility ou Fleet Engine Deliveries

Si vous êtes client de Mobility ou de Fleet Engine Deliveries, consultez la documentation Mobility pour en savoir plus sur la facturation. Pour en savoir plus sur l'enregistrement des transactions, consultez les pages Configurer la facturation, Enregistrer les transactions facturables, Créer des rapports et Enregistrer les transactions facturables (Android).