DOCSEARCHbyAlgolia
Submit Docs

Google Maps SDK for Android Samples

repository·main·Indexed 25 days ago

https://github.com/googlemaps-samples/android-samples

A collection of Android samples demonstrating features and implementation patterns of the Google Maps SDK for Android. Includes basic API demos, advanced real-time synchronized animations using a controller/agent architecture with Firebase Realtime Database, and data-driven styling for points, lines, and polygons. The repository provides multiple build variants, including a standard flavor and a Maps SDK V3 BETA flavor, and supports integration with Project IDX.

Tokens
10K
Snippets
17
Records
60
Agent score
82%

What's inside googlemaps-samples-android-samples

  1. Overview of available samples

    main

    This repository contains several distinct sample projects:

    • ApiDemos: A collection of small demos showcasing most features of the Maps SDK for Android.
    • FireMarkers: Demonstrates synchronized, live animations on a Google Map across multiple devices using Firebase Realtime Database and a controller/agent architecture.
    • WearOS: Demonstrates the basic setup required to display a map on a Wear OS device within a Gradle-based Android Studio project.
    • Tutorials: Samples associated with specific tutorials in the Google Maps developer's guide.
    • Snippets: Code snippets corresponding to the documentation found at developers.google.com/maps/documentation/android-sdk.

  2. FireMarkers Architecture Overview

    main

    The FireMarkers application is structured into four main layers to manage real-time map animations via Firebase:

    • UI Layer (View): Composed of MainActivity and MapScreen (Composable). It handles user interactions via TopAppBar actions and renders markers using a GoogleMap Composable.
    • State & Logic Layer (ViewModel): The MarkersViewModel manages the business logic, handles Firebase interactions via the data layer, and exposes StateFlow for the UI to consume.
    • Data Layer: Contains FirebaseConnection (service for Firebase interaction), ShapeData (static vector coordinates), and MarkerData (the data model).
    • Dependency Injection: Uses Hilt/Dagger to inject FirebaseConnection as a singleton into the MarkersViewModel.

  3. How the Controller/Agent architecture works for synchronized animations

    main

    The FireMarkers sample uses a controller/agent architecture to achieve real-time, synchronized map animations across multiple devices.

    • Controller: One device acts as the driver. It writes the animation state (such as progress, running status, and the current controller's ID) to a specific /animation node in the Firebase Realtime Database. The controller provides UI controls to start, stop, and reset the animation.
    • Agent: All other connected devices act as passive observers. They listen for real-time updates from the Firebase /animation node and synchronize their local UI and map animations to match the controller's state.

    This pattern ensures that all users see the same animation at the same time by using a single source of truth in the cloud.

  5. How the FireMarkers controller/agent synchronization works

    main

    FireMarkers uses a controller/agent synchronization pattern powered by Firebase Realtime Database to synchronize animations across multiple devices.

    The Model

    • Controller: Only one device acts as the controller at a time. It runs the animation loop and writes the current animation state (progress and running status) to the /animation node in Firebase.
    • Agents: All other devices are agents. They passively listen to the /animation node and update their local state based on the controller's writes.

    Synchronization Flow

    1. Control Transfer: An agent can request control by triggering a takeControl action, which updates the controllerId field in the /animation node.
    2. Animation Loop: The controller calculates animation progress and writes it to Firebase.
    3. Real-time Updates: All clients (controllers and agents) maintain listeners on two specific Firebase paths:
      • /markers: For marker data (e.g., after seeding or clearing).
      • /animation: For the current animation state (progress/fraction).
    4. Interpolation: The MarkersViewModel combines the marker data and the animation state using a combine operator. It uses the animation fraction to calculate the interpolated position and color for every marker.
    5. UI Rendering: The MapScreen composable collects the resulting StateFlow of interpolated data, causing the GoogleMap to recompose and animate markers smoothly.

  7. Open Google Maps Android samples in Project IDX

    main

    You can open specific Google Maps Platform Android tutorial code samples directly in the Project IDX IDE using a template URL. This allows you to quickly set up a development environment for a specific sample without manual cloning and configuration.

    To open a sample, construct a URL using the Project IDX new workspace endpoint with the following query parameters:

    • template: Must be https://github.com/googlemaps-samples/android-samples/open-in-idx-template.
    • giturl: The URL of the repository (e.g., https://github.com/googlemaps-samples/android-samples).
    • subdir: The specific subdirectory within the repository containing the sample you want to open.
    • launchactivity: The full component name of the Activity to launch (e.g., package.name/.ActivityName).
    • apikey: Your Google Maps Platform API Key. Note: There is no default value for the API Key. You must provide it in the URL or via the IDX workspace creation dialog.

    If a parameter is omitted from the URL, the template will use the default value defined in idx-template.json. If no default is defined and the parameter is missing from the URL, IDX will prompt you to enter the value during workspace creation.

  8. Configure the Google Maps API key for Wear OS

    main

    The sample requires a Google Maps API key to function. To provide your key without committing it to version control, use a secrets.properties file.

    1. Obtain an API key from the Google Maps documentation.
    2. Locate or create a file named secrets.properties in the top-level directory (the same folder as local.properties).
    3. Add your key using the MAPS_API_KEY variable, replacing YOUR_API_KEY with your actual key.
    MAPS_API_KEY=YOUR_API_KEY

  10. Verify the build and run instrumentation tests

    main

    You can verify that all samples build and pass tests using the provided verification scripts. Use these commands from the root of the repository.

    Build Verification

    To verify that all samples build and pass tests:

    ./scripts/verify_all.sh

    Running Instrumentation Tests

    To run tests on a connected device or emulator, use the following flags:

    • For Wear OS devices/emulators:
      ./scripts/verify_all.sh --connected-wear
    • For Mobile (Handheld) devices/emulators:
      ./scripts/verify_all.sh --connected-mobile

    Alternatively, you can use gradlew build to build the project directly or download pre-built APKs from the releases page.

    ./scripts/verify_all.sh --connected-mobile

  11. Run the Google Maps Android samples

    main

    To run the samples locally using Android Studio:

    1. Clone the repository to your local machine.
    2. Open Android Studio.
    3. On the welcome screen, select Open an Existing project.
    4. Select the root directory of the cloned repository (android-samples).

  12. Run the MapWithMarker Java sample

    main

    To run this sample, follow these steps:

    1. Download the source: Clone this repository or download an archived snapshot.
    2. Open in Android Studio: Use the "Open an existing Android Studio project" option and select the tutorials/java/MapWithMarker directory.
    3. Configure Gradle: If prompted for Gradle configuration, accept the default settings. Alternatively, you can build the project via the command line using ./gradlew build.
    4. Add API Key: This demo requires a valid Google Maps API key to function. You must obtain one from the Google Maps Platform and add it to the project configuration.