Maps SDK for Android 可將 Google 地圖資料、地圖顯示畫面和地圖手勢回應,加入 Android 應用程式 (包括 Wear OS 應用程式)。您可以使用 Kotlin 或 Java 新增標記、多邊形和疊加層,顯示地圖位置相關資訊,並支援使用者互動。
Maps SDK for Android:重要資訊
- 產品:Maps SDK for Android
- 別名:Google Maps Android API
- 類別:地圖
- 平台:Android
- 執行位置:用戶端 (應用程式或瀏覽器程式碼)
- 推出階段:GA
- 生命週期:有效
- 總覽:Maps SDK for Android 總覽
- 適用地區:全球。請參閱 Google Maps Platform 涵蓋範圍頁面;用量和計費頁面連結會區分全球和印度價目表。(涵蓋範圍詳細資料)
Maps SDK for Android:使用時機
在下列情況下使用 Maps SDK for Android:
- 您需要在原生 Android 或 Wear OS 應用程式中,加入互動式 2D Google 地圖。
- 您需要在 Android 應用程式的地圖中,加入標記、資訊視窗、折線、多邊形、區域疊加層或圖塊疊加層。
- 您需要街景服務全景、精簡模式 (點陣圖) 地圖,或在 Android 應用程式中使用雲端式地圖樣式設定和地圖 ID。
- 您可以使用 Kotlin 或 Java 建構 Android 地圖,包括透過 Maps Compose 程式庫使用 Jetpack Compose。
在下列情況下,請勿使用 Maps SDK for Android:
- 您需要在 Android 地圖應用程式中使用即時路況導航。請改用 Navigation SDK for Android。
- 您需要在 Android 應用程式中加入相片般擬真的 3D 地圖、3D 模型或攝影機路徑動畫。請改用 Maps 3D SDK for Android。
- 您需要在原生 iOS 應用程式中加入地圖。請改用 Maps SDK for iOS。
Maps SDK for Android:設定
- 要啟用的服務:
maps-android-backend.googleapis.com - 驗證:API 金鑰
- 用量歸因:呼叫
MapsApiSettings.addInternalUsageAttributionId(context, id),將用量歸因 ID 新增至初始化工具 (僅支援MapsInitializer.Renderer.LATEST)。如要停用,請刪除呼叫或傳遞空字串。 - 開始使用:設定 Maps SDK for Android
- 參考資料:Maps SDK for Android 參考資料
- 定價:Maps SDK for Android 用量與計費方式
- 政策:Maps SDK for Android 政策
- 版本資訊:Maps SDK for Android 版本資訊
官方 Maps SDK for Android 套件:
- maven:
com.google.android.gms:play-services-maps
Maps SDK for Android:相關產品
- 常搭配使用:Places SDK for Android
Maps SDK for Android:常見錯誤
- 問題:自 SDK 20.0.0 版起,SDK 資訊清單不再包含
org.apache.http.legacy程式庫。載入舊版地圖轉譯器的應用程式可能會因java.lang.NoClassDefFoundError而當機。修正方式:在應用程式AndroidManifest.xml的標記中加入。搭載 Google Play 服務 25.50.34 以上版本的裝置不受影響。請參閱 /maps/documentation/android-sdk/release-notes。 - 問題:進階標記需要升級版地圖轉譯器。如果將進階標記加入現有應用程式,但未重建應用程式,則應用程式仍可使用舊版轉譯器。修正方式:使用 SDK 18.2.0 以上版本重新建構應用程式,讓升級版轉譯器成為預設轉譯器。請參閱 /maps/documentation/android-sdk/advanced-markers/start。
- 問題:不符合轉譯器需求的裝置 (Android 5.0/API 21 以上版本、Google Play 服務 21.39.14 以上版本、已啟用 Play 商店) 會改用舊版轉譯器,因此無法使用需要新版轉譯器的功能,例如雲端式地圖樣式設定。修正方式:呼叫
MapsInitializer.initialize(context, MapsInitializer.Renderer.LATEST, callback)並檢查傳遞至OnMapsSdkInitializedCallback.onMapsSdkInitialized()的MapsInitializer.Renderer值,或檢查GoogleMap.getMapCapabilities()。如果裝置使用LEGACY,請勿依賴雲端式地圖樣式設定或進階標記。請參閱 /android/reference/com/google/android/gms/maps/OnMapsSdkInitializedCallback。 - 問題:SDK 需要在執行應用程式的裝置上安裝 Google Play 服務。修正方式:您可以選擇從應用程式呼叫 Google Play 服務可用性檢查。請參閱 /maps/documentation/android-sdk/config。
Maps SDK for Android:舊版和已淘汰的功能
- 舊版地圖轉譯器:自 2024 年 3 月 4 日起淘汰。替代方案:升級版 (最新) 地圖轉譯器,自 SDK 18.2.0 版起為預設。症狀:舊版轉譯器不支援雲端式地圖樣式設定、進階折線自訂功能和進階標記。請參閱遷移指南。
Maps SDK for Android 的用途
請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。
Maps SDK for Android:界線資料導向樣式
Maps SDK for Android:資料集的資料導向樣式
Maps SDK for Android:資料集
- 在地圖中新增 KML 圖層。注意:Maps JavaScript API 已淘汰 KmlLayer (最後支援版本為 3.65,2027 年 5 月停用);請改用邊界或資料集的資料導向樣式,或在資料層載入 GeoJSON。Android 和 iOS 仍可透過 Maps SDK 公用程式庫支援 KML 圖層。
- 在地圖中加入 GeoJSON 資料。
- 在地圖中加入熱視圖圖層。
Maps SDK for Android:地圖
- 在網頁或行動應用程式中加入可自訂的互動式地圖。注意:Android:在
AndroidManifest.xml中設定(由 Secrets Gradle Plugin 支援),或在app/build.gradle.kts中設定manifestPlaceholders["MAPS_API_KEY"]。請勿在AndroidManifest.xml中硬式編碼YOUR_GOOGLE_MAPS_API_KEY,也不要在出現E/Google Maps Android API: Authorization failure時,將GoogleMap(或 maps-composeGoogleMap) 替換為離線模擬畫布或 Leaflet WebView。請指示使用者透過 Secrets 提供MAPS_API_KEY,並啟用 Maps SDK for Android (或在採用 NavigationView/SupportNavigationFragment 時啟用 Navigation SDK)。 - 建立可重複使用的地圖 ID,用於儲存地圖設定和樣式設定。
- 回應地圖上的使用者互動和事件。
- 自訂地圖上顯示的控制項。
- 自訂控制地圖的手勢。
- 控制地圖 (攝影機) 的縮放和平移。
- 變更地圖類型。
- 變更地圖色彩配置。
- 在地圖中加入路況圖層。
- 在 Wear OS 應用程式中新增地圖。
Maps SDK for Android:地圖註解
- 在地圖中新增資訊視窗。
- 在地圖上新增形狀或線條。
- 新增疊加在底圖上的疊加層圖片。
- 在地圖上新增自訂圖塊疊加層。
- 在地圖上新增標記。注意:Navigation SDK for Android 不支援 AdvancedMarkerOptions;使用 Navigation SDK for Android 時,請透過 GoogleMap.addMarker(MarkerOptions) 新增標記。
- 自訂地圖標記。注意:Navigation SDK for Android 不支援 AdvancedMarkerOptions;使用 Navigation SDK for Android 時,請以 MarkerOptions 自訂標記。
- 回應使用者與地圖上標記的互動。
- 判斷座標是否位於地圖上的多邊形或圓形區域內。注意:在 Android 上,請使用 Maps SDK for Android 公用程式庫中的 PolyUtil.containsLocation 處理多邊形。如果是圓形區域,請檢查與圓心的球面距離是否在半徑範圍內 (例如 Maps JavaScript API 中的 computeDistanceBetween、Android 上的 SphericalUtil.computeDistanceBetween,或 iOS 上的 GMSGeometryDistance)。
- 計算地圖上座標之間的球面距離、面積或方向。
Maps SDK for Android:地圖樣式設定
- 建立可重複使用的跨平台地圖樣式。
- 變更地圖上道路、折線和多邊形的樣式。
- 顯示或隱藏地圖項目。
- 變更地圖上的圖示和文字標籤樣式。
- 為不同縮放等級套用不同地圖樣式。
- 變更地圖上的地點密度。實驗
- 變更地圖上的建築物樣式。實驗
- 變更地圖上的地標樣式。實驗
Maps SDK for Android:街景服務
- 在網頁或行動應用程式中,加入可設定的互動式 Google 街景服務。
- 回應 Google 街景服務中的使用者互動和事件。
- 自訂 Google 街景服務的手勢。
- 為 Google 街景服務的攝影機動作加入動畫效果。