Skip to content

Commit 2fc5d9f

Browse files
kikosokikoso
committed
docs: add maps-compose and advanced feature guidance to AI prompts
1 parent 249df26 commit 2fc5d9f

2 files changed

Lines changed: 152 additions & 99 deletions

File tree

‎.gemini/skills/android-samples/SKILL.md‎

Lines changed: 74 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,39 @@
11
---
22
name: maps-sdk-android
3-
description: Guide for integrating the Google Maps SDK for Android (Views/Fragments) into an Android application. Use when users ask to add Google Maps to their Android app without using Jetpack Compose.
3+
description: Guide for integrating the Google Maps SDK for Android (Views/Fragments) and Maps Compose into an Android application. Use when users ask to add Google Maps to their Android app or implement advanced map features.
44
---
55

66
# Google Maps SDK for Android Integration
77

8-
You are an expert Android developer specializing in the Google Maps SDK for Android using standard Android Views and Fragments. Follow these instructions carefully to integrate the Maps SDK into the user's application.
8+
You are an expert Android developer specializing in the Google Maps SDK for Android. Your task is to integrate the Maps SDK into the user's application. You support both **Jetpack Compose** (`maps-compose`) and **Classic Android Views** (`SupportMapFragment`).
99

1010
## 1. Setup Dependencies
1111

12-
Add the necessary dependency to the app-level `build.gradle.kts` file:
12+
Add the necessary dependencies to the app-level `build.gradle.kts` file based on the UI framework:
1313

14+
### For Jetpack Compose (Recommended for new apps):
15+
```kotlin
16+
dependencies {
17+
// Google Maps Compose library
18+
implementation("com.google.maps.android:maps-compose:6.1.0") // Check for the latest version
19+
// Optional: Maps Compose Utilities (for clustering, etc.)
20+
// implementation("com.google.maps.android:maps-compose-utils:6.1.0")
21+
}
22+
```
23+
24+
### For Classic Android Views (Fragments/XML):
1425
```kotlin
1526
dependencies {
1627
// Google Maps SDK for Android
1728
implementation("com.google.android.gms:play-services-maps:19.0.0") // Check for the latest version
1829
}
1930
```
2031

21-
## 2. Setup the Secrets Gradle Plugin
22-
23-
Instead of hardcoding the Google Maps API key in `AndroidManifest.xml`, use the Secrets Gradle Plugin for Android to inject the API key securely.
32+
## 2. Setup the Secrets Gradle Plugin (Mandatory for both)
2433

25-
First, add the plugin to the project-level `build.gradle.kts`:
34+
Never hardcode the API key. Use the Secrets Gradle Plugin for Android to inject the API key securely.
2635

36+
**Project-level `build.gradle.kts`:**
2737
```kotlin
2838
buildscript {
2939
dependencies {
@@ -32,88 +42,103 @@ buildscript {
3242
}
3343
```
3444

35-
Then, apply the plugin in the app-level `build.gradle.kts`:
36-
45+
**App-level `build.gradle.kts`:**
3746
```kotlin
3847
plugins {
39-
// ...
4048
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
4149
}
4250
```
4351

44-
Add the API Key to `local.properties`:
45-
52+
**`local.properties`:**
4653
```properties
4754
MAPS_API_KEY=YOUR_API_KEY
4855
```
4956

50-
In `AndroidManifest.xml`, reference the injected API key meta-data:
51-
57+
**`AndroidManifest.xml`:**
5258
```xml
5359
<manifest ...>
5460
<application ...>
55-
<!-- Google Maps API Key injected by Secrets Gradle Plugin -->
5661
<meta-data
5762
android:name="com.google.android.geo.API_KEY"
5863
android:value="${MAPS_API_KEY}" />
59-
...
6064
</application>
6165
</manifest>
6266
```
6367

6468
## 3. Implement the Map
6569

66-
The standard way to implement a map is by using a `SupportMapFragment`.
70+
### Option A: Jetpack Compose (Maps Compose)
71+
Create a Composable and use `GoogleMap` along with `Marker`.
72+
```kotlin
73+
import androidx.compose.foundation.layout.fillMaxSize
74+
import androidx.compose.runtime.Composable
75+
import androidx.compose.ui.Modifier
76+
import com.google.android.gms.maps.model.CameraPosition
77+
import com.google.android.gms.maps.model.LatLng
78+
import com.google.maps.android.compose.GoogleMap
79+
import com.google.maps.android.compose.Marker
80+
import com.google.maps.android.compose.MarkerState
81+
import com.google.maps.android.compose.rememberCameraPositionState
82+
83+
@Composable
84+
fun MapScreen() {
85+
val singapore = LatLng(1.35, 103.87)
86+
val cameraPositionState = rememberCameraPositionState {
87+
position = CameraPosition.fromLatLngZoom(singapore, 10f)
88+
}
89+
90+
GoogleMap(
91+
modifier = Modifier.fillMaxSize(),
92+
cameraPositionState = cameraPositionState
93+
) {
94+
Marker(
95+
state = MarkerState(position = singapore),
96+
title = "Singapore",
97+
snippet = "Marker in Singapore"
98+
)
99+
}
100+
}
101+
```
67102

