Android開發筆記-Google Maps Android API v2

內容說明:建立Google地圖的前置作業。

資料來源:Google Developers

Google Maps Android API 更新至 v2 的版本,導致 v1 的舊程式已經無法使用。為了避免混淆 v1 的文章已經關閉。由於站長對 v2 沒有研究,目前僅撰寫本篇基礎的建置,進階的使用方式請參考其他網站或書籍。另外,若是您的程式採用 HTML5 撰寫,可以參考 Google Maps JavaScript API v3,在您的網頁中添加Google地圖。本篇為Android原生程式的Google地圖基礎說明。

取得金鑰的憑證指紋(SHA1)

在向Google申請API Key之前,我們必需要先取得自己金鑰的SHA1。這裡的金鑰有兩種,一種是開發中的金鑰,另一種則是要發佈用的金鑰。如果我們一開始就使用發佈的金鑰,那麼就會無法在模擬器上顯示結果,因此在開發過程中,還是先使用臨時的金鑰來測式。要找到你開發金鑰的位置,可以開啟Eclipse > Windows > Preferences > Android > Build裡面有個debug.keystore檔案位置,即是開發用的金鑰。

取得憑證指紋的方法可參考官方網站。由於本系列文章沒有教大家設定「環境變數」,所以這裡就寫一個批次檔(bat)給大家參考。開啟一個記事本,將下面語法貼上。修改”C:\j2sdk1.4.2_10”成自己電腦裡 Java SDK 的安裝路徑修,並且把”C:\Users...“改成自己電腦裡金鑰的位置。androiddebugkey 是金鑰名稱,後面兩個 android 是存取與金鑰密碼,Android的debug金鑰資訊可參考官方說明。最後另存成 getDebugMD5.bat 批次檔(注意後面沒有.txt),在這個檔案上直接點擊滑鼠二下,就會在bat檔旁邊多出一個debugKey.txt,這個txt裡面就有我們要的憑證指紋SHA1。

C:\j2sdk1.4.2_10\bin\keytool -list -v -keystore "C:\Users\Davina\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android >> debugKey.txt

建立私人金鑰 (發佈到Android平台時才需要使用)

要取得私人金鑰,必需透過Java SDK來完成。詳細說明請參考官方網站,這裡只提供一個速成的範例。開啟一個記事本,將下面語法貼上。修改”C:\j2sdk1.4.2_10”成自己電腦裡Java SDK的安裝路徑修,把filename改成自己要取的金鑰檔名,並設定key_name。最後另存成 getPrivateKey.bat 批次檔(注意後面沒有.txt),在這個檔案上直接點擊滑鼠二下,系統會詢問一些關於開發者的資料與密碼,最後就會在bat檔旁邊多出一個 filename.keystore,即是私人金鑰。對於準備好要發佈的程式,在建立私人金鑰後,回到上面取得憑證指紋的步驟,再按照下面的方法把API Key加入程式專案中。

C:\j2sdk1.4.2_10\bin\keytool -genkey -v -keystore filename.keystore -alias key_name -keyalg RSA -keysize 2048 -validity 10000

建立API Project

在取得 Google Map API Key 之前,我們必須到 Google APIs Console 建立一個 API Project。第一次進入 Google APIs Console 時,會出現下面的畫面,直接點擊 Create Project 即可。

Google APIs Console

你可以替不同的專案建立不同的Project,如果想要建立新的Project或更改名字,點選左上角的專案名稱(預設為API Project)即可。接下來要將 Google Maps Android API v2 的服務開啟。首先點選左側目錄的 Services,如下圖所示:

API Project Services

接著把捲軸往下拉找到「Google Maps Android API v2」(或按 Ctrl+F 搜尋),把中間的「OFF」轉成「ON」,然後跳到同意書:

Google Maps Android API v2 Terms

點選同意後,可以看到 Google Maps Android API v2 的服務已經開啟:

Google Maps Android API v2

取得API Key (2013.01.19 更新)

API Key是我們到 Google APIs Console 的最終目的。取得方法是點選左側選單的 API Access,並且按下 Create New Android Key:

