Map backend configuration reference

Here you can find the configuration options for the Kanzi Maps backends.

General settings

geocenter

Sets the default geographic center of the map in WGS84 (World Geodetic System 1984) coordinates.

This setting overrides the default property value set in MapView. If you do not set the geographic center, you can set the default geographic center in the MapView properties. See MapView documentation.

Syntax	<geocenter latitude="value" longitude="value"/>
Attributes	latitude The north-south position of the geographic center of the map in degrees. longitude The east-west position of the geographic center of the map in degrees.
Examples	<geocenter latitude="36.114647" longitude="-115.172813"/>

cache

Sets the cache root folder.

This setting is optional. By default the cache root folder is either the Kanzi Studio Preview Working Directory, which by default is Application/bin/, or on Android the dedicated system-provided cache directory.

Syntax	<cache folder="value" />
Attributes	folder Absolute path to the cache root folder.
Examples	<cache folder="/tmp/" />

proxy

Sets the backends, which support proxy, to route all HTTP traffic through the proxy that you specify.

This setting is optional.

Syntax	<proxy url="value" />
Attributes	url URL of the proxy in cURL format.
Examples	<proxy url="http://192.168.201.128:3128" />

caCert

Sets the absolute path to the CA (Certificate Authority) certificate bundle that Kanzi Maps uses to verify the identity of the backend servers when it connects to them over HTTPS.

How the backends obtain the trusted CA certificates depends on the platform:

• On Windows, Kanzi Maps reads the trusted CA certificates from the native Windows certificate store. This setting is ignored, and you do not need to provide a certificate file.

• On Linux, QNX, and Android, Kanzi Maps does not use a system certificate store. You must set caCert to a valid CA certificate bundle to enable SSL peer verification. If you do not, Kanzi Maps disables SSL peer verification and logs a warning. The connection is still encrypted, but Kanzi Maps does not verify the server identity, which leaves the connection vulnerable to man-in-the-middle attacks.

The certificate bundle is a PEM file that contains the public certificates of the Certificate Authorities you trust. It does not contain any private keys or secrets. For how to obtain or create this file, see Obtaining a CA certificate bundle. For how this setting interacts with the sslCertVerify setting, see SSL certificate verification behavior.

Note

On Linux, QNX, and Android, set caCert to a valid CA certificate bundle in production. Without it, Kanzi Maps cannot verify the backend server identity and disables SSL peer verification.

Syntax	<caCert path="value" />
Attributes	path Absolute path to the CA certificate bundle in PEM format. Required on Linux, QNX, and Android. Ignored on Windows.
Examples	<caCert path="/sdcard/cacert.pem" />

Obtaining a CA certificate bundle

On Linux, QNX, and Android, you must provide the CA certificate bundle that you reference in the caCert setting. Kanzi Maps does not ship a certificate bundle. The bundle is a PEM file that contains one or more CA certificates, where each certificate is a Base64 block:

# <Name of the issuing Certificate Authority>
-----BEGIN CERTIFICATE-----
<Base64-encoded certificate data>
-----END CERTIFICATE-----

To connect to the public Mapbox and TomTom servers (and the HERE routing servers), use a standard public root bundle. You can obtain one in any of these ways:

• Download the Mozilla CA bundle that the cURL project distributes as cacert.pem from https://curl.se/docs/caextract.html, then deploy the file to your device.

• Copy the CA bundle that your Linux distribution maintains, for example /etc/ssl/certs/ca-certificates.crt on Debian and Ubuntu, or /etc/pki/tls/certs/ca-bundle.crt on Red Hat and Fedora.

• Generate a fresh bundle from the Mozilla source with the mk-ca-bundle.pl script that ships with cURL.

• Manually construct a minimal bundle that contains only the root Certificate Authority certificates that the map provider’s servers actually use. Identify the issuing authority by inspecting the server certificate chain, for example with openssl s_client -connect api.mapbox.com:443 -showcerts, obtain that root CA certificate from the authority’s official distribution point, and add only that certificate to the bundle. This approach minimizes the set of authorities that Kanzi Maps trusts, but you must update the bundle if the provider changes its Certificate Authority.

Deploy the resulting file to each device and set the caCert path to its absolute location.

sslCertVerify

Sets whether to verify the SSL certificate. By default, the SSL certificate verification is enabled. You can use this setting to disable the verification during development.

