設定 Android Studio 專案

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

步驟 1:設定 Android Studio

  1. 必須使用 Android Studio Arctic Fox 或更新版本。如果您尚未下載安裝,請先完成此步驟。
  2. 確認您在 Android Studio 中使用的是 Android Gradle 外掛程式 7.0 以上版本

步驟 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:

    dependencies {
        implementation 'com.google.android.libraries.places:places:3.3.0'
    }
    
  4. 在模組層級 build.gradle 檔案中,將 compileSdkminSdk 設為下列值:
    android {
        compileSdk 31
    
        defaultConfig {
            minSdk 21
            // ...
        }

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

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

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

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

  1. 在 Android Studio 中開啟專案層級的 build.gradle 檔案,然後將下列程式碼加進 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. 儲存檔案,然後使用 Gradle 同步處理專案
  4. 在專案層級目錄中開啟 secrets.properties 並新增下列程式碼,然後將 YOUR_API_KEY 替換成您的 API 金鑰。
    MAPS_API_KEY=YOUR_API_KEY 
  5. 儲存檔案。
  6. 在您的 AndroidManifest.xml 檔案中,前往 com.google.android.geo.API_KEY 並按照以下方式更新 android:value attribute
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
  7. 視需要編輯外掛程式的屬性,指定不同的 Secrets 檔案或其他屬性。 在 Android Studio 中開啟專案層級的 build.gradle 檔案,然後編輯 secrets 屬性:

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

注意事項:如上所示,API 金鑰的建議中繼資料名稱為 com.google.android.geo.API_KEY。具備這個名稱的金鑰可用來驗證 Android 平台上的多個 Google 地圖相關 API,包括 Places SDK for Android。為了兼顧回溯相容性,API 也支援 com.google.android.maps.v2.API_KEY 這個名稱。此舊版名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式只能指定這兩種 API 金鑰中繼資料名稱的其中一個;如果同時指定兩者,API 會擲回例外狀況。

步驟 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

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

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

Java

    // 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



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

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

      

Java


    // 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) 建立虛擬裝置並安裝模擬器。

後續步驟

專案設定完畢後,您可以探索範例應用程式