Skip to content

Commit 249df26

Browse files
kikosokikoso
committed
docs: pivot AI guidelines to teach Maps SDK integration
1 parent a190fff commit 249df26

2 files changed

Lines changed: 222 additions & 33 deletions

File tree

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

Lines changed: 109 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,119 @@
11
---
2-
name: android-samples
3-
description: Guide for understanding and using the Google Maps SDK for Android Samples repository. Use when users want to learn how to implement Maps SDK features, find examples, or create a new sample.
2+
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.
44
---
55

6-
# Google Maps SDK for Android Samples
6+
# Google Maps SDK for Android Integration
77

8-
You are an expert Android developer specializing in the Google Maps SDK for Android. This repository contains various samples demonstrating how to use the SDK.
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.
99

10-
## Repository Structure
10+
## 1. Setup Dependencies
1111

12-
1. **ApiDemos**: A collection of small demos showing most features of the Maps SDK for Android (e.g., markers, polygons, camera movement, location).
13-
2. **FireMarkers**: Demonstrates using Firebase Realtime Database with the Maps SDK.
14-
3. **WearOS**: Demonstrates a basic map on a Wear OS device.
15-
4. **tutorials**: Samples associated with tutorials in the developer's guide.
16-
5. **snippets**: Snippets for code found in the official documentation.
12+
Add the necessary dependency to the app-level `build.gradle.kts` file:
1713

18-
## Running the Samples
14+
```kotlin
15+
dependencies {
16+
// Google Maps SDK for Android
17+
implementation("com.google.android.gms:play-services-maps:19.0.0") // Check for the latest version
18+
}
19+
```
1920

20-
To run the samples, the user needs:
21-
- A Google Maps API key added to `local.properties`: `MAPS_API_KEY=YOUR_API_KEY`
22-
- The Secrets Gradle Plugin for Android is used to inject the API key.
21+
## 2. Setup the Secrets Gradle Plugin
2322

24-
## Creating a New Sample
25-
When creating a new sample or modifying an existing one:
26-
1. Ensure the code is written in Kotlin.
27-
2. Follow modern Android development practices.
28-
3. Use the Secrets Gradle plugin for API key management.
29-
4. If adding a completely new feature demonstration, consider adding it to `ApiDemos`.
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.
3024