On Linux, QNX, and Android, this setting works together with the caCert setting. For details, see SSL certificate verification behavior.

Syntax	<sslCertVerify enabled="value" />
Attributes	enabled Whether to verify the SSL certificate. The default is true.
Examples	<sslCertVerify enabled="false" />

SSL certificate verification behavior

The caCert and sslCertVerify settings together determine whether Kanzi Maps verifies the identity of the backend servers. They apply to all requests from the Mapbox and TomTom backends, and to the routing requests from the HERE backend. They do not affect HERE map tile requests, which the HERE OLP SDK handles with its own TLS configuration. The requests behave as follows.

Platform	sslCertVerify	caCert	Behavior
Windows	true (default)	Ignored	Kanzi Maps verifies the server identity against the native Windows certificate store.
Windows	false	Ignored	Kanzi Maps disables SSL peer verification.
Linux, QNX, Android	true (default)	Set to a valid bundle	Kanzi Maps verifies the server identity against the specified CA certificate bundle.
Linux, QNX, Android	true (default)	Not set, or path is invalid	Kanzi Maps disables SSL peer verification and logs a warning. The connection is encrypted but unauthenticated.
Linux, QNX, Android	false	Any	Kanzi Maps disables SSL peer verification.

When Kanzi Maps disables SSL peer verification, HTTPS connections still encrypt traffic, but Kanzi Maps does not verify that it is connected to the genuine backend server. Disable verification only during development. In production, set caCert on Linux, QNX, and Android, and keep sslCertVerify enabled on all platforms.

offlineTiles

Configures the location and state of usage of offline tile packages with offline tile manager. Offline tiles are prerecorded files that Kanzi Maps can use when no network connectivity is available. See Using offline map tiles.

Syntax	<offlineTiles folder="value" enabled="value" />
Attributes	folder The directory where the offline tile packages are stored. Specify the path to the directory relative to the Kanzi Studio Preview Working Directory, which by default is Application/bin/. On Android you can place the directory in the APK. enabled Whether to enable the use of the offline tile manager. Enable the use of the offline tile manager only when you want to use offline map tiles.
Examples	<offlineTiles folder="offlineTiles" enabled="false" />

offlineRoutes

Configures the location and state of usage of offline route packages with the offline route manager. Offline routes are prerecorded files that Kanzi Maps can use when no network connectivity is available. See Using offline routes.

Syntax	<offlineRoutes folder="value" enabled="value" />
Attributes	folder The directory where the offline route packages are stored. Specify the path to the directory relative to the Kanzi Studio Preview Working Directory, which by default is Application/bin/. On Android you can place the directory in the APK. enabled Whether to enable the use of the offline route manager. Enable the use of the offline route manager only when you want to use offline routes.
Examples	<offlineRoutes folder="offlineRoutes" enabled="false" />

offlineMode

Forces Kanzi Maps to fetch tiles and routes from offline managers instead of online requests.

Syntax	<offlineMode enabled="value" />
Attributes	enabled Whether to fetch tiles and routes from offline managers instead of online requests. The default is false.
Examples	<offlineMode enabled="false" />

offlineBounds

Sets the use of offline areas which are set for offline tiles and read by the offline manager for the current backend.

The scrolling of the Map View node is restricted in offline areas.

Currently this setting is mostly useful when recording tiles.

Syntax	<offlineBounds enabled="value" />
Attributes	enabled Whether to use offline areas. The default is false.
Examples	<offlineBounds enabled="false" />

prefetch

Configures tile prefetching.

The prefetching works currently only for zoom levels. The minZoomLevel attribute defines the minimum zoom level to which Kanzi Maps prefetches tiles. For example, if the minimum zoom level is 2 and the current zoom level is 14, Kanzi Maps fetches all tiles between and including zoom levels 2 and 14.

Currently this setting is mostly useful when recording tiles.

Syntax	<prefetch minZoomLevel="value" enabled="value" />
Attributes	minZoomLevel Minimum zoom level to which you want to prefetch tiles. enabled Whether to prefetch tiles. The default is false.
Examples	<prefetch minZoomLevel="0" enabled="false" />

tileFetch

Sets the retry interval for tile fetch.

The retry happens when tile fetching fails because of a network connection error.

Syntax	<tileFetch retryIntervalSeconds="value" />
Attributes	retryIntervalSeconds Retry interval in seconds.
Examples	<tileFetch retryIntervalSeconds="3" />

