開始在 Android 上使用進階方案

Google Maps APIs Premium Plan 授權為 Google Maps Android API 提供更進一步的支援。 本文件將介紹如何打造一款使用包含 Premium Plan 的 Google Maps Android API 之 Android 應用程式。

總覽

請依照本頁的指示來下載 SDK、設定專案並新增地圖。 以下是必須執行之步驟的摘要:

  1. 下載 SDK。
  2. 將 SDK 新增至新的或現有 Android 專案。
  3. 將 API 金鑰新增至應用程式宣示說明。
  4. 指定所需的 Android 權限與 OpenGL ES 第 2 版。
  5. 新增地圖。

下載 SDK

您可以將 SDK 下載為靜態程式庫,或使用 Android SDK Manager。

選項 1:將 SDK 下載為靜態程式庫

將最新版本下載為靜態程式庫

選項 2:使用 Android SDK Manager 下載 SDK

在 Android Studio 中:

  1. 選擇 [Tools] > [Android] > [SDK Manager]。
  2. 選擇 [Appearance & Behavior] > [System Settings] > [Android SDK]。
  3. 按一下 [SDK Update Sites] 標籤。
  4. 按一下加號 (+) 圖示來新增網站。
  5. 輸入名稱(例如「Google Maps for Work」)及其 URL: https://dl.google.com/geosdk/android-m4b-addon.xml
  6. 按一下 [OK]。
  7. 按一下 [SDK Tools] 標籤。
  8. 選擇 Google Maps Mobile SDK for Work 並按一下 [OK] 來完成下載。

Android Studio 會將程式庫安裝於 <android-sdk-folder>/extras/google/maps_for_business_sdk/

請參閱 Android SDK Manager 指南來取得將 Android SDK Manager 作為獨立工具使用的操作說明。

將 SDK 新增至專案

以下是針對 Android Studio 的操作說明。 若您使用的是其他工具,請參閱 Android 文件中對於命令列使用方式的操作說明。

Premium Plan 的 Google Maps Android API 有兩種格式:aar 組合 (google-maps-sdk-m4b.aar) 以及程式庫模組 (google-maps-sdk-m4b_lib)。

您可以自行選擇最適合您的格式。

選項 1:從 aar 組合中匯入 SDK

依照這些步驟來將 aar 組合(google-maps-sdk-m4b.aar)併入 Android Studio 專案:

  1. 瀏覽至此位置的 Google Maps APIs Premium Plan:

    <android-sdk>/extras/google/maps_for_business_sdk

  2. google-maps-sdk-m4b.aar 檔案複製到您專案中的 libs 目錄。 (如果目錄不存在,請建立目錄。)

  3. build.gradle 檔案中新增下列程式碼:

    dependencies {
        compile(name:'google-maps-sdk-m4b', ext:'aar')
    
    }
    
    repositories {
        flatDir{
            dirs 'libs'
        }
    }
    
  4. 如下所示,完成設定步驟。

選項 2:將 SDK 作為程式庫模組匯入

除了使用 aar 檔案外,您可以依照這些步驟來將 SDK 程式庫模組 (google-maps-sdk-m4b_lib) 新增到 Android Studio 中現有的專案:

  1. 在 Android Studio 中,選擇匯入新模組的選項 ([File] -> [New] -> [Import Module])。

  2. 瀏覽至此位置的 SDK:

    <android-sdk>/extras/google/maps_for_business_sdk

  3. 選擇 google-maps-sdk-m4b_lib 目錄,並按一下 [Choose]。

  4. 接受匯入精靈中的預設值。
  5. 按一下 [Finish]。 您將看到摘要匯入程序結果的文字檔。

  6. 請確認程式庫已包含在 settings.gradle 檔案中:

    include ':googlemapssdkm4b_lib'

  7. 在應用程式 build.gradle 檔案中新增模組相依性:

    compile project(':googlemapssdkm4b_lib')

轉換所有使用 Google Play 服務的現有設定

  1. 若您現有的應用程式使用 Google Play 服務,請將所有對於 com.google.android.gms.maps 套件的參照取代為 com.google.android.m4b.maps

  2. 請在所有對於 XML 版面配置屬性的參照前面加上 m4b_。 例如: m4b_mapTypem4b_cameraZoom

在應用程式宣示說明中指定設定

使用 Google Maps Android API 的 Android 應用程式必須在其宣示說明檔案(AndroidManifest.xml)中指定下列設定:

API 金鑰

驗證指南中所述,請為您的專案產生 API 金鑰,並將金鑰新增至 AndroidManifest.xml

權限

透過在 AndroidManifest.xml 中新增 <uses-permission> 元素做為 <manifest> 元素的子項,以指定您的應用程式需要的權限。

位置權限

如果您的應用程式透過啟用「我的位置」圖層來存取使用者的目前位置,您必須要求位置權限,如位置資料指南中所述。

外部儲存空間權限

如果您是以 Google Play Services SDK 8.3 版或更新版本為目標,使用 Google Maps Android API 已不再需要 WRITE_EXTERNAL_STORAGE 權限。

如果您是以版本更舊的 Google Play Services SDK 為目標,您必須要求 android.permission.WRITE_EXTERNAL_STORAGE 權限。

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