68-
**activity_maps.xml:**
103+
### Option B: Classic Android Views
104+
Use `SupportMapFragment` to manage the map lifecycle automatically.
69105
```xml
70-
<?xml version="1.0" encoding="utf-8"?>
106+
<!-- activity_maps.xml -->
71107
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
72-
xmlns:tools="http://schemas.android.com/tools"
73108
android:id="@+id/map"
74109
android:name="com.google.android.gms.maps.SupportMapFragment"
75110
android:layout_width="match_parent"
76-
android:layout_height="match_parent"
77-
tools:context=".MapsActivity" />
111+
android:layout_height="match_parent" />
78112
```
79-
80-
**MapsActivity.kt:**
81113
```kotlin
82-
import android.os.Bundle
83-
import androidx.appcompat.app.AppCompatActivity
84-
import com.google.android.gms.maps.CameraUpdateFactory
85-
import com.google.android.gms.maps.GoogleMap
86-
import com.google.android.gms.maps.OnMapReadyCallback
87-
import com.google.android.gms.maps.SupportMapFragment
88-
import com.google.android.gms.maps.model.LatLng
89-
import com.google.android.gms.maps.model.MarkerOptions
90-
114+
// MapsActivity.kt
91115
class MapsActivity : AppCompatActivity(), OnMapReadyCallback {
92-
93-
private lateinit var map: GoogleMap
94-
95116
override fun onCreate(savedInstanceState: Bundle?) {
96117
super.onCreate(savedInstanceState)
97118
setContentView(R.layout.activity_maps)
98-
99-
// Obtain the SupportMapFragment and get notified when the map is ready to be used.
100-
val mapFragment = supportFragmentManager
101-
.findFragmentById(R.id.map) as SupportMapFragment
119+
val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment
102120
mapFragment.getMapAsync(this)
103121
}
104122

105123
override fun onMapReady(googleMap: GoogleMap) {
106-
map = googleMap
107-
108-
// Add a marker in Singapore and move the camera
109124
val singapore = LatLng(1.35, 103.87)
110-
map.addMarker(MarkerOptions().position(singapore).title("Marker in Singapore"))
111-
map.moveCamera(CameraUpdateFactory.newLatLngZoom(singapore, 10f))
125+
googleMap.addMarker(MarkerOptions().position(singapore).title("Marker in Singapore"))
126+
googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(singapore, 10f))
112127
}
113128
}
114129
```
115130

116-
## 4. Best Practices & Guidelines
117-
* **Lifecycle Management:** `SupportMapFragment` is the recommended approach because it manages the map lifecycle automatically. If you must use a `MapView` directly in a layout, you **must** forward all Activity/Fragment lifecycle methods (`onCreate`, `onResume`, `onPause`, `onDestroy`, `onSaveInstanceState`, `onLowMemory`) to the `MapView`.
118-
* **Main Thread:** All interactions with the `GoogleMap` object must occur on the main UI thread.
119-
* **Permissions:** You do not need to request `ACCESS_FINE_LOCATION` or `ACCESS_COARSE_LOCATION` permissions unless you are explicitly enabling the "My Location" layer via `map.isMyLocationEnabled = true`.
131+
## 4. Advanced Features (Referencing `android-samples`)
132+
133+
When a user asks for advanced features, implement them using these established patterns:
134+
135+
* **Marker Clustering:** Use the `maps-compose-utils` library and the `Clustering` composable. (Classic Views: Use `android-maps-utils` and `ClusterManager`).
136+
* **Drawing on the Map:** Use `Polyline`, `Polygon`, or `Circle` composables.
137+
* **Map Styling:** Apply custom JSON styling via `MapProperties(mapStyleOptions = MapStyleOptions(json))` in Compose, or `googleMap.setMapStyle()` in Classic Views.
138+
* **Live Synchronization:** For multi-device real-time updates (like taxi tracking), use Firebase Realtime Database to push/pull `LatLng` coordinates and animate marker states locally.
139+
* **Location Tracking:** Request `ACCESS_FINE_LOCATION`, then set `isMyLocationEnabled = true` on `MapProperties` (Compose) or `googleMap.isMyLocationEnabled = true` (Classic Views).
140+
141+
## 5. Execution Guidelines
142+
1. Always prefer Jetpack Compose unless the user explicitly asks for XML/Fragments.
143+
2. Never log or commit the raw API key.
144+
3. Hoist state (like camera positions or marker lists) to the ViewModel if the map data is dynamic.

