Getting Started

This guide explains how to configure NGLRegionalOffline, which is a SDK service used to configure and manage the Offline Maps runtime. It provides a unified API for configuration, regional catalog queries, map package downloads, progress monitoring, and management of installed regions, including pause, resume, cancel, and delete operations.

Install the SDK with Swift Package Manager

Regional Offline Maps support is included in the Nbmap SDK. No separate Regional Offline package or framework is required.

To add the SDK using Swift Package Manager:

In Xcode, select File > Add Package Dependencies…
Enter the following package repository URL:

1
https://github.com/nextbillion-ai/maps-native-distribution

Select Up to Next Major Version and set 2.2.0 as the minimum version.
Select the Nbmap package product and add it to the application target.
Build the project and verify that the SDK module can be imported:

1
import Nbmap

Regional Offline Maps APIs are available in Nbmap version 2.2.0 and later.

SDK Version Requirements

Regional Offline Maps are supported in Nbmap Maps SDK for iOS 2.2.0 and later. Versions earlier than 2.2.0 do not include the NGLRegionalOffline APIs or the regional offline map capabilities described in this guide.

Tile Server Requirements

Maps SDK uses TomTom tile server by default, so NGLRegionalOffline does not require an additional call to:

1
NGLAccountManager.useWellKnownTileServer(NGLTomTom)

Do not switch the tile server to NGLMapTiler or another data source. NGLRegionalOffline currently supports TomTom only. Using any other tile server causes NGLRegionalOffline APIs to reject the operation.

Configure the Offline Maps Runtime

Configure offline maps runtime ( NGLRegionalOffline ) once during application startup:

1
import Nbmap
2
NGLRegionalOffline.configure()

Use an explicit configuration when the application needs to derive NGLRegionalOffline settings from the active tile server

1
let config = NGLRegionalOfflineConfig.fromCurrentTileServer()
2
NGLRegionalOffline.configure(with: config)

Use the maps base URL overload only when the application must target a custom regional offline service:

1
NGLRegionalOffline.configure(
2
    withMapsBaseUrl: "https://example.com/maps"
3
)

configure() uses the SDK default maps base URL. Use configure(withMapsBaseUrl:) for a dedicated endpoint, or configure(with:) for a complete custom configuration. A separate install() call is not required as NGLRegionalOffline operation methods install and configure lazily when needed.

Call NGLRegionalOffline class methods directly; do not create or retain a client object.

Tile Server Switching and the TomTom Restriction

When the configuration changes through NGLAccountManager, the Regional Offline maps engine refreshes automatically. Switch back to TomTom tile server before entering the offline maps flow:

1
NGLAccountManager.useWellKnownTileServer(NGLTomTom)
2
let supported = NGLRegionalOffline.isOfflineMapSupportedForCurrentTileServer()

onTileServerChanged() remains available only for custom paths that bypass NGLAccountManager. When the active provider is unsupported, configuration logs OfflineProviderDiagnostic. The asynchronous operations return unsupportedTileServer, and synchronous data APIs return empty values without touching TomTom storage.