注意:如果您的應用程式是以需要使用執行階段權限的 API 層級 23 (Android 6.0) 為目標,您「應該」以 Google Play Services SDK 8.3 版或更新版本為目標。

權限會自動合併到宣示說明

下列權限定義在 Google Play 服務宣示說明中,並會在建置期間自動合併到您應用程式的宣示說明。您需要明確地將它們新增到您的宣示說明:

OpenGL ES 第 2 版

Google Maps Android API 使用 OpenGL ES 第 2 版來轉譯地圖。下列設定定義在 Google Play 服務宣示說明中,並會在建置期間自動合併到您應用程式的宣示說明。您不需要明確地將它新增到您的宣示說明:

<uses-feature
        android:glEsVersion="0x00020000"
        android:required="true"/>

這樣會通知外部服務相關需求。特別地,它會使 Google Play 商店避免在不支援 OpenGL ES 第 2 版的裝置上顯示您的應用程式。

新增地圖

測試應用程式是否已正確設定的最簡單方法是新增一個簡單的地圖。

注意:請勿將此段程式碼用於生產應用程式。

  1. activity_main.xml 中,新增下列片段。

    <?xml version="1.0" encoding="utf-8"?>
    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
              android:id="@+id/map"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              android:name="com.google.android.m4b.maps.MapFragment"/>
    
  2. MainActivity.java 中,新增下列程式碼。

    package com.example.mapdemo;
    
    import android.app.Activity;
    import android.os.Bundle;
    
    public class MainActivity extends Activity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
        }
    }
    

建置並執行您的應用程式

建置並執行您的應用程式。 您應該會看到一份地圖。

疑難排解:

  • 如果您並未看到地圖,請確認您已完成本文中所有上述步驟。 請您特別確認 API 金鑰是否正確,以及您的帳號是否已啟動 Google Maps APIs Premium Plan 服務。

  • 如果專案中的方法數量超過限制,您可能會收到錯誤訊息:

    Unable to execute dex: method ID not in [0, 0xffff]: 65536

    若要了解此錯誤的原因及解決辦法,請參閱 Android 開發人員指南中的 建置超過 65K 個方法的應用程式

  • 如果您的專案已依存於 Guava,您可能會收到如下的類別衝突錯誤:

    com.android.dex.DexException:Multiple dex files define Lcom/google/common/annotations/Beta

    若要解決此問題,您可以在 google-maps-sdk-m4b_lib/libs 目錄中刪除 Guava。

更多資訊

如何遷移現有應用程式

Premium Plan 提供的 Android API 在設計上與標準的 Google Maps Android API 非常相似。

因此,遷移程序很簡單。

  1. 下載 Premium Plan 的 Google Maps Android API,並依上述步驟將 SDK 新增至您的專案。

  2. 將所有對於 com.google.android.gms.maps 套件的參照取代為 com.google.android.m4b.maps

  3. 請在所有對於 XML 版面配置屬性的參照前面加上 m4b_。 例如: m4b_mapTypem4b_cameraZoom

  4. 驗證指南中所述,請為您的專案產生新的 API 金鑰,並將金鑰新增至 AndroidManifest.xml

  5. 建置應用程式。

版本比較

下列表格說明標準版 Google Maps Android API 與 Premium Plan API 在使用上的主要差異。

  標準 Google Maps Android API Premium Plan
套件名稱 com.google.android.gms.maps com.google.android.m4b.maps
版面配置檔案中的 XML 屬性 屬性名稱不加前置詞。 例如: mapType 屬性名稱前面加上 m4b_。 例如: m4b_mapType。 如需詳細資訊,請參閱 XML 屬性的文件
下載位置 包含在 Google Play 服務 可作為靜態程式庫。
支援管道 社群支援 可取得進階版支援
條款 Google Maps APIs 服務條款規範。 Google Maps APIs Premium Plan 條款規範。

Google Play 服務

標準版 Google Maps Android API 同時需要 Google Play 服務 APK 及 Google Play 服務用戶端程式庫。 然而,使用 Google Maps APIs Premium Plan 時,SDK 僅要求在目標裝置上安裝 Google Play 服務 APK - 無需用戶端程式庫。

將應用程式遷移至 Premium Plan 時,您不需要在專案中移除 Google Play 服務 SDK。

不過,您應移除所有對於 com.google.android.gms.maps 套件的參照。 Google Play 服務包含一版 Google Maps Android API 以及其他 Google 服務。 如果您在應用程式中透過 Play 服務來使用其他 Google API,請確認您僅使用 Premium Plan SDK(com.google.android.m4b.maps 套件)來存取 Google 地圖。

雖然 Google Play 服務用戶端程式庫並非必要,但仍相當實用,有了這個程式庫,您便能使用其他 Google API,例如 Google+ 或 Location API。

範例程式碼

GitHub 上的 Google 地圖存放庫包括數個範例,這些範例示範如何在您的 Android 應用程式中使用 Google Maps Android API。

請注意,範例應用程式使用的是 com.google.android.gms.maps 套件,而非搭配 Premium Plan 使用的 com.google.android.m4b.maps

由於範例應用程式使用 Location API 進行部分示範,因此也需要 Google Play 服務 SDK

此外,您可以在開發人員指南的每個頁面上找到程式碼片段。

文件

Google Maps APIs Premium Plan 的相關資訊主要來自於我們網站上提供的開發人員文件與參考資料。