Configurer un projet Android Studio

Pour configurer votre application afin qu'elle utilise le SDK Places pour Android, procédez comme suit. Ils sont obligatoires pour toutes les applications utilisant le SDK Places pour Android.

Étape 1 : Configurez Android Studio

Ce document décrit un environnement de développement utilisant Android Studio Hedgehog et le plug-in Android Gradle version 8.2.

Étape 2 : Configurez le SDK

La bibliothèque du SDK Places pour Android est disponible via le dépôt Maven de Google. Pour ajouter le SDK à votre application, procédez comme suit :

  1. Dans le fichier settings.gradle de premier niveau, incluez le portail de plug-ins Gradle, le dépôt Maven de Google et le dépôt central Maven sous le bloc pluginManagement. Dans le script, le bloc pluginManagement doit apparaître avant toute autre instruction.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. Dans le fichier settings.gradle de premier niveau, incluez le dépôt Maven de Google et le dépôt central Maven sous le bloc dependencyResolutionManagement :
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. Dans la section dependencies de votre fichier build.gradle au niveau du module, ajoutez une dépendance au SDK Places pour Android:

    Groovy

    dependencies {
        // If updating kotlin-bom version number above, also edit project-level build.gradle definition of $kotlin_version variable
        implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
        implementation 'com.google.android.libraries.places:places:3.3.0'
    }

    Kotlin

    dependencies {
        implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
        implementation("com.google.android.libraries.places:places:3.3.0")
    }
  4. Dans le fichier build.gradle au niveau du module, définissez compileSdk et minSdk sur les valeurs suivantes :

    Groovy

    android {
        compileSdk 34
    
        defaultConfig {
            minSdk 21
            // ...
        }
    }

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 21
            // ...
        }
    }
  5. Dans la section buildFeatures de votre fichier build.gradle au niveau du module, ajoutez la classe BuildConfig, que vous utilisez pour accéder aux valeurs de métadonnées définies ultérieurement dans cette procédure:

    Groovy

    android {
      // ...
      buildFeatures {
        buildConfig true
        // ...
      }
    }

    Kotlin

    android {
      // ...
      buildFeatures {
        buildConfig = true
        // ...
      }
    }

Étape 3 : Ajoutez votre clé API au projet

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.

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

  1. Dans Android Studio, ouvrez votre fichier build.gradle ou build.gradle.kts de premier niveau et ajoutez le code suivant à l'élément dependencies sous 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. Ouvrez le fichier build.gradle au niveau du module et ajoutez le code suivant à l'élément plugins.

    Groovy

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. Dans le fichier 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.
    PLACES_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.

    PLACES_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 Android Studio, ouvrez le fichier build.gradle ou build.gradle.kts 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éfinissez toute autre propriété.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

Étape 4. Initialiser le client API Places

Initialisez le SDK Places pour Android dans une activité ou un fragment. Vous devez d'abord déterminer la version du SDK à utiliser: SDK Places pour Android ou SDK Places pour Android (nouveau). Pour en savoir plus sur les versions du produit, consultez Choisir la version de votre SDK.

L'exemple suivant montre comment initialiser le SDK pour les deux versions.

SDK Places pour Android (nouveau)

Transmettez la clé API lorsque vous appelez Places.initializeWithNewPlacesApiEnabled():

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

SDK Places pour Android

Transmettez la clé API lorsque vous appelez Places.initialize():

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initialize(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initialize(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

Vous êtes maintenant prêt à utiliser le SDK Places pour Android.

Étape 5 : Configurez un appareil Android

Pour exécuter une application qui utilise le SDK Places pour Android, vous devez la déployer sur un appareil Android ou un émulateur Android qui exécute Android 4.0 ou une version ultérieure et inclut les API Google.

  • Pour utiliser un appareil Android, suivez les instructions fournies dans Exécuter des applications sur un appareil matériel.
  • Pour utiliser un émulateur Android, vous pouvez créer un appareil virtuel et installer l'émulateur à l'aide d'AVD Manager (le gestionnaire d'appareils virtuels Android) fourni avec Android Studio.

Étapes suivantes

Une fois votre projet configuré, vous pouvez explorer les applications exemples.