舊版 Google Maps Mobile SDK for Work:Android

針對擁有舊版 Google Maps APIs for Work或 Google Maps API for Business 授權的客戶,Google Maps Android API 是作為 Google Maps Mobile SDK for Work 的一部分而購買的。

本節介紹該 SDK 的設定。

本頁面僅適用於舊版 Maps APIs for Work 或 Maps API for Business 授權的客戶。本頁面不適用於 2016 年 1 月推出之新版 Google Maps APIs Premium Plan 的客戶。

總覽

請依照本頁的指示來下載 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 APIs」)及其 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 文件中對於命令列使用方式的操作說明。

Google Maps Mobile SDK for Work 的 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 Mobile SDK for Work:

    <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

取得 API 金鑰並新增至應用程式如下所述,請為您的專案產生 API 金鑰,並將金鑰新增至 AndroidManifest.xml

您需要設定 Android 限定 API 金鑰

API 金鑰會將您識別為 Google Maps Mobile SDK for Work 客戶,並為您的應用程式啟用支援與已購買配額。

您可以使用應用程式的套件名稱與數位憑證的組合,來在已啟用 Google Maps Mobile SDK 服務的帳戶上產生 API 金鑰。

API 金鑰以您應用程式的數位憑證之簡短形式為依據。 所有 Android 應用程式都會使用您持有私密金鑰的數位憑證簽署。 (請參閱簽署應用程式之 Android 指南,瞭解有關數位憑證的詳細資訊。)

顯示應用程式的憑證資訊

Android API 金鑰限制是以您應用程式數位憑證的簡短形式為依據,也就是憑證的 SHA-1 指紋

從 Android Studio 取得認證資訊

如果您遵照 Google Maps Android API 入門指南,Android Studio 會使用您應用程式的憑證,建立方便的 google_maps_api.xml 檔案。

選擇下列其中一種方式從 Android Studio 取得您的 API 金鑰:

  • 最快速、簡單的方式:使用 Android Studio 為您建立的 google_maps_api.xml 檔案中提供的連結:
    1. 複製 google_maps_api.xml 檔案中提供的連結,然後在您的瀏覽器中貼上。該連結會帶您前往 Google API Console,並透過 URL 參數提供前往 Google API Console 的必要資訊,進而減少需要您手動輸入的次數。
    2. 依照指示在 Google API Console 上建立新的專案,或選取現有的專案。
    3. 為您的專案建立 Android 限定 API 金鑰。
    4. 複製產生的 API 金鑰,返回 Android Studio,然後將 API 金鑰黏貼到 google_maps_api.xml 檔案中的 <string> 元素。
  • 稍微慢一點的方式:使用 Android Studio 為您建立的 google_maps_api.xml 檔案中提供的憑證:
    1. 複製 google_maps_api.xml 檔案中提供的憑證。
    2. 在您的瀏覽器中前往 Google API Console
    3. 使用複製的憑證,將您的應用程式新增至現有的 API 金鑰,或建立新的 API 金鑰。

自行取得憑證資訊

如果您在建立應用程式時,未遵照入門指南,那麼您必須自行取得憑證的 SHA-1 指紋。首先,請確認您使用的是正確的憑證。您可能會有兩個憑證:

  • 偵錯憑證:Android SDK 工具會在您執行偵錯建置時自動產生此憑證。此憑證只能搭配您要測試的應用程式使用。請不要嘗試發佈使用偵錯憑證簽署的應用程式。在 Android 開發人員文件中的在偵錯模式中簽署對偵錯憑證有更詳細的說明。
  • 發行憑證:Android SDK 工具會在您執行發行建置時自動產生此憑證。您也可以使用 keytool 程式產生此憑證。請在您準備好在市場上公開發行應用程式時,才使用此憑證。

如果要顯示憑證的 SHA-1 指紋,請依照下列步驟,使用 keytool 程式搭配 -v 參數。如需有關 Keytool 的詳細資訊,請參閱 Oracle 文件

偵錯憑證

顯示偵錯憑證指紋

  1. 找出您的偵錯金鑰存放區檔案。檔案名稱為 debug.keystore,而且是在您第一次建置專案時建立。它預設會儲存在與 Android Virtual Device (AVD) 檔案相同的目錄:

    • macOS 與 Linux~/.android/
    • Windows Vista 與 Windows 7C:\Users\your_user_name\.android\
  2. 列出 SHA-1 指紋:

    • 對於 Linux 或 macOS,請開啟終端機視窗並輸入下列命令:

      keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    • 對於 Windows Vista 與 Windows 7,請執行:

      keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

您應該會看見類似下面的輸出:

Alias name: androiddebugkey
Creation date: Jan 01, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4aa9b300
Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033
Certificate fingerprints:
     MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9
     SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75
     Signature algorithm name: SHA1withRSA
     Version: 3
發行憑證

顯示發行憑證指紋

  1. 找出您的發行憑證金鑰存放區檔案。發行金鑰存放區並沒有預設的位置或名稱。如果您在建置供發行用的應用程式時沒有指定發行金鑰存放區,則該版本會讓您的 .apk 維持未簽署的狀態,您必須先將它簽署才能發佈。對於發行憑證,您還需要憑證的別名,以及金鑰存放區與憑證的密碼。您可以透過輸入下列命令,以列出金鑰存放區中所有金鑰的別名:

    keytool -list -keystore your_keystore_name

    your_keystore_name 取代為金鑰存放區的完整路徑與名稱,包括 .keystore 副檔名。接著會提示您輸入金鑰存放區的密碼。然後 keytool 就會顯示金鑰存放區中的所有別名。

  2. 在終端機或命令提示字元中輸入下列命令:

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    your_keystore_name 取代為金鑰存放區的完整路徑與名稱,包括 .keystore 副檔名。將 your_alias_name 取代為您建立憑證時指派給憑證的別名。

