Ch22 Google Map

要在應用程式中使用Google Map，必須透過「Google Maps Android API」將Google Maps資料轉成地圖後，以應用程式顯示出來，這需要用到此API的Key值。 從2013年3月1日起，Google全面改用「Google Maps Android API v2」版。

一、Google Map使用前準備 要開發與Google Map相關應用程式，首先必須安裝「Google Play services SDK」，及申請「Google Maps Android API Key」，請依以下步驟安裝「Google Play services SDK」： 從Eclipse啟動「Android SDK Manager」。 在Android SDK Manager對話框顯示的套件清單中，往下找到「Extra」分類中的「Google Play services」套件，至少要安裝此套件，此處筆者為方便其他開發需求，安裝了「Extra」分類中所有套件。

安裝後，在Android SDK的安裝資料夾中會出現「extra/google/google_play_service」資料夾。 匯入「<Android SDK安裝資料夾>/extra/google/google_play_service/libproject/google_player_services_lib」函式庫專案 從Eclipse執行「File>Import>」 從開啟的「Import」對話框選「Android」分類中的「Existing Android Code Into Worksapce」，敲「Next」鈕 再利用「Root Directory」的「Browse」鈕找到「google_player_services_lib」函式庫專案資料夾，記得勾選「Copy projects into workspace」 然後敲「Finish」鈕匯入此函式庫專案。

匯入後從Eclipse的Package Explorer中可以看到此函式庫專案。

建立專案 從Package Explorer右敲專案名稱，執行「Properties」 由開啟的對話框左側選「Android」 從右側Library區敲「Add」鈕 再從新開啟的「Project Selection」對話框選google_player_services_lib函式庫專案，以在專案中設定對google_player_services_lib函式庫參考。 點選[Apply]/[Ok] 完成設定

