Configurar um projeto do Android Studio

AVISO: A versão 2.0.0 ou mais recente do SDK do Places para Android depende do AndroidX: A partir desta versão, a antiga Biblioteca de Suporte não será mais suporte. Para manter a compatibilidade, é necessário migrar seus projetos para usar o AndroidX.

Se quiser configurar seu app para usar o SDK do Places para Android, siga estas etapas: etapas. Eles são necessá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.

Observação: se o seu ambiente de desenvolvimento usa uma versão diferente do Android Studio ou do Gradle, recomendamos seguir as etapas de acordo com as versões em questão. Para mais informações sobre as versões do Android Studio e do Gradle, consulte Compatibilidade entre o Plug-in do Android para Gradle e o Android Studio.

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.kts 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.kts 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. No dependencies do arquivo build.gradle no nível do módulo, adicione uma dependência SDK do Places para Android:

   Observação : versão do SDK do Places para Android 3.5.0 requer o kotlin-bom 1.8.0 ou mais recente. Para mais informações sobre a dependência kotlin-bom, consulte Uso da versão mais recente da kotlin-stdlib em dependências transitivas.

   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.5.0")
   }

4. No arquivo build.gradle no nível do módulo, defina compileSdk. e minSdk aos seguintes valores:
   Observação:verifique se compileSdk está definido como 34 ou maior e minSdk está definido como 21 ou mais.

   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 será usada para acessar 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.

Observação: consulte a documentação do plug-in Secrets Gradle para Android (link em inglês) no GitHub para conferir os requisitos mais recentes do sistema e instruções de instalação.

Para instalar esse plug-in no seu projeto do Google Maps:

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

   Kotlin

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

   Groovy

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

3. No arquivo build.gradle.kts ou build.gradle no nível do módulo, verifique se targetSdk e compileSdk estão definidos para 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.
   Observação: se o arquivo secrets.properties não existe, crie-o na mesma pasta que o arquivo local.properties.

   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.

   Observação: insira o código conforme mostrado. Não substitua DEFAULT_API_KEY pela sua chave de API.

   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 nível do módulo build.gradle.kts ou build.gradle e edite a propriedade secrets. Se o A propriedade secrets não existe, adicione-a.

   Edite as propriedades do plug-in para definir propertiesFileName como secrets.properties, defina defaultPropertiesFileName como local.defaults.properties e defina 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 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.*"
   }
           

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)

Transmitir 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

Transmitir 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);
    

IMPORTANTE: nunca adicione chaves de API diretamente ao no código do aplicativo. Em ambientes de produção, recomendamos o uso de um mecanismo seguro para gerenciar chaves de API.

Agora está tudo pronto para você começar a 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, ele precisa ser implantado em um dispositivo Android ou Android emulador baseado no Android 5.0 ou superior e 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.
  Observação: se você quiser usar um Android Emulator, selecione um dispositivo com o ícone do Google Play , mostrado na coluna Play Store. Esse ícone indica que os perfis obedecem completamente ao CTS e podem usar imagens do sistema que incluem o app Play Store:

  

Próximas etapas

Depois de configurar o projeto, explore o aplicativos de exemplo.