taskScheduler

Configures the number of threads used by the thread pools that Kanzi Maps uses internally to run tasks related to processing map content.

Kanzi Maps uses one thread pool for CPU-intensive computational tasks, and another thread pool for IO-intensive tasks, that is, mostly blocking tasks.

For example, to force only one concurrent tile fetch, set ioWorkers="1".

Syntax	<taskScheduler ioWorkers="value" computeWorkers="value" />
Attributes	ioWorkers Number of IO worker threads used by the thread pools. The default is 8. computeWorkers Number of compute worker threads used by the thread pools. The default is 4.
Examples	<taskScheduler ioWorkers="8" computeWorkers="4" />

inMemoryTileCache

Configures the number of complete tiles to keep in cache and the maximum amount of combined GPU and CPU memory that the cached tiles can consume.

Syntax	<inMemoryTileCache maxSize="value" maxMemoryUsageKb="value" />
Attributes	maxSize Maximum number of tiles to keep in cache. maxMemoryUsageKb Maximum amount of combined GPU and CPU memory in kilobytes for the cached tiles to consume.
Examples	<inMemoryTileCache maxSize="100" maxMemoryUsageKb="32768" />

backend

Each backend has its own settings embedded in the map_settings.xml file. Use the backend element to configure backend-specific settings.

Kanzi Maps selects as active the backend that you list first in the map_settings.xml file.

For the settings specific to each supported backend, see Backend-specific settings.

Attributes	name Kanzi metaclass name of the backend. filename The filename of the library without extension and without a possible platform-specific prefix, such as ‘lib’.
Examples	<backend name="Maps.MapboxBackend" filename="mapbox_backend"> ... </backend>

Backend-specific settings

This section lists the settings specific to each backend supported by Kanzi Maps:

• Mapbox. See Mapbox settings.

• Here OLP Edge. See Here OLP Edge settings.

• TomTom. See TomTom settings.

Mapbox settings

This section describes the configuration options for the Mapbox backend.

To use the Mapbox backend, in the map_settings.xml file in the backend element set:

• name="Maps.MapboxBackend"

• filename="mapbox_backend"

For example:

<backend name="Maps.MapboxBackend" filename="mapbox_backend">
    <login accessToken="-- access token --" />
    <diskCache maxFileCount="9000" maxDiskUsageKb="65536" disableEviction="false" />
    <offlineTiles folder="mapbox_tiles" enabled="false" />
    <offlineDemoRoutes folder="mapbox_demo_routes" mode="disabled" />
</backend>

login

Configures the login credentials required by Mapbox services. The backend uses the Mapbox vector and raster tiles, routing, and geocoding services.

To register and receive a Mapbox authentication token, visit https://www.mapbox.com.

Attributes	accessToken Access token.
Examples	<login accessToken="-- access token --" />

diskCache

Configures the Mapbox-specific on-disk tile cache.

To reduce the amount of tile fetches and related API calls over the network, Mapbox caches tile content to disk.

By default cache eviction is enabled, that is, Mapbox removes cached tiles from disk to make space for new tiles.

When you disable cache eviction by setting disableEviction="true", the maxFileCount and maxDiskUsageKb have no effect, the backend does not remove cached tiles from disk, and the cache can grow without limits.

Attributes

maxFileCount Maximum number of files allowed in cache when cache eviction is enabled. maxDiskUsageKb Total maximum size of cached tiles on disk in kilobytes when cache eviction is enabled. disableEviction Whether cache eviction is disabled. By default cache eviction is enabled (disableEviction="false"). When you disable cache eviction, the maxFileCount and maxDiskUsageKb attributes have no effect.

Examples

<diskCache maxFileCount="9000" maxDiskUsageKb="65536" disableEviction="false" />

offlineTiles

Configures the location and state of use of offline tiles. Offline tiles are prerecorded files that Kanzi Maps can use when no network connectivity is available.

Currently offline tiles are simply the cached tiles copied into a separate directory. The default tile cache folder is Application/bin/mapbox_cache.

It is usually better to disable the use of offline tiles, because enabling offline tiles causes extra file system access when loading tiles.

To learn how to generate and use offline tiles, see Using offline map tiles.

Attributes	folder The directory where Mapbox offline tiles are stored. Specify the path to the directory relative to the Kanzi Studio Preview Working Directory, which by default is Application/bin/. On Android you can place the directory in the APK. enabled Whether to enable the use of offline tiles.
Examples	<offlineTiles folder="mapbox_tiles" enabled="false" />

