Skip to content

Latest commit

 

History

History
284 lines (203 loc) · 11 KB

README.md

File metadata and controls

284 lines (203 loc) · 11 KB
Raw

Journey Maps Client Flutter

This package allows you to easily incorporate SBB maps into your Flutter application. Te

iOS and Android example showcases

Table Of Contents

Introduction

The package is meant as a client for the Journey Maps API and is based on the Flutter Maplibre GL plugin - solely for Android and iOS.

Getting Started

Supported platforms

Android iOS

Precondition

In order to access styles and tile data, you need to register your application to the Journey Maps Tile API to receive an API Key. Create an account (e.g. using SwissPass Login) to be able to setup an application and then register this application to the API.

Installation

Since this package is not on pubdev yet, you need to add it to your pubspec.yaml file like this:

dependencies:
    ...
    sbb_maps_flutter:
      git:
        url: [email protected]:SchweizerischeBundesbahnen/journey-maps-client-flutter.git
        ref: main \\ might be prone for breaking changes - use a TAG REF

In code usage

API key

Make the API Key accessible to your application. Either

  1. add it as env var (not recommended):
JOURNEY_MAPS_API_KEY='YOUR_API_KEY_HERE'
  1. Or use a package such as envied for clean env var handling and obfuscating your API key, making it harder to reverse engineer (in public apps!). Pass the env key to the SBBRokasMapStyler as constructor parameter. Use this styler to the SBBMap as mapStyler parameter.
SBBRokasMapStyler.full(apiKey: Env.MY_API_KEY_NAME);
Adding the map
SBBMap(
  initialCameraPosition: const SBBCameraPosition(
    target: LatLng(46.947456, 7.451123), // Bern
    zoom: 15.0,
  ),
  mapStyler: _customStylerWithApiKey // as from above
)
Accessing user location

This package uses the geolocator flutter plugin for accessing the device location and asking the user for permissions. See the package for detailed instructions on accessing the device location. In short:

iOS

Add this to your Info.plist file.

<key>NSLocationWhenInUseUsageDescription</key>
<string>YOUR DESCRIPTION WHY YOU NEED ACCESS TO THE MAP<string>

Android

Add these to your AndroidManifest.xml file. If both are specified, the geolocator plugin uses the ACCESS_FINE_LOCATION setting.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
Focusing on user location when building map

To directly focus the map camera onto the device location when the SBBMap is built, use the OnMapLocatorAvailable callback and the SBBMapLocator.trackDeviceLocation() method. This has the nice side effect, that the user will be prompted for permissions if not granted already.

This can be seen in the Track Device route in the example app here: track_device_location_route.dart.

Tested deployment platforms

iOS Android SDK
Oldest Tested 15.5 28
Latest Tested 17.6 34

Tested with the latest (stable channel) and oldest supported (3.19.6) Flutter SDK.

Example App

Icon of the example app

The SBB Karten demo application is available both in the SBB Enterprise Playstore (Android) and in the managed iOS SBB Store (Ivanti MobileIron).

Documentation

Features

Feature iOS Android
Gesture ✅ ✅
Camera ✅ ✅
Map Styles (including ROKAS Styles) ✅ ✅
Location (including device tracking) ✅ ✅
Customizable UI ✅ ✅
Floor Switcher (switch levels) ✅ ✅
ROKAS POIs: Display ✅ ✅
ROKAS POIs: Event Triggering and Select ✅ ✅
Annotations ✅ ✅
- Circles (Display & OnClick) ✅ ✅
- ROKAS Markers (Display & OnClick) ✅ ✅
- Custom Markers (Display & OnClick) ✅ ✅
- Fill Annotations (Display & OnClick) ✅ ✅
- Line Annotations (Display & OnClick) ✅ ✅
Routing (Beta) ✅ ✅

Custom Map Properties

Custom properties of the map (e.g. compass position, disabling certain gestures) can be set using the SBBMapProperties class, given as properties parameter in the SBBMap constructor.

// the defaults
const SBBMapProperties({
    this.compassEnabled = true,
    this.compassViewPosition = CompassViewPosition.topLeft,
    this.compassViewMargins,
    this.rotateGesturesEnabled = true,
    this.scrollGesturesEnabled = true,
    this.doubleClickZoomEnabled = true,
    this.dragEnabled = true,
  });

Gallery and Examples

Standard Map

The default SBB map with ROKAS styling (see standard_map_route.dart).

Plain Map

How to disable all UI components while using ROKAS Map styling. (see plain_map_route.dart).

Camera Movement

Programmatic control over camera movement (see camera_route.dart).

Custom UI

Customizing the map UI using the builder (see custom_ui_route.dart).

ROKAS Point of Interests

Displaying and interacting ROKAS POIs (see poi_route.dart).

Custom UI

Customizing the map UI using the builder (see custom_ui_route.dart).

Map Properties

Using map properties (see map_properties_route.dart).

Annotations

Displaying and interacting with custom annotations (see display_annotations_route.dart).

Track device location on map build

Displaying user device location on build (see track_device_location_route.dart).

Read on

License

This project is licensed under MIT.

Contributing

This repository includes a CONTRIBUTING.md file that outlines how to contribute to the project, including how to submit bug reports, feature requests, and pull requests.

Maintainer

Contributors

  • Loris Sorace
  • Hoang Tran

Coding Standards

See CODING_STANDARDS.md.

Code of Conduct

See CODE_OF_CONDUCT.md.

Caveats, limitations and known bugs*

Limitations

  • When selecting POIs programmatically with the RokasPOIController, one can only select from the POIs that are loaded in the tile source, meaning that trying to select a POI at a very distant place will not be possible. The workaround would be to first move to the geo coordinate and then select the POI.