-
Notifications
You must be signed in to change notification settings - Fork 68
Upgrading from 3.x and 4.0.x to 4.1
Starting from version 4.1 CARTO Mobile SDK uses new schema carto.streets for vector tiles, it is based on OMT schema. This applies to both online map tiles and offline map packages. We have also new built-in styles (Voyager, Positron, Darkmatter) and these 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 - once a month
- 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 until end of 2018, 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 if you need to continue using them.
Switching to new schema when using online tiles (CartoOnlineVectorTileLayer) is simple:
- Use
'carto.streets'as source instead of 'nutiteq.osm' in CartoOnlineTileDataSource - 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 across all zoom levels.
If you use custom styling for basemaps, then also the styling has to be changed, as list of layers and attributes is different. Please contact CARTO support if you need help with this.
Offline case is more tricky as existing users may have already downloaded offline packages that are expected to work. The old packages are with old schema, but our updated SDK does not have bundled styles for it anymore. There are few options regarding upgrading to new schema:
- Let user to delete old packages and force downloading new data packages
- Mix old packages with packages from the new source.
- Keep using old packages and old source. The old packages are not updated, so use this as last resort.
Each of the options is described in the following sections.
We suggest users to be informed that your new app update requires re-download of offline packages, which is needed to get future updates and use newer and nicer style. Same packages as were already downloaded can be downloaded from 'carto.streets' source automatically, while displaying online map during the download process. Generally the packages have exactly the same ID-s for both sources, but there are some exceptions:
- Some very large country packages like GB, DE, FR are no longer available. For these countries only split packages (GB-ENG, GB-WLS, etc) are available. It is generally not user-friendly to let to download whole France or Germany, these take over 2GB each. So your app should give user selection which sub-package they really want to re-download.
- Some packages have new smaller sub-packages (RU, IT, JP etc). Also for these it is suggested to offer subpackages, even if automatic redownload of complete country is technically possible.
- Map of new packages
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.
This requires bundling old styles with the application. No re-download is needed, but no map updates are provided and outdated map styling is in use. Also the old source may be removed from server after some time.