offlineDemoRoutes

Configures the location and mode of offline demo routes. Offline demo routes are prerecorded routes that Kanzi Maps can use to provide limited routing support when there is no network access.

Offline routing is limited to those exact route queries that you made when recording the routes. Any new, even if only slightly different, routing requests fail without network connection to the Mapbox routing service.

To learn how to generate and use offline tiles, see Using offline routes.

Attributes	folder The directory where the demo route files are stored. mode The operation mode: enabled enables offline routes in read-only mode. This is the normal offline demo mode. record enables recording routes when online and using routes when offline. disabled disables the offline route feature. This is the default and normal online mode.
Examples	<offlineDemoRoutes folder="mapbox_demo_routes" mode="disabled" />

Here OLP Edge settings

This section describes the configuration options for the Here OLP Edge backend.

To use the Here OLP Edge backend, in the map_settings.xml file in the backend element set:

• name="Maps.HereOLPEdgeBackend"

• filename="here_olp_edge_backend"

For example:

<backend name="Maps.HereOLPEdgeBackend" filename="here_olp_edge_backend">
    <catalog url="hrn:here:data:::here-optimized-map-for-visualization-plus-2" />
    <layer name="omv-plus-v2" />
    <login applicationKey="-- app key --"
           applicationSecret="-- app secret --"/>
    <loginRoute applicationKey="-- app key --"
                applicationSecret="-- app secret --"/>
</backend>

catalog

Sets the catalog to use to retrieve map data. The default is the HERE Optimized Map for Visualization Plus version 2 maps, which include building height information.

Attributes	url URL of the catalog from which to retrieve map data.
Examples	<catalog url="hrn:here:data:::here-optimized-map-for-visualization-plus-2" />

layer

Sets the name of the HERE layer to use from the catalog. By default Kanzi Maps uses the OMV2+.

Attributes	name The name of the HERE layer to use from the catalog. The default is HERE Optimized Map for Visualization Plus version 2.
Examples	<layer name="omv-plus-v2" />

login

Configures the login credentials to use for OMV (HERE Optimized Map for Visualization) map tile access.

The login credentials are currently not available publicly. To get access to the OMV keys, contact HERE Technologies and/or Rightware.

Attributes	applicationKey Login key. applicationSecret Application secret.
Examples	<login applicationKey="-- app key --" applicationSecret="-- app secret --"/>

loginRoute

Configures the login credentials to use for the HERE routing REST API.

To get access to the routing keys, visit https://developer.here.com/plans and apply for the appropriate plan.

Attributes	applicationKey Routing key. applicationSecret Application secret.
Examples	<loginRoute applicationKey="-- app key --" applicationSecret="-- app secret --"/>

TomTom settings

This section describes the configuration options for the TomTom backend.

To use the TomTom backend, in the map_settings.xml file in the backend element set:

• name="Maps.TomTomBackend"

• filename="tomtom_backend"

For example:

<backend name="Maps.TomTomBackend" filename="tomtom_backend">
    <login accessToken="-- access token --" />
    <diskCache maxFileCount="9000" maxDiskUsageKb="65536" disableEviction="false" />
</backend>

login

Configures the login credentials required by TomTom services. The backend uses the TomTom vector and raster tiles, routing, and geocoding services.

To register and receive a TomTom authentication token, visit https://developer.tomtom.com/.

Attributes	accessToken Access token.
Examples	<login accessToken="-- access token --" />

diskCache

Configures the TomTom-specific on-disk tile cache.

To reduce the amount of tile fetches and related API calls over the network, TomTom caches tile content to disk.

When you disable cache eviction by setting disableEviction="true", the maxFileCount and maxDiskUsageKb have no effect, the backend does not remove cached tiles from disk, and the cache can grow without limits.

Attributes

maxFileCount Maximum number of files allowed in cache when cache eviction is enabled. maxDiskUsageKb Total maximum size of cached tiles on disk in kilobytes when cache eviction is enabled. disableEviction Whether cache eviction is disabled. By default cache eviction is enabled (disableEviction="false"). When you disable cache eviction, the maxFileCount and maxDiskUsageKb attributes have no effect.

Examples

<diskCache maxFileCount="9000" maxDiskUsageKb="65536" disableEviction="false" />

See also

Using offline maps in demos