Android 地圖與定位 (Maps and Positioning)(1)

Maps and Positioning

Google Maps Android API 第 1 版目前已不建議使用，這是第 2 版的使用筆記。

地圖概觀

使用 Google Maps Android API v2 的步驟：

1. 下載及設定 Google Play services SDK，Google Maps Android API 是這個 SDK 中的一部份。
2. 取得 API Key 。你必須在 Google APIs 控制台註冊一個專案，來取得一個簽核過的憑證給你的 App 使用。
3. 在 Application Manifest(AndroidManifest.xml) 中做相關的設定。
4. 在 Android 專案中加入地圖。
5. 發佈您的應用程式。

步驟 1 的 SDK 下載及設定，只有第一次使用時才需要。步驟 2 取得 API Key 的部份在測試時，使用除錯(debug)憑證；在真正發佈 App 時，再使用發佈(release)憑證去重新申請一個給發佈用的 API Key。步驟 3、4、5 在每次專案中都要做。

步驟 1. 下載 Google Play Services SDK

請開啟 SDK Manager ，在 Eclipse 的選單 Window -> Android SDK Manager。

捲到最下方的 Extras 目錄，勾選 Google Play Services 後 Install，如下圖： Google Play Services SDK 是一個以 Library Project 的形式存在，不像是 jar 檔可以直接加入到專案中的 libs 資料夾，所以使用方法稍為麻煩一點。

