# 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:

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

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

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

```bash
import Nbmap
```

Regional Offline Maps APIs are available in `Nbmap` version `2.3.2` 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:

```swift
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:

```swift
import Nbmap
NGLRegionalOffline.configure()
```

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

```swift
let config = NGLRegionalOfflineConfig.fromCurrentTileServer()
NGLRegionalOffline.configure(with: config)
```

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

```swift
NGLRegionalOffline.configure(
    withMapsBaseUrl: "https://example.com/maps"
)
```

_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:

```swift
NGLAccountManager.useWellKnownTileServer(NGLTomTom)
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.