您應該會看見類似下面的輸出:

Alias name: <alias_name>
Creation date: Feb 02, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4cc9b300
Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
Certificate fingerprints:
    MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
    SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
    Signature algorithm name: SHA1withRSA
    Version: 3

SHA1 為開頭的那一行包含憑證的 SHA-1 指紋。指紋是以冒號分隔的 20 個兩位數十六進位數字序列。

請參閱簽署應用程式的 Android 指南,瞭解有關數位憑證的進一步資訊。

驗證您的帳戶已啟用 Google Maps Mobile SDK 服務

Google Cloud Support 團隊在您註冊 Google Maps Mobile SDK for Work 時,就會啟用 Google Maps Mobile SDK 服務。

服務會在新專案上啟用。 接著,您可以從 Google API Console 取得 API 金鑰。

注意:只有專案的最初擁有者能夠看到 Google Maps Mobile SDK 服務。 要為其他專案擁有者提出授權要求,以便讓他們看到服務,請在 Google Cloud Support Portal 提交非技術性案件。

驗證您的帳戶已啟用,如下所示:

  1. 造訪 Google API Console,並使用您的 Google 帳戶登入。
  2. 選擇您訂購 Google Maps Mobile SDK for Work 時,為您建立的 Google Maps Mobile SDK for Work 專案。 專案名稱將會以 Google Maps APIs for Business or Google Maps for Work or Google Maps 做為開頭。 如果您尚未購買 SDK 的存取權,請與銷售人員聯絡。

  3. 在「Dashboard」中,確認 API 清單中 Google Maps Mobile SDK* 是否已啟用。

從 Google API Console 取得 API 金鑰啟用您專案的 Google Maps Mobile SDK for Work 服務後,請務必產生新的金鑰。

  1. 前往 Google API Console 憑證頁面,並使用您的 Google 帳戶登入。

  2. 選擇您訂購 Google Maps Mobile SDK for Work 時,為您建立的 Google Maps Mobile SDK for Work 專案。 專案名稱將會以 Google Maps APIs for Business or Google Maps for Work or Google Maps 做為開頭。 如果您尚未購買 SDK 的存取權,請與銷售人員聯絡。

  3. API 金鑰清單中,尋找 Android 限定的金鑰。

  4. 若專案中尚未包含 Android 限定 API 金鑰,請選擇 [Create credentials] > [API key] 來立即建立新的金鑰。
  5. 在產生的對話方塊中,選擇 [Restrict key]。
  6. 在「Restrictions」區塊中,選擇 [Android apps],然後輸入應用程式的 SHA-1 指紋與套件名稱。 例如: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75 com.example.android.mapexample

  7. 按一下 Save

    您的新 Android 限定 API 金鑰會出現在您專案的 API 金鑰清單中。 API 金鑰是字元字串,類似於:

    AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
    

將 API 金鑰新增到您的應用程式

依照下面的步驟在您應用程式的宣示說明 (包含在檔案 AndroidManifest.xml 內) 中包括 API 金鑰。

  1. AndroidManifest.xml 中,將下列元素新增為 <application> 元素的子項,方式是透過在結尾的 </application> 標籤前面插入該元素:
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="YOUR_API_KEY"/>
        

    以您的 API 金鑰替代 value 屬性中的 YOUR_API_KEY。此元素會將金鑰 com.google.android.geo.API_KEY 設定為您的 API 金鑰值。

  2. 儲存 AndroidManifest.xml 並重新建置您的應用程式。

注意:如上所示,建議使用 com.google.android.geo.API_KEY 做為 API 金鑰的中繼資料名稱。名稱如上的金鑰可用來驗證 Android 平台上的多個 Google 地圖型 API,包括 Google Maps Android API。為提供回溯相容性,API 也支援名稱 com.google.android.maps.v2.API_KEY。此舊版名稱只能向 Android Maps API v2 驗證。應用程式只能指定這些 API 金鑰中繼資料名稱的其中一個。如果同時指定兩者,API 會擲回例外狀況。

指定應用程式權限

透過在 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"?>

  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 Mobile SDK for Work 服務。

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

    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。

更多資訊

如何遷移現有應用程式

Google Maps Mobile SDK for Work 提供的 Android API 在設計上與標準的 Google Maps Android API 非常相似。

因此,遷移程序很簡單。

  1. 下載 Google Maps Mobile SDK for Work 的 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 與 Google Maps Mobile SDK for Work API 在使用上的主要差異。

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

Google Play 服務

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

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

不過,您應移除所有對於 com.google.android.gms.maps 套件的參照。 Google Play 服務包含一版 Google Maps Android API 以及其他 Google 服務。 如果您在應用程式中透過 Play 服務來使用其他 Google API,請確認您僅使用 Google Maps Mobile SDK for Work 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 套件,而非搭配 Google Maps Mobile SDK for Work 使用的 com.google.android.m4b.maps

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

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

文件

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