Google Play Service 運作流程： (圖片來源：http://developer.android.com/google/play-services/index.html)

你的 App 會透過這個 Client Library 去和 Google Play Services 溝通。

確定您已裝好 Google Play Services SDK 後，可以在這個目錄 <android-sdk-folder>/extras/google/google_play_services/libproject/google-play-services_lib 中看到這個 Library Project。記住這個路徑，然後開啟 Eclipse。(提醒：<android-sdk-folder>是指你的Android SDK目錄，每個人安裝的位置可能不一樣，)

在 Eclipse 中，File -> Import 選擇 Android -> Existing Android Code into Workspace ，在 Root Directory 欄位填入(或按下旁邊的瀏覽按鈕去尋找)剛才記住的路徑。完成後這個 Library Project 就加入 Eclipse 中了，之後你的任何專案都可以使用它，不需要再重做以上動作。

重要！Google Play Services SDK 只支援 Android 2.2 之後的系統。

使用 Library Project 的方式，是在 Eclipse 的 Package Explorer 中對你的專案名稱按右鍵 -> Properties，左邊選擇 Android ，右邊拉到最下方，在 Library 中點選 Add ，將剛才加入的 google-play-services_lib 加入就完成了。

在你的專案中 "Is Library" 是不會打勾的。如果你是在開發 Library 就要打勾，你可以去看 google-play-services_lib 專案的這個選項，就會是打勾的。

這裡要做個簡單的錯誤檢查，確定使用者的裝置上是否能夠使用 Google Play Services。
程式碼如下：

private void checkGooglePlayServices(){
    int result = GooglePlayServicesUtil.isGooglePlayServicesAvailable(this);
    switch (result) {
        case ConnectionResult.SUCCESS:
            Log.d(TAG, "SUCCESS");
            break;

        case ConnectionResult.SERVICE_INVALID:
            Log.d(TAG, "SERVICE_INVALID");
            GooglePlayServicesUtil.getErrorDialog(ConnectionResult.SERVICE_INVALID, this, 0).show();
            break;

        case ConnectionResult.SERVICE_MISSING:
            Log.d(TAG, "SERVICE_MISSING");
            GooglePlayServicesUtil.getErrorDialog(ConnectionResult.SERVICE_MISSING, this, 0).show();
            break;

        case ConnectionResult.SERVICE_VERSION_UPDATE_REQUIRED:
            Log.d(TAG, "SERVICE_VERSION_UPDATE_REQUIRED");
            GooglePlayServicesUtil.getErrorDialog(ConnectionResult.SERVICE_VERSION_UPDATE_REQUIRED, this, 0).show();
            break;

        case ConnectionResult.SERVICE_DISABLED:
            Log.d(TAG, "SERVICE_DISABLED");
            GooglePlayServicesUtil.getErrorDialog(ConnectionResult.SERVICE_DISABLED, this, 0).show();
            break;
    }
}

除了成功(SUCCESS)之外，都會跳出錯誤訊息，可以告知使用者該怎麼做。這裡是因為要直接測試是否正常，所以才需要自己寫，我實作的結果是，當無法使用 Google Play Services 時，內部已經做了這些判斷並會顯示相對應的訊息。(這只能用實機測，模擬器是沒有 Google Play 的)

步驟 2. 取得 API Key

要使用 Google Maps 的服務，必須在應用程式中使用 Maps API Key，Key 要在Google API Console (控制台)中申請，然後把 Key 加入 AndroidManifest.xml 檔中。

Google 服務是認 Key 不認人的，所以當你未發佈到 Google Play 之前，會用 debug 的金鑰去申請 Key，這個 Key 就只能在這個模擬器或自己的裝置中使用；也就是說，當你要發佈 App 到 Google Play 時，要使用 release 的金鑰，這時就要使用 release 金鑰再去申請一個 Key，給 release 版使用。

為應用程式取得 API Key 的步驟：

1. 取得應用程式的憑證資料。
2. 在 Google APIs Console 註冊一個專案，並且在專案中加入 Maps API 服務。
3. 當你的專案都設定好了，就可以申請一個或多個 Keys。
4. 最後把取得的 Key 加入應用程式中使用。

詳細說明如下：

1. 取得憑證資料

有2種

• Debug certificate：由 Android SDK 自動產生，給測試開發用。
• Release certificate：當發佈 release 版時產生，或使用 keytool 來自行產生。只有這個版本才能發佈到 Google Play。

※取得 Debug 憑證：

1. 找到 debug keystore 檔。在 Eclipse 中 Windows -> Preferences -> Android -> Build，會看到 Default debug keystore 欄位，即 keystore 儲存的位置，複製這個路徑。
2. 在命令列中輸入
   Windows 7:

   keytool -list -v -keystore "你複製的路徑" -alias androiddebugkey -storepass android -keypass android

   Mac:

   keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

3. 執行結果會顯示憑證的資料，你只要複製 SHA1 這個指紋。

※取得 Release 憑證：

1. 一樣要找到 keystore 的路徑，每個人存放的位置不同。
2. 在命令列(Win7)中，進入你存放 keystore 的目錄，輸入如下指令：
   

   keytool -list -keystore 你的keystore名稱

   這會顯示簡單的資訊，例如別名。
3. 輸入以下指令就可以取得指紋：

   keytool -list -v -keystore 你的keystore名稱 -alias 你的別名

   這裡千萬不要使用 -storepass 及 -keypass ，這兩個參數是在命令列中直接輸入密碼，較不安全。最好是讓 keytool 詢問你時再輸入，密碼不會顯示在螢幕上，比較安全。

2. 在 Google APIs Console 註冊一個專案

首先請到 Google APIs Console 建立專案，第一次進入會直接要求你建立專案，所以就點選 Create Project 建立吧~預設建立的名稱叫做「API Project」，在左上角的下拉選單上顯示，你可以對它更名或不理它用預設的。

點選左邊的功能選單 Service，就可以看到右邊主視窗中列出所有的服務。找到「Google Maps Android API v2」這一項，把開關打開，接受使用條款後就可以使用了。

3. 申請 API Key

步驟(2)完成後，左邊的選單會出現 API Access 選項，選擇它。接著在主視窗中點選「Create new Android key」，在跳出的視窗中輸入剛才步驟(1)取得的SHA1指紋碼，及你的 Android 專案的套件名稱，範例如下：

BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75;com.tonycube.googlemapdemo

SHA1指紋碼和套件名稱中間以分號( ; )區隔。

完成後就會在主視窗看到多了一筆資料「Key for Android apps (with certificates)」裡面會有一個 API key 項目，把 Key 的值複製起來，就可以在你的 Android 專案中使用囉~~~

4. 把鑰匙拿來開門囉~~~

接下來就是把 Key 放進你的應用程式中。打開 AndroidManifest.xml 檔， 選擇 Application 頁籤，Add -> Meta Data，在 Name 欄位填入 「com.google.android.maps.v2.API_KEY」，在 Value 欄位填入剛才複製的 API Key 。

選擇 Permissions 頁籤，Add -> Permission，在 Name 欄位填入「com.tonycube.googlemapdemo.permission.MAPS_RECEIVE」，粗體部份請換成你的套件名稱。Protection level 欄位請選擇「signature」。

再次 Add -> Uses Permission，在 Name 欄位填入「com.tonycube.googlemapdemo>.permission.MAPS_RECEIVE」，一樣粗體部份換成你的套件名稱。

存檔後 API Key 的部份就算完成了~~呼~~~

步驟 3. 設定 AndroidManifest.xml

使用 Google Maps Android API 需要指定以下權限：

• android.permission.INTERNET：使用網路下載地圖圖資。
• com.google.android.providers.gsf.permission.READ_GSERVICES：允許 API 存取以網頁為基礎的服務 (web-based services)。
• android.permission.WRITE_EXTERNAL_STORAGE：允許 API 在裝置的外部儲存區(sdcard)上儲存快取圖資。

以下權限為非必要，主要是用來定位：

• android.permission.ACCESS_COARSE_LOCATION：允許 API 使用 WiFi 網路或基地台做定位(定位較不精準)。
• android.permission.ACCESS_FINE_LOCATION：允許 API 使用 GPS 做精準定位。

所以就是以上 5 項權限：

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

Google Maps Android API v2 需要使用 OpenGL ES version 2，對於無法使用 OpenGL ES version 2 的裝置會無法使用第 2 版的 Android Google 地圖，因此必需限制有此項功能的裝置才能安裝。

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

當設定這個標籤後，會在 Google Play 直接排除無法使用的裝置，也就是使用者的裝置沒有 OpenGL ES v2 功能的就不能下載，避免使用者下載後無法使用而浪費時間產生不滿。

這個屬性要加在<user-permission>標籤之後，或是在 AndroidMenifest.xml 中選擇 manifest 頁籤，Add -> uses feature 也可以。

步驟 4. 在 Android 專案中加入地圖

終於可以開始使用地圖了。

建立一個 Android 專案，練習時建議用最新的 Android API 4.0 或之後的版本來測試(但必須至少在 2.2 版之後，因為之前的版本不支援 Google Play Services)。AndroidManifest.xml 照前面所說的做好設定，並記得加入 Library，接下來直接修改 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"
  class="com.google.android.gms.maps.MapFragment" />

然後就可以發佈測試了，但這邊要注意，只能在實機上測試，因為我們有用到 Google Play Service ，而 Google Play Service 必須和 Google Play Store 做溝通，在模擬器上是沒有 Google Play Store 的(網路上好像有教怎麼在模擬器上安裝，但何必麻煩)，所以直接拿實機測試吧~~

結果如下： 呼~~~打完收工。

參考資料：

• Google Maps Android API v2

本文網址：http://blog.tonycube.com/2012/12/androidmaps-and-positioning1.html
由 Tony Blog 撰寫，請勿全文複製，轉載時請註明出處及連結，謝謝 😀