於是會出現一個對話視窗,要我們輸入金鑰的SHA-1憑證指紋與程式的package名稱,這時候前面「取得金鑰的憑證指紋」所產生的檔案資料就派上用場了,我們可以在那裡找到 SHA1 的憑證指紋。除了憑證指紋外,還要輸入程式專案的package名稱,格式為「憑證指紋;package名稱」(分號分隔),例如「B5:99:05:3F:00:F4:9C:18:14:9C:32:ED:C3:CF:F2:10:FB:1D:C6:41;moke.test.googlemap」。package名稱預設是包含專案名稱的(請看main.java第一行),所以每個專案有獨自的API Key,另外官方也建議在發佈時給每個專案不同的私人金鑰。

輸入完成後按下 Create,就會在畫面上看到新增一例 Key for Android apps,裡面的 API key 會在後面使用到。

安裝 Google Play services SDK

在取得API key之後,接下來是環境建置。由於Google Map API必須使用到 Google Play services API,所以我們必須先安裝 Google Play services 的環境。在安裝之前,請先確認 ADT 和 Android SDK 的版本是最新的,可以到 Help > Check for Updates 更新,或重新安裝

參考官方說明,首先到 Eclipse 的 Android SDK Manager 最下面 Extras 尋找 Google Play services 並且安裝。

接著到 Eclipse 的 File > Import,選擇 Android > Existing Android Code into Workspace 匯入 /extras/google/google_play_services/libproject/google-play-services_lib 專案。

到這裡就完成了 Google Play services SDK 的安裝。當我們的專案要使用 Google Play services 時,直接在專案資料夾上點選滑鼠右鍵選擇 Properties,到 Android > Library 按下 Add 加入 google-play-services_lib,即可完成 Google Play services 的建置,請參考下圖。

應用程式設定與權限 (2013.01.06 新增)

在取得 API Key 並且設定好 Google Play services 後,必須將 API Key 設定到 AndroidManifest.xml,並且開啟許多 Google Map 的相關權限。首先開啟AndroidManifest.xml,在前面加入 API Key,第 27 行的 your_api_key 要換成上面在 Google APIs Console 申請到的 API Key:

...
        <meta-data
            android:name="com.google.android.maps.v2.API_KEY"
            android:value="your_api_key"/>
    </application>

接著要在後面加入各項 Google 權限。第 30、32 行的 moke.test.googlemap 要記得換成自己程式的 package 名稱。29-32 行是 API Key;33 行開啟網路存取權限,讓 API 可以下載地圖;34 行允許API將地圖暫存檔存在外部儲存裝置;35 行允許API存取 Google web-based 服務;36 行允許API使用 WiFi 或行動網路的服務;37 行允許API使用GPS定位;Google Maps Android API 2 會使用到 OpenGL ES version 2,所以必須加入 38 行的設定,以避免 Google Play Store 認為我們的 App 不支援 OpenGL ES version 2。

<permission
        android:name="moke.test.googlemap.permission.MAPS_RECEIVE"
        android:protectionLevel="signature"/>
    <uses-permission android:name="moke.test.googlemap.permission.MAPS_RECEIVE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-feature android:glEsVersion="0x00020000" android:required="true"/>

加入地圖 (2013.01.19 更新)

一個最簡易的地圖程式是在 main.xml 加入下面的程式碼,前面有提到必須使用實機測式,所以這在模擬器是無法執行的(在模擬器上它會要你更新Google Play)。

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    class="com.google.android.gms.maps.MapFragment"/>

ps. 我從電腦編譯程式到平板上執行時,不曉得為什麼會一次跑出兩個程式(一個沒有畫面),但回到平板直接執行程式時就沒有這種問題了。

關於 Google Maps Android API v2 更進一步的說明可以參考官方說明文件

無法顯示地圖時 (2013.01.19新增)

  1. 請確認開發時使用debug.keystore產生SHA1
  2. API Key及應用程式權限要加入AndroidManifest.xml
  3. 請確認網路通行(最好在開放的網路進行測式)