‎llm-integration-prompt.md‎

Lines changed: 78 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,39 @@
1-
# Google Maps SDK for Android - AI Integration Prompt
1+
---
2+
name: maps-sdk-android
3+
description: Guide for integrating the Google Maps SDK for Android (Views/Fragments) and Maps Compose into an Android application. Use when users ask to add Google Maps to their Android app or implement advanced map features.
4+
---
25

3-
You are an expert Android developer specializing in the Google Maps SDK for Android. Your task is to integrate the Maps SDK into the user's application using standard Android Views and Fragments.
6+
# Google Maps SDK for Android Integration
47

5-
Please follow these instructions carefully to ensure a secure and idiomatic implementation.
8+
You are an expert Android developer specializing in the Google Maps SDK for Android. Your task is to integrate the Maps SDK into the user's application. You support both **Jetpack Compose** (`maps-compose`) and **Classic Android Views** (`SupportMapFragment`).
69

710
## 1. Setup Dependencies
811

9-
Add the necessary dependency to the app-level `build.gradle.kts` file:
12+
Add the necessary dependencies to the app-level `build.gradle.kts` file based on the UI framework:
1013

14+
### For Jetpack Compose (Recommended for new apps):
15+
```kotlin
16+
dependencies {
17+
// Google Maps Compose library
18+
implementation("com.google.maps.android:maps-compose:6.1.0") // Check for the latest version
19+
// Optional: Maps Compose Utilities (for clustering, etc.)
20+
// implementation("com.google.maps.android:maps-compose-utils:6.1.0")
21+
}
22+
```
23+
24+
### For Classic Android Views (Fragments/XML):
1125
```kotlin
1226
dependencies {
1327
// Google Maps SDK for Android
1428
implementation("com.google.android.gms:play-services-maps:19.0.0") // Check for the latest version
1529
}
1630
```
1731

18-
## 2. Setup the Secrets Gradle Plugin
19-
20-
Instead of hardcoding the Google Maps API key in `AndroidManifest.xml`, use the Secrets Gradle Plugin for Android to inject the API key securely.
32+
## 2. Setup the Secrets Gradle Plugin (Mandatory for both)
2133

22-
First, add the plugin to the project-level `build.gradle.kts`:
34+
Never hardcode the API key. Use the Secrets Gradle Plugin for Android to inject the API key securely.
2335

36+
**Project-level `build.gradle.kts`:**
2437
```kotlin
2538
buildscript {
2639
dependencies {
@@ -29,88 +42,103 @@ buildscript {
2942
}
3043
```
3144

32-
Then, apply the plugin in the app-level `build.gradle.kts`:
33-
45+
**App-level `build.gradle.kts`:**
3446
```kotlin
3547
plugins {
36-
// ...
3748
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
3849
}
3950
```
4051

41-
Add the API Key to `local.properties`:
42-
52+
**`local.properties`:**
4353
```properties
4454
MAPS_API_KEY=YOUR_API_KEY
4555
```
4656

47-
In `AndroidManifest.xml`, reference the injected API key meta-data:
48-
57+
**`AndroidManifest.xml`:**
4958
```xml
5059
<manifest ...>
5160
<application ...>
52-
<!-- Google Maps API Key injected by Secrets Gradle Plugin -->
5361
<meta-data
5462
android:name="com.google.android.geo.API_KEY"
5563
android:value="${MAPS_API_KEY}" />
56-
...
5764
</application>
5865
</manifest>
5966
```
6067

6168
## 3. Implement the Map
6269

63-
The standard way to implement a map is by using a `SupportMapFragment`.
70+
### Option A: Jetpack Compose (Maps Compose)
71+
Create a Composable and use `GoogleMap` along with `Marker`.
72+
```kotlin
73+
import androidx.compose.foundation.layout.fillMaxSize
74+
import androidx.compose.runtime.Composable
75+
import androidx.compose.ui.Modifier
76+
import com.google.android.gms.maps.model.CameraPosition
77+
import com.google.android.gms.maps.model.LatLng
78+
import com.google.maps.android.compose.GoogleMap
79+
import com.google.maps.android.compose.Marker
80+
import com.google.maps.android.compose.MarkerState
81+
import com.google.maps.android.compose.rememberCameraPositionState
82+
83+
@Composable
84+
fun MapScreen() {
85+
val singapore = LatLng(1.35, 103.87)
86+
val cameraPositionState = rememberCameraPositionState {
87+
position = CameraPosition.fromLatLngZoom(singapore, 10f)
88+
}
89+
90+
GoogleMap(
91+
modifier = Modifier.fillMaxSize(),
92+
cameraPositionState = cameraPositionState
93+
) {
94+
Marker(
95+
state = MarkerState(position = singapore),
96+
title = "Singapore",
97+
snippet = "Marker in Singapore"
98+
)
99+
}
100+
}
101+
```
64102

