Configure map data storage

The SDK uses two storage areas on the device to hold map content: an on-device cache holding prefetched online map data (the “online cache” for short) and, if you enabled it, an onboard region store. This guide shows how to choose where each one lives and what you should consider when placing them.

After reading this guide you will know which directories the SDK writes to, which of them you can control from public API, and how the online cache relates to the runtime caching behavior described in Caching Strategy (the onboard region store is not covered there).

For the complete buildSdkConfiguration snippet that uses these settings, follow the Map data quickstart.

The two storage areas

Online cache

Holds online tiles prefetched along the current route and around the user’s current position; see Caching Strategy for what tiles are and how prefetching works. This is what keeps the SDK running when connectivity drops. Configured via the cacheStorageConfiguration { …​ } lambda block of buildSdkConfiguration, which exposes a CacheStorageConfiguration.Builder. Setting it is optional — a sensible default location is used otherwise.

Onboard region store

Holds the NDS map regions installed on the device. Present only when a regionStorePath is passed to buildSdkConfiguration. Configured via the regionStorePath argument and the regionStoreConfiguration { …​ } lambda block, which exposes a RegionStoreConfiguration.Builder. See Manage onboard regions for installing and updating the regions it holds.

Configuring the locations

Configuring the locations of both areas looks like this:

1
val sdkConfig = buildSdkConfiguration(
2
    context = context,
3
    apiKey = apiKey,
4
    regionStorePath = File(context.filesDir, "region-store"),
5
    telemetryUserConsent = { UserConsent.TelemetryOn },
6
    cacheStorageConfiguration = {
7
        directoryPath = File(context.filesDir, "online-cache")
8
    },
9
    regionStoreConfiguration = {
10
        keyStorePath = File(context.filesDir, "keystore")
11
        updateStoragePath = File(context.filesDir, "region-updates")
12
    },
13
)

The individual settings are described below.

Online cache location

CacheStorageConfiguration.directoryPath is the only setting for the online cache, and it is optional: by default the SDK uses a cache directory inside the application’s filesDir. For most apps the default is the right choice.

If you point it elsewhere, the path must be absolute and writable by the application. A location under context.cacheDir, for example, lets Android reclaim the space when the device runs low on storage — the SDK rebuilds the cache on demand, at the cost of fresh downloads.

The size of the online cache, the prefetched corridor, and the eviction policy are SDK-managed. See Caching Strategy for the runtime behavior they enforce.

Onboard region store location

The onboard region store is configured in three parts:

• regionStorePath (required if the onboard map is to be used as a map data source) — the directory that contains the NDS region store (the directory holding the ROOT.NDS file). This is the same directory you ship or download the onboard map into.
• keyStorePath and keyStorePassword (optional) — the location and password of the keystore that authorizes access to the region store. If your provisioning provides a keystore, point keyStorePath at the keystore file itself; its parent directory must be writable. If your keystore is unprotected, leave keyStorePassword unset.
• updateStoragePath (optional) — a directory used for staging downloaded update packages before they are applied to the region store. Defaults to a directory named updates inside the application’s filesDir, which the SDK creates if it does not exist yet. It must not be the same directory as regionStorePath, and neither may be nested inside the other.

All three must be absolute paths. The region store directory is the one shipped in your setup package — the SDK reads it, it does not create it.

Choosing the right filesystem

Internal storage (under context.filesDir)

The default and the recommended location for both the online cache and the onboard region store. It is private to the app, requires no special permissions, and avoids the FUSE performance penalty described below.

External or removable storage

Use only if your app needs to share map data with other apps or to pre-load a large region store from an SD card. Two things to be aware of:

• Permissions — adjust your application to request the necessary permissions for accessing external storage. See the Android Developer Guide on Permissions and access to external storage.
• Filesystem in Userspace (FUSE) — Android 11 and higher default to FUSE for SD cards. FUSE significantly degrades performance for large NDS files and can cause stalls in map rendering and SDK operation. See the Android Developer Guide on Mitigating FUSE Performance.

Cache freshness and eviction

Cache size, freshness, and eviction are managed by the SDK and are not configurable; see Caching Strategy for how they work at runtime. The onboard region store is not evicted by the SDK: you control its contents by which regions you ship or download (see Manage onboard regions).

Next steps