申請API Key 必須使用開發者數位認證憑證「SHA1」(稱為「認證指紋」，注意不是以往的「MD5」認證憑證有2種：Debug 與Release憑證。 Debug憑證專門提供開發者測試用，不能用於正式釋出的版本，而且由Android SDK自動產生；Release憑證必須由開發者手動以Java的keytool工具建立。 取得SHA1認證指紋方式如下： 認證指紋應該存於 「C:\User\<user name>\.android\debug.keystore」中 此檔案的內容必需用Java的「keytool」工具才能顯示。

如果不確定你的debug.keystore所在位置，可以利用Eclipse的「Windows>Preferences」命令，從開啟的偏好對話框左邊 選「Android>Build」，右邊的「Default debug keystore」欄顯示的就是它存放位置。 可直接取用此 SHA1 值

新版Eclipse已不須此步驟 開啟命令提示字元視窗，移到Java安裝資料夾，執行以下keytool命令： Keytool –list –v –keystore “<你debug.keystore檔完整路徑>” -alias androiddebugkey –storepass android –keypass android 執行後顯示認證指紋，記錄你的SHA1認證指紋。

申請Google Maps Android API v2的API Key： 連至Google Console網站，網址為： https://code.google.com/apis/console 如果是第一次登入，會要求建立專案，專案名稱不一定要與開發的專案相同，敲下「Create project」鈕後會要求同意Google的條款才能繼續。 點選右下方之[回傳統畫面] 從畫面左側選「Services」，再從右側顯示的服務清單找到「Google Maps Android API v2」，敲此項右邊的開關圖示(圖示會從OFF變成ON)，表示要申請此項的API Key。

再從畫面左側選「API Access」，然後敲右側的「Create new Android key」鈕，要求產生新的API Key。

從開啟的「Configure Android Key for API Project」對話框，輸入你的SHA1認證指紋，後面接分號「;」再加上開發專案套件名稱。 EX: ;com.example.googlemaptest

如果沒有錯誤，會回到「API Access」畫面並顯示產生的API Key，記錄此API Key，這API Key需提供給應用程式組態檔。

開發GoogleMap應用程式，除了參考到之前匯入的「google_player_services_lib」函式庫專案、要在組態檔提供API Key以外，還必須在組態檔中設定一些如網路、外部記憶體寫入等許可申請。 設定GoogleMap Test專案 設定對google_player_services_lib函式庫參考。 如 Page 7

從Eclipse開啟組態檔AndroidManifest.xml，完成以下設定： 加入下列服務的引用 <meta-data android:name="com.google.android.gms.version“ android:value="@integer/google_play_services_version" /> 加入API Key的引用 <meta-data android:name= “com.google.android.maps.v2.API_KEY” android:value="<你的API Key>"/> 書上遺漏此指令

增加應用程式可以接受Google Map資訊的許可，這是透過增加<permission>與<uses-permission>元素完成，加入位置為<application>標記之前，加入的內容如下： <permission android:name= "com.example.googlemaptest. permission.MAPS_RECEIVE" android:protectionLevel="signature"/> <uses-permission android:name= permission.MAPS_RECEIVE"/>

申請必要的使用許可如下： 透過網路下載地圖圖資 <uses-permission android:name= "android.permission.INTERNET"/> 允許讀取以網頁為基礎的服務 "com.google.android.providers.gsf. permission.READ_GSERVICES"/> 允許將圖資暫存在外部記憶體(SD卡) "android.permission. WRITE_EXTERNAL_STORAGE"/>

以下的使用許可是為了方便而申請，對目前專案並無直接關係： 允許以Wi-Fi 網路或基地台定位 <uses-permission android:name= "android.permission. ACCESS_COARSE_LOCATION"/> 允許以GPS定位 ACCESS_FINE_LOCATION"/> 允許存取網路狀態 ACCESS_NETWORK_STATE"/>

Google Maps Android API v2 需要使用 OpenGL ES第2版的功能，因此必需限制具有此功能的裝置才能安裝： <uses-feature android:glEsVersion="0x00020000" android:required="true"/>

Google Maps Android API v2不再以「MapView」類別顯示Google地圖，而改以Fragment顯示地圖。如果使用Android SDK4.0以上版本，可以使用「MapFragment」類別，否則應使用「SupportMapFragment」類別；此範例我們先使用「MapFragment」類別。 範例詳細內容請參考原書 code 22-3。 因為Google Maps Android API v2會用到 Google Play Service，而且Google Play Service必須與 Google Play Store互動，而模擬器內並沒有Google Play Store，因此Google Map的應用只能在實際裝置上進行測試。

目前網路上提出許多可以用模擬器測試Google Map的方法，這些方法主要是在模擬器上安裝一些套件以便使模擬器能與Google Play Store互通，不過這些方法一般都只針對特定SDK版本的模擬器，有興趣的讀者可以上網參考(例如發佈於以下網址的文章：http://hscc.cs.nctu.edu.tw/~lincyu/Android/GoogleMapV2_Emulator.pdf)

二、Google Map應用中的重要類別 Google Map應用中可以使用的類別相當多，簡略的介紹如下： Fragment 是顯示地圖的類別，主要提供2個子類別用以顯示地圖：「MapFragment」與「SupportMapFragment」。 這2種類別最重要的方法是「getMap()」方法，此方法回傳它所包含的地圖類別「GoogleMap」。 Google地圖也是一種服務，因此必須以系統的「getFragmentManager()」或「getSupportFragmentManager()」方法取得對佈局中此類別實體物件的參考。

GoogleMap 所有對Google地圖的操作都要從此類別開始，此類別實體是透過FragmentManager或SupportFragmentManager物件的getMap()方法取得。 GoogleMap常用方法如下： addMarker (MarkerOptions options)：在地圖上增加一個標記。 animateCamera (CameraUpdate update)：以動畫方式將Camera從目前位置移到CameraUpdate指定的位置；Camera位置就是顯示的地圖位置。

clear()：清除地圖上所有增加的標記以及其他圖形等。 getCameraPosition()：取得Camera目前位置的快照，此快照在Camera移動時不會自動更新。 getMapType()：取得目前顯示的地圖型式，地圖型式22-4節再說明。 setMapType(int type)：設定要顯示的地圖型式。 getMaxZoomLevel()：回傳目前Camera位置最高縮放等級。 getMinZoomLevel()：回傳目前Camera位置最低縮放等級。 getMyLocation()：回傳目前顯示的使用者位置。

getUiSettings()：取得此地圖的使用者介面設定。 moveCamera(CameraUpdate update)：依CameraUpdate重新定位Camera。 setInfoWindowAdapter(GoogleMap.InfoWindowAdapter adapter)：設定自定的訊息窗描繪器。 setMyLocationEnabled(boolean enabled)：啟用或停用我的位置圖層，啟用此功能會持續繪出使用者目前位置與方位指示器，並顯示可以和目前位置互動的使用者介面控制。 setOnInfoWindowClickListener(GoogleMap.OnInfoWindowClickListener listener)：設定當敲標記訊息窗時系統回呼的方法。

setOnMapClickListener(GoogleMap setOnMapClickListener(GoogleMap.OnMapClickListener listener)：設定當敲地圖時系統回呼的方法。 setOnMapLongClickListener(GoogleMap.OnMapLongClickListener listener)：設定當長壓地圖時系統回呼的方法。 setOnMarkerClickListener(GoogleMap.OnMarkerClickListener listener)：設定當敲標記時系統回呼的方法。 setOnMarkerDragListener(GoogleMap.OnMarkerDragListener listener)：設定當拖曳標記時系統回呼的方法。

camera(CameraPosition camera)：設定Camera初始位置。 GoogleMapOptions 此類別為以程式增加Google地圖時，設定一些建置地圖的屬性(不透過xml佈局檔)，常用的方法如下： camera(CameraPosition camera)：設定Camera初始位置。 compassEnabled(boolean enabled)：設定是否啟動指南針。

CameraPosition 地圖的Camera是透過CameraPosition類別設定它位置的相關資料。 類別常用方法如下： CameraPosition(LatLng target, float zoom, float tilt, float bearing)：以指定的經緯度座標(位置)、縮放等級(鏡頭遠近，可以設定的範圍依位置、地圖型式與螢幕尺寸而變)、Camera傾斜角及方位角等資料，建置CameraPosition物件。 CameraPosition.Builder builder(CameraPosition camera)：用指定的CameraPosition物件產生一個Camera位置建立者。

此CameraUpdate 此類別實際控制Camera的動作，此類別的實體物件由CameraUpdateFactory建立，GoogleMap透過animateCamera(CameraUpdate)或moveCamera(CameraUpdate)修訂Camera位置參數(因此Camera會改變位置)。

CameraUpdateFactory 此類別主要用以建立CameraUpdate物件。一般是用「newCameraPosition (CameraPosition cameraPosition)」方法，以傳入的CameraPosition物件建立CameraUpdate，傳入的CameraPosition物件可用以設定Camera的位置座標、方位角、傾斜角或縮放等級等資料。

是放在地圖表面指定位置的圖示，但它是劃在螢幕上而非地圖上，因此不會隨著地圖旋轉或縮放而改變，常用的方法如下： Marker 是放在地圖表面指定位置的圖示，但它是劃在螢幕上而非地圖上，因此不會隨著地圖旋轉或縮放而改變，常用的方法如下： getPosition()：回傳此Marker所在位置。 setPosition(LatLng latlng) ：設定此Marker顯示的位置。 getSnippet()：回傳此Marker訊息窗的說明文字。

setSnippet(String snippet)：設定此Marker訊息窗的說明文字。 getTitle()：回傳此Marker在訊息窗顯示的標題。 setTitle(String title)：設定此Marker在訊息窗顯示的標題。 isDraggable()：回傳此Marker是否可被使用者拖曳而改變位置。 setDraggable(boolean draggable)：設定此Marker是否可以被使用者拖曳而改變位置。 setVisible(boolean visible)：設定此Marker是否可見。

MarkerOption 定義一個標記的各項屬性，常用方法如下： draggable(boolean draggable)：設定Marker的拖曳屬性。 icon(BitmapDescriptor icon)：設定Marker顯示的圖示。 position(LatLng position)：設定Marker顯示的位置。 snippet(String snippet)：設定Marker顯示的說明文字。 title(String title)：設定Marker顯示的標題。 visible(boolean visible)：設定Marker是否可見。

LatLng 以度表示經緯度座標值的類別，它主要提供2個欄位，「latitude」存放此物件的緯度，「longitude」存放此物件的經度；建構函式「LatLng (double latitude, double longitude)」以指定的經緯度建立此物件。 UiSettings 作用是設定GoogleMap的使用者介面，此勿件透過GoogleMap的getUiSettings()方法取得。

三、顯示指定位置的地圖 CameraPosition中的target是地圖在螢幕中間的位置(經緯度) 。 zoom決定了地圖顯示範圍大小，每增加一個等級地圖會放大一倍，因此對整個螢幕顯示的範圍會更小，但能顯示更多細節。 bearing是顯示垂直方向與北方的夾角(以順時鐘方向為正)，如果設為90表示地圖正上方為東方。 tilt為Camera從空中往下看地表的傾斜角度，預設為垂直向下。

MapLocationSet Test範例 設定地圖顯示位置是透過CameraUpdate物件，而GoogleMap移動Camera有2種方式，一是以GoogleMap.moveCamera(CameraUpdate)採取立即的移動，或是以GoogleMap.animateCamera(CameraUpdate)用動態方式移動。 MapLocationSet Test範例 也改用「SupportMapFragment」顯示地圖，因此將活動改為延伸自「FragmentActivity」類別。 範例詳細內容請參考原書。

四、顯示不同型態的地圖 Google Maps Android API提供有5種不同型式的地圖，透過GoogleMap類別的「setMapType()」方法就能指定所要顯示的地圖型式。可以使用的地圖型式常數定義如下： public static final int MAP_TYPE_NORMAL：顯示基本型式地圖，有主要地點的標示。 public static final int MAP_TYPE_NONE：不顯示地圖內容。 public static final int MAP_TYPE_SATELLITE：顯示衛星空照圖，無主要地點標示。

public static final int MAP_TYPE_HYBRID：顯示衛星空照圖，但有主要地點標示。 public static final int MAP_TYPE_TERRAIN：顯示地形圖。 MapsType Test範例 以按鈕控制要顯示的地圖型式。 範例詳細內容請參考原書。

五、為地圖加上標記 透過MarKer物件可以在特定地點以指定的圖示設定標記，並可以設定當使用者敲此標記時以標記訊息窗顯示的內容。 MapMarker Test範例 指定的位置加上標記，而且當使用者敲此標記時，會在標記訊息窗中顯示「I am here」內容。 範例詳細內容請參考原書。

六、地圖與定位 導航就是定位與地圖結合使用的範例之一。 MapANdLocation Test範例 利用GPS定位功能找出行動裝置目前所在的位置，並以此為基準顯示地圖並加上標記，且地圖與標記會隨使用者移動(其實是行動裝置移動)更新位置。 當使用者敲標記的時候，標記訊息窗會顯示使用者目前位置的經緯度，這是GoogleMap本身已經設定好的互動。

事件是使用者與地圖互動的主要媒介，除了OnMapClickListener事件偵聽以外，GoogleMap還提供有以下偵聽介面： 在程式中我們另外自建當使用者敲地圖(不是標記)的時候，會將地圖顯示的中心點從使用者位置移到所敲的位置的互動方式。 範例詳細內容請參考原書。 事件是使用者與地圖互動的主要媒介，除了OnMapClickListener事件偵聽以外，GoogleMap還提供有以下偵聽介面： OnMapLongClickListener：偵聽地圖被長時間按下時觸發的事件。 OnCameraChangeListener：偵聽地圖Camera位置改變時觸發的事件。

OnMyLocationChangeListener：偵聽我的位置點改變位置時觸發的事件。 OnMarkerClickListener：偵聽標記被敲下時觸發的事件。 OnMarkerDragListener：偵聽標記被拖曳時觸發的事件。 OnInfoWindowClickListener：偵聽標記訊息窗被敲下時觸發的事件。