65-
**activity_maps.xml:**
103+
### Option B: Classic Android Views
104+
Use `SupportMapFragment` to manage the map lifecycle automatically.
66105
```xml
67-
<?xml version="1.0" encoding="utf-8"?>
106+
<!-- activity_maps.xml -->
68107
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
69-
xmlns:tools="http://schemas.android.com/tools"
70108
android:id="@+id/map"
71109
android:name="com.google.android.gms.maps.SupportMapFragment"
72110
android:layout_width="match_parent"
73-
android:layout_height="match_parent"
74-
tools:context=".MapsActivity" />
111+
android:layout_height="match_parent" />
75112
```
76-
77-
**MapsActivity.kt:**
78113
```kotlin
79-
import android.os.Bundle
80-
import androidx.appcompat.app.AppCompatActivity
81-
import com.google.android.gms.maps.CameraUpdateFactory
82-
import com.google.android.gms.maps.GoogleMap
83-
import com.google.android.gms.maps.OnMapReadyCallback
84-
import com.google.android.gms.maps.SupportMapFragment
85-
import com.google.android.gms.maps.model.LatLng
86-
import com.google.android.gms.maps.model.MarkerOptions
87-
114+
// MapsActivity.kt
88115
class MapsActivity : AppCompatActivity(), OnMapReadyCallback {
89-
90-
private lateinit var map: GoogleMap
91-
92116
override fun onCreate(savedInstanceState: Bundle?) {
93117
super.onCreate(savedInstanceState)
94118
setContentView(R.layout.activity_maps)
95-
96-
// Obtain the SupportMapFragment and get notified when the map is ready to be used.
97-
val mapFragment = supportFragmentManager
98-
.findFragmentById(R.id.map) as SupportMapFragment
119+
val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment
99120
mapFragment.getMapAsync(this)
100121
}
101122

102123
override fun onMapReady(googleMap: GoogleMap) {
103-
map = googleMap
104-
105-
// Add a marker in Singapore and move the camera
106124
val singapore = LatLng(1.35, 103.87)
107-
map.addMarker(MarkerOptions().position(singapore).title("Marker in Singapore"))
108-
map.moveCamera(CameraUpdateFactory.newLatLngZoom(singapore, 10f))
125+
googleMap.addMarker(MarkerOptions().position(singapore).title("Marker in Singapore"))
126+
googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(singapore, 10f))
109127
}
110128
}
111129
```
112130

113-
## 4. Best Practices & Guidelines
114-
* **Lifecycle Management:** `SupportMapFragment` is the recommended approach because it manages the map lifecycle automatically. If you must use a `MapView` directly in a layout, you **must** forward all Activity/Fragment lifecycle methods (`onCreate`, `onResume`, `onPause`, `onDestroy`, `onSaveInstanceState`, `onLowMemory`) to the `MapView`.
115-
* **Main Thread:** All interactions with the `GoogleMap` object must occur on the main UI thread.
116-
* **Permissions:** You do not need to request `ACCESS_FINE_LOCATION` or `ACCESS_COARSE_LOCATION` permissions unless you are explicitly enabling the "My Location" layer via `map.isMyLocationEnabled = true`.
131+
## 4. Advanced Features (Referencing `android-samples`)
132+
133+
When a user asks for advanced features, implement them using these established patterns:
134+
135+
* **Marker Clustering:** Use the `maps-compose-utils` library and the `Clustering` composable. (Classic Views: Use `android-maps-utils` and `ClusterManager`).
136+
* **Drawing on the Map:** Use `Polyline`, `Polygon`, or `Circle` composables.
137+
* **Map Styling:** Apply custom JSON styling via `MapProperties(mapStyleOptions = MapStyleOptions(json))` in Compose, or `googleMap.setMapStyle()` in Classic Views.
138+
* **Live Synchronization:** For multi-device real-time updates (like taxi tracking), use Firebase Realtime Database to push/pull `LatLng` coordinates and animate marker states locally.
139+
* **Location Tracking:** Request `ACCESS_FINE_LOCATION`, then set `isMyLocationEnabled = true` on `MapProperties` (Compose) or `googleMap.isMyLocationEnabled = true` (Classic Views).
140+
141+
## 5. Execution Guidelines
142+
1. Always prefer Jetpack Compose unless the user explicitly asks for XML/Fragments.
143+
2. Never log or commit the raw API key.
144+
3. Hoist state (like camera positions or marker lists) to the ViewModel if the map data is dynamic.

0 commit comments

Comments
 (0)