Configurar um projeto do Android Studio

Se quiser configurar seu app para usar o SDK do Places para Android, siga estas etapas. Eles são obrigatórios para todos os apps que usam o SDK do Places para Android.

Etapa 1: configurar o Android Studio

Este documento descreve um ambiente de desenvolvimento usando o Android Studio Hedgehog e a versão 8.2 do Plug-in do Android para Gradle.

Etapa 2: configurar o SDK

A biblioteca do SDK do Places para Android está disponível no repositório Maven do Google. Para adicionar o SDK ao app, faça o seguinte:

  1. No arquivo settings.gradle de nível superior, inclua o portal do plug-in do Gradle, o repositório Maven do Google e o repositório Maven central no bloco pluginManagement. O bloco pluginManagement precisa aparecer antes de qualquer outra instrução no script.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. No arquivo settings.gradle de nível superior, inclua o repositório Maven do Google e o repositório Maven central (links em inglês) no bloco dependencyResolutionManagement:
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. Na seção dependencies do arquivo build.gradle do módulo, adicione uma dependência ao SDK do Places para 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. No arquivo build.gradle no nível do módulo, defina compileSdk e minSdk como os seguintes valores:

    Groovy

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

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 21
            // ...
        }
    }
  5. Na seção buildFeatures do arquivo build.gradle do módulo, adicione a classe BuildConfig, que é usada para acessar os valores de metadados definidos posteriormente neste procedimento:

    Groovy

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

    Kotlin

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

Etapa 3: adicionar sua chave de API ao projeto

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 esse plug-in no seu projeto do Google Maps:

  1. No Android Studio, abra o arquivo de nível superior build.gradle ou build.gradle.kts 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 módulo e adicione o seguinte código ao elemento plugins.

    Groovy

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. No arquivo build.gradle no nível do módulo, defina targetSdk e compileSdk como 34.
  4. Salve o arquivo e sincronize seu projeto com o Gradle.
  5. 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. Armazene sua chave nesse arquivo porque secrets.properties não é verificado em um sistema de controle de versões.
    PLACES_API_KEY=YOUR_API_KEY
  6. Salve o arquivo.
  7. 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.

    PLACES_API_KEY=DEFAULT_API_KEY

    O objetivo desse arquivo é oferecer um local de backup para a chave da 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.

  8. Salve o arquivo.
  9. No Android Studio, abra o arquivo build.gradle ou build.gradle.kts 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, defaultPropertiesFileName como local.defaults.properties e defina outras propriedades.

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

Etapa 4. Inicializar o cliente da API Places

Inicialize o SDK do Places para Android em uma atividade ou um fragmento. Primeiro, você precisa decidir qual versão do SDK usar: SDK do Places para Android ou SDK do Places para Android (novo). Para mais informações sobre versões do produto, consulte Escolher a versão do SDK.

O exemplo a seguir mostra como inicializar o SDK para as duas versões.

SDK do Places para Android (novo)

Transmita a chave de API ao chamar 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 do Places para Android

Transmita a chave de API ao chamar 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);
    

Agora você já pode usar o SDK do Places para Android.

Etapa 5: configurar um dispositivo Android

Para executar um app que usa o SDK do Places para Android, faça a implantação dele em um dispositivo compatível ou Android Emulator com base no Android 4.0 ou uma versão mais recente que inclua as APIs do Google.

  • Para usar um dispositivo Android, siga as instruções no artigo Executar apps em um dispositivo de hardware.
  • Para usar o Android Emulator, crie um dispositivo virtual e instale o emulador usando o AVD Manager que acompanha o Android Studio.

Próximas etapas

Depois que o projeto estiver configurado, explore os apps de exemplo (link em inglês).