Skip to content

Upgrading from 3.x and 4.0.x to 4.1

Jump to bottom
Mark Tehver edited this page Sep 13, 2017 · 6 revisions

Upgrading to SDK 4.1

Starting from version 4.1 CARTO Mobile SDK uses new schema (OpenMapTiles/OMT) for vector tiles. This applies to online map tiles and offline map packages. New built-in styles (Voyager, Positron, Darkmatter) work only with the new schema. New schema provides several advantages:

  • The schema has official specification and is open
  • Map data is updated more frequently
  • All OpenStreetMap languages are included in the tiles

The new schema can be used with new source name 'carto.streets'. Old schema 'nutiteq.osm' continues to work but no map data updates are planned. Also note that the new built-in styles (Voyager, Positron, Darkmatter) are not compatible with 'nutiteq.osm' source and old styles (Nutibright, Dark, Grey) must be bundled with the application.

Online case

Switching to new schema when using online tiles (CartoOnlineVectorTileLayer) is simple:

  • Use 'carto.streets' as source instead of 'nutiteq.osm'
  • Replace CartoBaseMapStyle.CARTO_BASE_MAP_STYLE_DEFAULT with CartoBaseMapStyle.CARTO_BASE_MAP_STYLE_VOYAGER
  • Replace CartoBaseMapStyle.CARTO_BASE_MAP_STYLE_DARK with CartoBaseMapStyle.CARTO_BASE_MAP_STYLE_DARKMATTER
  • Replace CartoBaseMapStyle.CARTO_BASE_MAP_STYLE_GRAY with CartoBaseMapStyle.CARTO_BASE_MAP_STYLE_POSITRON

The new styles have better design, better performance on low-end devices and use consistent information density accross all zoom levels.

Offline case

Offline case is more tricky as existing users may have already downloaded offline packages that are expected to work. There are few options regarding upgrading to new schema:

  • Keep using old packages and old source.
  • Delete old packages and force upgrading to new source.
  • Mix old packages with packages from the new source.

Each of the options is described in the following sections.

Keep using old packages and old source.

This requires bundling old styles with the application. This is simplest option but implies no map updates and outdated map styling.

Delete old packages and force upgrading to new source.

In simple cases users can be simply informed about the upgrade and have to re-download needed packages from 'carto.streets' source. In more complex cases the old packages can be downloaded from 'carto.streets' source automatically while displaying online map during the download process. This is the suggested option. Note that re-downloading existing packages is sometimes not trivial as package list has changed in 'carto.streets' vs 'nutiteq.osm'.

Mix old packages with packages from the new source.

This option is only available if map packages do not overlap and are not shown together. In this case it would be possible to create two PackageManager instances (with different package folders) and choose between the instances case by case.

'carto.streets' packages vs 'nutiteq.osm' packages

When comparing the package lists from 'carto.streets' and 'nutiteq.osm' sources, there are following differences:

  • Very large packages like GB, DE, FR are no longer available. For these countries only split packages (GB-ENG, GB-WLS, etc) are available.
  • Some packages have smaller subpackages (RU, IT, JP etc).

When automatically upgrading from old packages and a package XX is missing from the 'carto.streets' source, the following simple rule can be used:

  • Find and download all packages with prefix 'XX-' from the 'carto.streets' source
Clone this wiki locally