31-
## AI Guidelines
32-
Always refer to `.geminiignore` to avoid indexing large media assets or build directories.
25+
First, add the plugin to the project-level `build.gradle.kts`:
26+
27+
```kotlin
28+
buildscript {
29+
dependencies {
30+
classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
31+
}
32+
}
33+
```
34+
35+
Then, apply the plugin in the app-level `build.gradle.kts`:
36+
37+
```kotlin
38+
plugins {
39+
// ...
40+
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
41+
}
42+
```
43+
44+
Add the API Key to `local.properties`:
45+
46+
```properties
47+
MAPS_API_KEY=YOUR_API_KEY
48+
```
49+
50+
In `AndroidManifest.xml`, reference the injected API key meta-data:
51+
52+
```xml
53+
<manifest ...>
54+
<application ...>
55+
<!-- Google Maps API Key injected by Secrets Gradle Plugin -->
56+
<meta-data
57+
android:name="com.google.android.geo.API_KEY"
58+
android:value="${MAPS_API_KEY}" />
59+
...
60+
</application>
61+
</manifest>
62+
```
63+
64+
## 3. Implement the Map
65+
66+
The standard way to implement a map is by using a `SupportMapFragment`.
67+
68+
**activity_maps.xml:**
69+
```xml
70+
<?xml version="1.0" encoding="utf-8"?>
71+
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
72+
xmlns:tools="http://schemas.android.com/tools"
73+
android:id="@+id/map"
74+
android:name="com.google.android.gms.maps.SupportMapFragment"
75+
android:layout_width="match_parent"
76+
android:layout_height="match_parent"
77+
tools:context=".MapsActivity" />
78+
```
79+
80+
**MapsActivity.kt:**
81+
```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+
91+
class MapsActivity : AppCompatActivity(), OnMapReadyCallback {
92+
93+
private lateinit var map: GoogleMap
94+
95+
override fun onCreate(savedInstanceState: Bundle?) {
96+
super.onCreate(savedInstanceState)
97+
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
102+
mapFragment.getMapAsync(this)
103+
}
104+
105+
override fun onMapReady(googleMap: GoogleMap) {
106+
map = googleMap
107+
108+
// Add a marker in Singapore and move the camera
109+
val singapore = LatLng(1.35, 103.87)
110+
map.addMarker(MarkerOptions().position(singapore).title("Marker in Singapore"))
111+
map.moveCamera(CameraUpdateFactory.newLatLngZoom(singapore, 10f))
112+
}
113+
}
114+
```
115+
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`.

‎llm-integration-prompt.md‎

Lines changed: 113 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,116 @@
1-
# Google Maps SDK for Android Samples - AI Integration Prompt
1+
# Google Maps SDK for Android - AI Integration Prompt
22

3-
You are an expert Android developer. Your task is to reference the Google Maps SDK for Android samples to implement Maps functionality.
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.
44

5-
## Core Concepts to Reference
6-
- **Setup**: Always use the Secrets Gradle Plugin to inject `MAPS_API_KEY` from `local.properties`.
7-
- **ApiDemos**: Look at the `ApiDemos` directory for concise examples of markers, map styles, camera controls, and overlays.
8-
- **Snippets**: Refer to the `snippets` directory for raw, documentation-ready code blocks.
5+
Please follow these instructions carefully to ensure a secure and idiomatic implementation.
96

10-
## Example Integration
11-
To integrate a basic map, follow the patterns shown in the `ApiDemos` project:
12-
1. Include `com.google.android.gms:play-services-maps` in dependencies.
13-
2. Setup the `SupportMapFragment` or `MapView`.
14-
3. Implement `OnMapReadyCallback`.
7+
## 1. Setup Dependencies
8+
9+
Add the necessary dependency to the app-level `build.gradle.kts` file:
10+
11+
```kotlin
12+
dependencies {
13+
// Google Maps SDK for Android
14+
implementation("com.google.android.gms:play-services-maps:19.0.0") // Check for the latest version
15+
}
16+
```
17+
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.
21+
22+
First, add the plugin to the project-level `build.gradle.kts`:
23+
24+
```kotlin
25+
buildscript {
26+
dependencies {
27+
classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
28+
}
29+
}
30+
```
31+
32+
Then, apply the plugin in the app-level `build.gradle.kts`:
33+
34+
```kotlin
35+
plugins {
36+
// ...
37+
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
38+
}
39+
```
40+
41+
Add the API Key to `local.properties`:
42+
43+
```properties
44+
MAPS_API_KEY=YOUR_API_KEY
45+
```
46+
47+
In `AndroidManifest.xml`, reference the injected API key meta-data:
48+
49+
```xml
50+
<manifest ...>
51+
<application ...>
52+
<!-- Google Maps API Key injected by Secrets Gradle Plugin -->
53+
<meta-data
54+
android:name="com.google.android.geo.API_KEY"
55+
android:value="${MAPS_API_KEY}" />
56+
...
57+
</application>
58+
</manifest>
59+
```
60+
61+
## 3. Implement the Map
62+
63+
The standard way to implement a map is by using a `SupportMapFragment`.
64+
65+
**activity_maps.xml:**
66+
```xml
67+
<?xml version="1.0" encoding="utf-8"?>
68+
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
69+
xmlns:tools="http://schemas.android.com/tools"
70+
android:id="@+id/map"
71+
android:name="com.google.android.gms.maps.SupportMapFragment"
72+
android:layout_width="match_parent"
73+
android:layout_height="match_parent"
74+
tools:context=".MapsActivity" />
75+
```
76+
77+
**MapsActivity.kt:**
78+
```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+
88+
class MapsActivity : AppCompatActivity(), OnMapReadyCallback {
89+
90+
private lateinit var map: GoogleMap
91+
92+
override fun onCreate(savedInstanceState: Bundle?) {
93+
super.onCreate(savedInstanceState)
94+
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
99+
mapFragment.getMapAsync(this)
100+
}
101+
102+
override fun onMapReady(googleMap: GoogleMap) {
103+
map = googleMap
104+
105+
// Add a marker in Singapore and move the camera
106+
val singapore = LatLng(1.35, 103.87)
107+
map.addMarker(MarkerOptions().position(singapore).title("Marker in Singapore"))
108+
map.moveCamera(CameraUpdateFactory.newLatLngZoom(singapore, 10f))
109+
}
110+
}
111+
```
112+
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`.

0 commit comments

Comments
 (0)