smap_flutter 1.0.5

sMap for Flutter: maps from the sMap service in Flutter apps, with styles, labels in any language, clustered points, lines, areas and 3D buildings.

sMap for Flutter: smap_flutter

Maps from the sMap service for Flutter apps on Android and iOS.

• Five colour schemes: light, white, grayscale, dark, black
• Labels in any language (BCP-47 tags such as en, fr, zh-Hans); the device language by default
• Switching scheme or language keeps every layer you added
• Points at any scale: clustered (tap a cluster to zoom in), circles or your own icons, labels
• Lines (colour, width, dashes) and areas (flat or extruded in 3D)
• 3D buildings
• Draw order, visibility, replacing data, fitting the camera to a layer, tap handlers
• Reads from the nearest service node and moves to the next one when a node fails; keeps working while the service address is down (kept node list, optional seed nodes)
• Short-lived tokens refreshed automatically, or a map key that ships inside the app

The map's attribution button stays visible: the map data licence requires it. Every map shows a small sMap badge in its bottom-right corner, just left of the attribution button.

Installation

From pub.dev:

dependencies:
  smap_flutter: ^1.0.5

Or straight from the repository:

dependencies:
  smap_flutter:
    git:
      url: https://github.com/Goodneo-Solutions/smap-sdk
      path: flutter
      ref: 1.0.5

Requirements: Flutter 3.41 or later, Android minSdk 24 (the Flutter default) with the INTERNET permission, iOS 15 or later.

A minimal map

import 'package:smap_flutter/smap_flutter.dart';

SMap(
  options: SMapOptions(
    getToken: () => myServer.mapToken(),   // see "Tokens"
    style: SMapStyle.light,
    center: const LatLng(43.6532, -79.3832),
    zoom: 11,
  ),
  onReady: (map) async {
    await map.addPoints(
      'stores',
      [const SMapPoint(43.65, -79.38, properties: {'name': 'Queen St'})],
      const SMapPointOptions(cluster: true, label: 'name'),
    );
    map.onTap('stores', (properties, position) => print(properties['name']));
  },
)

Layers may also be added before the map is ready (in onCreated); they are drawn as soon as it is.

Tokens

The service uses short-lived map tokens issued by your server. Give the map either:

• token: a token you already have, or
• getToken: a Future<String> Function() that fetches one. It is called at start when no token is given, and again two minutes before each token expires (a failed call is retried after 30 seconds).

A new token reloads the style with it; your layers are put back automatically. Never ship the secret that signs tokens inside an app: issue tokens from your server.

Controller

Call	What it does
ready	Future that completes once the first style has loaded
setStyle(SMapStyle) / setLanguage(tag)	Switch scheme or label language; layers are kept
setBuildings3D(on, color:, opacity:)	Buildings in 3D below your layers; tilts a flat map to 55°
addPoints(id, points, SMapPointOptions)	GeoJSON or a list of SMapPoint / {lat, lng, properties} maps
addLines(id, lines, SMapLineOptions)	GeoJSON or a list of SMapLine
addPolygons(id, polygons, SMapPolygonOptions)	GeoJSON or a list of SMapPolygon; extrude draws them in 3D
addImage(name, bytes)	Registers an image for the icon of points
setData(id, data) / setVisible(id, visible) / removeLayer(id)	Change a layer
layers()	Layer ids in draw order, bottom first
fitLayer(id, padding: 40, maxZoom: 15)	Show all of a layer's data
onTap(id, handler)	handler(properties, LatLng) for a tapped feature
flyTo(center, zoom:)	Move the camera
engine	The underlying map controller, for anything not wrapped

Draw order: a higher zIndex draws on top; equal values draw in the order added. Errors are raised as SMapException; errors with no caller (token refresh, style reloads) go to the widget's onError.

Map keys

A map key (smk_…) can ship inside the app instead of a token from your server. Create one in the developer center and list your app on its allowlist:

• Android: the package name and the SHA-256 of each signing certificate (debug, release, and the store's app signing key when the store re-signs the app). Print it with keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android | grep SHA256, or apksigner verify --print-certs app-release.apk | grep SHA-256 for a built app.
• iOS: the bundle id.

SMap(options: const SMapOptions(apiKey: 'smk_…'))

The package reads the app's identity from the platform (package name and signing certificate on Android, bundle id on iOS) and sends it, with the key, on every request to the map service's nodes and to no other host; the app cannot set it itself. With a token too, both are sent and the token is checked first.

The map's tile requests go through one HTTP layer shared by every map in the app, which this package sets when it starts. An app that sets its own HTTP client or request headers for the map afterwards (including the global header functions of the map engine package) replaces it, and the map's tile requests no longer carry the app identity.

Options

Option	Default	What it does
baseUrl	https://tile.srsr.ca	The service address; its node list is asked for first
nodes	none	Node URLs known in advance; their node list is asked for when baseUrl does not answer, so a first start works while it is down
token / getToken	none	See "Tokens"
apiKey	none	A map key, see "Map keys"
style	SMapStyle.light	Colour scheme
language	device language	Label language
nearest	true	Read from the nearest node (the measured order is remembered for an hour)
center, zoom, bearing, pitch	0, 0, 1, 0, 0	Initial camera

The last node list received is kept for 30 days. When no node answers for its list (baseUrl, then every other known node in turn), the kept list and nodes are measured instead, so the map keeps working while the service address is down. An order found that way is used for the current run only and is not remembered; the next start asks for the node list again.

Example

example/ is a one-screen demo: scheme and language switchers, 2,000 clustered points, a line, an extruded block and a 3D buildings switch.

cd example
flutter run --dart-define=SMAP_TOKEN=sm1.…   # or --dart-define=SMAP_API_KEY=smk_…