Google Maps là thứ dễ demo nhất và cũng dễ hỏng nhất trong app Android. Trên máy bạn, bản đồ hiện đẹp; trên máy QA, nó thành lưới ô xám; trên máy người dùng thật, nó làm pin tụt nhanh hơn mọi tính năng khác. Nguyên nhân hiếm khi nằm ở Compose, mà ở API key, quyền vị trí và cách bạn đăng ký nhận vị trí qua Google Play Services.
Code dưới đây chạy trên targetSdk 36: key bị lộ, quyền nền bị Play từ chối và location request không được remove là ba lỗi phải chặn từ đầu.
Mục lục
Cập nhật 2026
- Target API 36 là bắt buộc. Từ 31/08/2026, app mới và bản cập nhật phải target API 36, gia hạn tối đa tới 01/11/2026.
LocationRequest.create()và các hằngPRIORITY_*đã deprecated. DùngLocationRequest.Buildervới các hằng trongPriority.- Maps Compose đổi API clustering. Overload một dòng
Clustering(items, ...)đã bị ẩn; bản hiện tại cầnrememberClusterManager. - Không pin version Play Services.
play-services-mapsvàplay-services-locationphát hành theo lịch Play Services, không theo lịch app.
Play Services không phải thư viện bạn bundle
Dependency bạn thêm chỉ là client stub mỏng; phần render bản đồ, lấy vị trí và xử lý tile chạy trong tiến trình của app hệ thống Play Services, được cập nhật qua Play Store độc lập với bản Android. Vì vậy máy không có GMS sẽ không có bản đồ — kiểm tra bằng GoogleApiAvailability và có fallback.
API key: ba thứ quyết định bản đồ có hiện hay không
Key chỉ hoạt động khi Maps SDK for Android được enable trong Cloud project, key bị giới hạn đúng package và SHA-1 của chứng chỉ đang dùng, và manifest khai báo đúng meta-data. Thiếu một trong ba, bạn nhận cùng một triệu chứng: nền xám có lưới, không tile, không lỗi rõ trong logcat.
| Build | Chứng chỉ ký | Lấy SHA-1 ở đâu |
|---|---|---|
| debug | debug keystore, mỗi máy một khác | ./gradlew signingReport |
| release nội bộ | upload key | signingReport với keystore release |
| release trên Play | Play App Signing key | Play Console → App integrity |
Chỉ whitelist SHA-1 của upload key là lỗi kinh điển: bản test chạy tốt, bản production trắng bản đồ. Thêm cả hai SHA-1 vào một key, hoặc tách key theo build type.
Đừng coi key trong APK là bí mật: nó trích xuất được, và tài liệu Google nói thẳng rằng vượt restriction là chuyện đơn giản. Hãy giới hạn API — key chỉ gọi được Maps SDK for Android — bật cảnh báo quota và rotate nếu bị lạm dụng. Các call Geocoding, Routes, Places phải đi qua backend.
// File: app/build.gradle.kts
import java.util.Properties
val secrets = Properties().apply {
val file = rootProject.file("secrets.properties") // không commit
if (file.exists()) file.inputStream().use { load(it) }
}
android {
compileSdk = 36
defaultConfig {
minSdk = 24
targetSdk = 36
manifestPlaceholders["MAPS_API_KEY"] = secrets.getProperty("MAPS_API_KEY") ?: ""
}
buildFeatures { compose = true }
}
dependencies {
// Version trong libs.versions.toml, lấy bản mới nhất từ tài liệu Google.
implementation(libs.play.services.maps)
implementation(libs.play.services.location)
implementation(libs.maps.compose)
implementation(libs.kotlinx.coroutines.play.services) // Task.await()
}
<!-- File: app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Chỉ bỏ comment khi thật sự cần vị trí lúc app ở nền:
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" /> -->
<application ...>
<meta-data
android:name="com.google.android.geo.API_KEY"
android:value="${MAPS_API_KEY}" />
</application>
</manifest>
Quyền vị trí: coarse, fine và all-the-time
Xin cả coarse và fine trong một lần gọi. Từ Android 12, hộp thoại có lựa chọn “Approximate”; app phải chạy được với sai số cỡ vài km. Chỉ tính năng cần độ chính xác mét — ghim điểm, chỉ đường, xác nhận đang trong cửa hàng — mới nên giải thích để người dùng bật precise.
Từ Android 10, ACCESS_BACKGROUND_LOCATION là quyền riêng; từ Android 11 không còn hộp thoại, người dùng phải vào Settings chọn “Allow all the time” — hãy xin foreground trước và giải thích lợi ích cụ thể. Play review thủ công quyền này. Chỉ cần vị trí khi mở app thì đừng khai báo quyền nền; cần theo dõi khi màn hình tắt thì phải có foreground service type location kèm FOREGROUND_SERVICE_LOCATION (từ API 34). Toạ độ là dữ liệu cá nhân theo Nghị định 13/2023/NĐ-CP: cần mục đích rõ ràng và thời hạn lưu.
Một màn hình Google Maps chạy được trong Compose
Màn hình đầy đủ: bản đồ, một marker, luồng xin quyền fine/coarse và đúng một lần lấy vị trí bằng getCurrentLocation.
// File: ui/map/MapScreen.kt
private val HANOI = LatLng(21.0285, 105.8542)
private fun Context.hasAnyLocation() =
ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) ==
PackageManager.PERMISSION_GRANTED ||
ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION) ==
PackageManager.PERMISSION_GRANTED
@Composable
fun MapScreen(modifier: Modifier = Modifier) {
val context = LocalContext.current
val scope = rememberCoroutineScope()
val fused = remember { LocationServices.getFusedLocationProviderClient(context) }
var hasLocation by remember { mutableStateOf(context.hasAnyLocation()) }
val camera = rememberCameraPositionState {
position = CameraPosition.fromLatLngZoom(HANOI, 13f)
}
fun requestOnce() {
scope.launch {
val cts = CancellationTokenSource()
try {
val fix = fused
.getCurrentLocation(Priority.PRIORITY_HIGH_ACCURACY, cts.token)
.await() ?: return@launch // không có fix, không phải lỗi
camera.position = CameraPosition.fromLatLngZoom(
LatLng(fix.latitude, fix.longitude), 16f
)
} catch (e: SecurityException) {
hasLocation = false // quyền bị thu hồi giữa chừng
} finally {
cts.cancel()
}
}
}
val permissionLauncher = rememberLauncherForActivityResult(
ActivityResultContracts.RequestMultiplePermissions()
) { result ->
hasLocation = result[Manifest.permission.ACCESS_FINE_LOCATION] == true ||
result[Manifest.permission.ACCESS_COARSE_LOCATION] == true
if (hasLocation) requestOnce()
}
// Người dùng có thể đổi quyền trong Settings khi app đang chạy.
LifecycleEventEffect(Lifecycle.Event.ON_RESUME) {
hasLocation = context.hasAnyLocation()
}
Column(modifier = modifier.fillMaxSize()) {
GoogleMap(
modifier = Modifier.weight(1f),
cameraPositionState = camera,
properties = MapProperties(isMyLocationEnabled = hasLocation),
uiSettings = MapUiSettings(
zoomControlsEnabled = false,
myLocationButtonEnabled = hasLocation
)
) {
Marker(
state = rememberMarkerState(position = HANOI),
title = "Hồ Hoàn Kiếm"
)
}
Button(
modifier = Modifier.fillMaxWidth().padding(16.dp),
onClick = {
if (hasLocation) requestOnce()
else permissionLauncher.launch(
arrayOf(
Manifest.permission.ACCESS_FINE_LOCATION,
Manifest.permission.ACCESS_COARSE_LOCATION
)
)
}
) {
Text(if (hasLocation) "Lấy vị trí hiện tại" else "Cấp quyền vị trí")
}
}
}
rememberCameraPositionState lưu camera qua xoay màn hình và process death. MapProperties(isMyLocationEnabled = ...) ném SecurityException nếu bật khi chưa có quyền, nên phải gate bằng checkSelfPermission. getCurrentLocation trả về fix mới chứ không phải vị trí cache, nên luôn có nhánh xử lý null.
Marker, camera và UI settings
Marker là state hoisted: MarkerState giữ vị trí, còn tiêu đề, icon, alpha hay draggable truyền qua tham số. Khi marker kéo được, đọc state.position thay vì giữ một LatLng song song — hai nguồn sự thật sẽ lệch sau recomposition.
Camera có ba kiểu: gán position để nhảy tức thì, animate(...) để chạy mượt, và CameraPosition.fromLatLngZoom để dựng lại trạng thái đã lưu. Tắt zoomControlsEnabled vì gesture đã đủ; dùng contentPadding bằng chiều cao bottom bar để logo Google không nằm dưới thanh điều hướng.
Khi buộc phải dùng AndroidView và MapView
GoogleMap composable tự quản lý vòng đời MapView bên trong. Chỉ khi nhúng bản đồ vào màn hình View cũ, hoặc cần GoogleMapOptions ở mức thấp, bạn mới dùng AndroidView — và lúc đó vòng đời là việc của bạn.
// File: ui/map/LegacyMapView.kt
@Composable
fun LegacyMapView(modifier: Modifier = Modifier, onMapReady: (GoogleMap) -> Unit) {
val context = LocalContext.current
val lifecycleOwner = LocalLifecycleOwner.current
val onReady by rememberUpdatedState(onMapReady)
val mapView = remember { MapView(context) }
DisposableEffect(lifecycleOwner, mapView) {
mapView.onCreate(null) // đúng một lần
mapView.getMapAsync { onReady(it) }
val observer = LifecycleEventObserver { _, event ->
when (event) {
Lifecycle.Event.ON_START -> mapView.onStart()
Lifecycle.Event.ON_RESUME -> mapView.onResume()
Lifecycle.Event.ON_PAUSE -> mapView.onPause()
Lifecycle.Event.ON_STOP -> mapView.onStop()
Lifecycle.Event.ON_DESTROY -> mapView.onDestroy()
else -> Unit
}
}
lifecycleOwner.lifecycle.addObserver(observer)
// Composable có thể xuất hiện khi Activity đã RESUMED.
if (lifecycleOwner.lifecycle.currentState.isAtLeast(Lifecycle.State.RESUMED)) {
mapView.onStart()
mapView.onResume()
}
onDispose {
lifecycleOwner.lifecycle.removeObserver(observer)
mapView.onDestroy()
}
}
AndroidView(factory = { mapView }, modifier = modifier)
}
Hai lỗi thường gặp: quên onDestroy làm rò native surface và giữ Activity; đặt MapView trong LazyColumn mà không detach khi item bị recycle.
Clustering: đừng vẽ 2.000 marker cùng lúc
Ở zoom 11, vài trăm điểm bán hàng tạo màn hình dày marker, mỗi marker là một đối tượng native do SDK vẽ. Clustering gộp các điểm gần nhau thành marker số, giảm số đối tượng phải vẽ và làm tap target có nghĩa.
maps-compose-utils cung cấp Clustering; ClusterItem bây giờ là interface Kotlin với position, title, snippet, zIndex, nên implement bằng override val. API hiện tại yêu cầu tạo ClusterManager bằng rememberClusterManager rồi truyền vào Clustering, cả hai trong MapsComposeExperimentalApi. Danh sách item phải ổn định — dùng remember(stores) và data class có equals theo id.
Offline maps: không có API tải vùng
Maps SDK for Android không cung cấp API tải trước một vùng như app Google Maps. Cache tile trên thiết bị là best-effort: hết hạn, bị dọn khi thiếu bộ nhớ, không đảm bảo còn khi vào hầm.
Nếu offline là yêu cầu thật, đừng vá Maps SDK. Hai hướng trung thực: tự cung cấp tile qua TileOverlay với TileProvider/UrlTileProvider trỏ vào file nội bộ, hoặc bundle ảnh tĩnh/POI cho khu vực nhỏ. Với tile tự quản lý, tải trước khi có Wi-Fi và lưu trong cacheDir — xem bài hệ thống file trong Android. Đừng tải hàng loạt tile của Google: điều khoản không cho phép.
Vị trí liên tục: priority, interval và pin
LocationRequest.Builder có bốn tham số ảnh hưởng pin: priority, interval, min update interval và min update distance. Chọn sai priority là nguyên nhân số một của pin tụt.
| Priority | Nguồn và sai số | Dùng cho |
|---|---|---|
HIGH_ACCURACY |
GNSS + Wi-Fi + cảm biến, vài mét tới ~50 m | Chỉ đường, xác nhận đúng địa điểm |
BALANCED_POWER_ACCURACY |
Wi-Fi + cell, sai số cỡ trăm mét | Hiển thị vị trí, tìm cửa hàng gần nhất |
LOW_POWER |
Chủ yếu cell, sai số có thể tới vài km | Cập nhật thưa, thời tiết, log |
PASSIVE |
Chỉ nhận fix khi app khác yêu cầu | Tín hiệu phụ, không chủ động |
setMinUpdateDistanceMeters rẻ hơn nhiều so với giảm interval: đứng yên trong quán, không có lý do nhận 60 fix mỗi phút. setWaitForAccurateLocation(false) cho fix đầu nhanh hơn nhưng kém chính xác.
// File: location/LocationTracker.kt
val request = LocationRequest.Builder(Priority.PRIORITY_BALANCED_POWER_ACCURACY, 30_000L)
.setMinUpdateIntervalMillis(10_000L)
.setMinUpdateDistanceMeters(50f)
.setWaitForAccurateLocation(false)
.build()
val callback = object : LocationCallback() {
override fun onLocationResult(result: LocationResult) {
val fix = result.lastLocation ?: return
camera.position = CameraPosition.fromLatLngZoom(
LatLng(fix.latitude, fix.longitude), camera.position.zoom
)
}
}
fused.requestLocationUpdates(request, callback, Looper.getMainLooper())
// Bắt buộc: remove khi màn hình dừng, nếu không callback giữ Activity.
fused.removeLocationUpdates(callback)
Mỗi requestLocationUpdates phải có removeLocationUpdates đối xứng trong onStop hoặc onDispose. Chỉ cần một fix thì dùng getCurrentLocation.
Geofencing: mạnh nhưng đắt pin
Geofencing hợp cho “nhắc tôi khi tới cửa hàng”, không hợp cho theo dõi liên tục. Giới hạn 100 geofence mỗi app trên mỗi người dùng thiết bị; bán kính nên từ 100 đến 150 m; dùng DWELL thay vì chỉ ENTER để tránh spam thông báo khi xe chạy ngang. PendingIntent cần FLAG_UPDATE_CURRENT và thêm FLAG_MUTABLE từ Android 12. Geofence không sống qua reboot hay clear data — cần BOOT_COMPLETED để đăng ký lại.
Places SDK: cẩn thận hoá đơn
Places SDK (bản mới) tính tiền theo request và theo SKU dữ liệu, nên một vòng autocomplete ngây thơ có thể tạo hoá đơn lớn hơn doanh thu app. Ba biện pháp: dùng session token để gộp các lần gõ phím và lần lấy chi tiết vào một phiên; chỉ xin đúng field cần (id, tên, toạ độ); debounce 300–500 ms và không gọi khi ô tìm kiếm rỗng.
Ngoài chi phí còn ràng buộc dữ liệu: placeId được lưu lâu dài, nhưng phần lớn nội dung khác không được cache vô hạn. Cần “địa điểm yêu thích” thì lưu placeId và gọi lại khi cần.
Những lỗi lặp lại và cách sửa
| Triệu chứng | Nguyên nhân | Cách sửa |
|---|---|---|
| Bản đồ là lưới xám | Chưa enable Maps SDK, sai package/SHA-1, thiếu INTERNET | Đối chiếu restriction với cert của build đang chạy |
| Bản Play trắng bản đồ | Chỉ whitelist SHA-1 debug/upload | Thêm SHA-1 của Play App Signing key |
| Play từ chối cập nhật | Khai báo background location không đúng core feature | Bỏ quyền nền nếu chỉ cần foreground |
| Pin tụt, review 1 sao | High accuracy + interval ngắn, không remove khi onStop | Balanced + min distance; remove đối xứng |
| Activity leak khi xoay màn hình | MapView thiếu onDestroy |
Forward đủ lifecycle; remove trong onDispose |
| Có quyền nhưng không có vị trí | Chỉ coarse, location service tắt, hoặc fix null | Xử lý null và coarse; kiểm tra location enabled |
| Crash khi bật my-location | Bật khi chưa có quyền | Gate bằng checkSelfPermission mọi lúc |
Một lỗi nữa: dùng LocationManager trần cho code mới. Nó không bị xoá nhưng không fuse nguồn và không tối ưu pin như Play Services. Chỉ dùng khi cần GNSS thô hoặc trạng thái provider mà fused API không cung cấp.
Checklist trước khi phát hành
- Key giới hạn đúng package + SHA-1 của debug, CI và Play App Signing, chỉ cho Maps SDK for Android.
- Không khai báo
ACCESS_BACKGROUND_LOCATIONnếu không có tính năng nền thật. - Mọi
requestLocationUpdatescóremoveLocationUpdates; mọigetCurrentLocationcó nhánh null. - UI chạy được khi chỉ có quyền coarse và khi location service bị tắt.
Nhìn tới 2027
Android 17 (API 37) mới ở beta, nhưng hướng đã rõ: quyền vị trí theo phiên. Play đã nêu trong chính sách: app target API 37 trở lên mà chỉ dùng vị trí theo phiên phải dùng location button. Về build, app có native lib riêng phải hỗ trợ trang 16 KB; Play chặn bản cập nhật không đạt từ 01/02/2027.
Bài trước đi qua Firebase Authentication, Firestore và Crashlytics — ghép với bản đồ, bạn có app có tài khoản và vị trí. Bài tiếp theo là AdMob, nơi hoá đơn quảng cáo cũng cần đọc kỹ như hoá đơn Maps. Nếu bạn mới vào series, bắt đầu từ lộ trình Android.



