設定 Android Studio 專案

如要將應用程式設為使用 Places SDK for Android,請按照下列步驟操作。所有使用 Places SDK for Android 的應用程式都必須使用 API。

步驟 1:設定 Android Studio

本文件說明使用 Android Studio HedgehogAndroid Gradle 外掛程式 8.2 版的開發環境。

步驟 2:設定 SDK

您可透過 Google 的 Maven 存放區存取 Places SDK for Android 程式庫。如要將 SDK 加入應用程式,請按照下列步驟操作:

  1. 在頂層 settings.gradle 檔案的 pluginManagement 區塊下方,加入 Gradle 外掛程式入口網站Google Maven 存放區,以及 Maven 中央存放區pluginManagement 區塊必須放在指令碼中的任何其他陳述式之前。
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. 在頂層 settings.gradle 檔案的 dependencyResolutionManagement 區塊下方,加入 Google Maven 存放區Maven 中央存放區
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. 模組層級 build.gradle 檔案的 dependencies 區段中,將依附元件新增至 Places SDK for 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. 在模組層級 build.gradle 檔案中,將 compileSdkminSdk 設為以下值:

    Groovy

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

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 21
            // ...
        }
    }
  5. 在模組層級 build.gradle 檔案的 buildFeatures 區段中,新增 BuildConfig 類別。您可以用該類別存取這個程序稍後定義的中繼資料值:

    Groovy

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

    Kotlin

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

步驟 3:將 API 金鑰加到專案

本節將說明如何儲存 API 金鑰,讓應用程式以安全的方式參照金鑰。API 金鑰不應該登錄在版本管控系統中;我們建議將金鑰儲存在位於專案根目錄的 secrets.properties 檔案內。如要進一步瞭解 secrets.properties 檔案,請參閱這篇文章中關於 Gradle 屬性檔案的說明

建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。

如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android,請按照下列步驟操作:

  1. 在 Android Studio 中開啟頂層的 build.gradlebuild.gradle.kts 檔案, 然後將下列程式碼加進 buildscript 下方的 dependencies 元素。

    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. 開啟模組層級的 build.gradle 檔案,然後將下列程式碼加進 plugins 元素。

    Groovy

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. 在模組層級的 build.gradle 檔案中,確認 targetSdkcompileSdk 已設為 34。
  4. 儲存檔案,然後使用 Gradle 同步處理專案
  5. 開啟頂層目錄中的 secrets.properties 檔案,並加入下列程式碼,然後將 YOUR_API_KEY 替換成您的 API 金鑰。secrets.properties 不會登錄在版本管控系統中,因此請將金鑰儲存至該檔案。
    PLACES_API_KEY=YOUR_API_KEY
  6. 儲存檔案。
  7. 在頂層目錄 (與 secrets.properties 檔案相同的資料夾) 中建立 local.defaults.properties 檔案,然後加入下列程式碼。

    PLACES_API_KEY=DEFAULT_API_KEY

    如果找不到 secrets.properties 檔案,這個檔案便可做為 API 金鑰的備份位置,以確保建置程序不會失敗。如果您從略過 secrets.properties 的版本管控系統複製應用程式,且尚未在本機建立 secrets.properties 檔案來提供 API 金鑰,就可能會發生這種情況。

  8. 儲存檔案。
  9. 在 Android Studio 中開啟模組層級的 build.gradlebuild.gradle.kts 檔案,然後編輯 secrets 屬性。如果 secrets 屬性不存在,請新增該屬性。

    編輯外掛程式的屬性,將 propertiesFileName 設為 secrets.properties、將 defaultPropertiesFileName 設為 local.defaults.properties,以及設定任何其他屬性。

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

步驟 4:初始化 Places API 用戶端

在活動或片段中初始化 Places SDK for Android。您必須先決定要使用的 SDK 版本:Places SDK for Android 或 Places SDK for Android (新版)。如要進一步瞭解產品版本,請參閱「選擇 SDK 版本」一文。

以下範例說明如何初始化這兩個版本的 SDK。

Places SDK for Android (新推出)

呼叫 Places.initializeWithNewPlacesApiEnabled() 時傳遞 API 金鑰:

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

Places SDK for Android

呼叫 Places.initialize() 時傳遞 API 金鑰:

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

您現在可以開始使用 Places SDK for Android 了!

步驟 5:設定 Android 裝置

如要執行使用 Places SDK for Android 的應用程式,請務必將該應用程式部署至採用 Android 4.0 以上版本且包含 Google API 的 Android 裝置或 Android 模擬器。

  • 如要使用 Android 裝置,請按照在硬體裝置上執行應用程式一文的說明操作。
  • 如要使用 Android 模擬器,您可以使用 Android Studio 隨附的 Android 虛擬裝置管理工具 (AVD Manager) 建立虛擬裝置並安裝模擬器。

後續步驟

專案設定完成後,即可探索範例應用程式