# Getting Started

This page prepares the app to use Offline Maps by adding the SDK, confirming permissions/storage behavior, selecting the supported offline tile data source, and initializing _RegionalOffline_ before building the download experience.

## Install the SDK

Regional Offline Maps is an SDK service that manages offline map data across the application. It provides all the APIs to configure offline maps, download map packages, and enable the standard `MapView` which reads the installed data when network connectivity is unavailable. _RegionalOffline_ is included in the `nb-maps` AAR and does not require a separate offline artifact.

Integrate the release version using the Maps SDK repository and credential configuration:

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}
dependencies {
    implementation("ai.nextbillion:nb-maps-android:3.2.0")

    // The Kotlin Flow examples in this guide use the following Lifecycle extension.

implementation("androidx.lifecycle:lifecycle-runtime-ktx:<lifecycle-version>")
}
```

**Note:** If your app also uses the Navigation SDK, make sure the Maps SDK version used by Offline Maps matches the Maps SDK version required by your Navigation SDK release.

> _The Offline Maps APIs are included in the Maps SDK. If you use the Kotlin Flow examples in this guide, also add the_ **AndroidX Lifecycle runtime KTX dependency** _to collect flows safely within the_ `Activity` _or_ `Fragment` _lifecycle._

## Permissions and Storage

The SDK AAR already declares the base permissions for `INTERNET` and `ACCESS_NETWORK_STATE`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

The application does not need to declare them again after manifest merging. By default, offline data is written to _FileSource_'s app-specific resource directory and does not require shared-storage permission. Uninstalling the application, clearing application data, or explicitly deleting or moving this resource directory removes the offline data.

## Tile Server Requirements

Initialize Nextbillion and select the tile server before initializing Offline Maps:

```kotlin
import ai.nextbillion.maps.Nextbillion
import ai.nextbillion.maps.style.NGLWellKnownTileServer

Nextbillion.getInstance(
    applicationContext,
    BuildConfig.NEXTBILLION_API_KEY
)
```

Regional Offline currently supports only `NGLTomTom`:

| Tile server | Regional Offline data source |
| --- | --- |
| _NGLWellKnownTileServer.NGLTomTom_ | `OfflineDataSource.TOMTOM`, id 1 |

_NGLWellKnownTileServer.NGLMapTiler_ can be used normally for online maps, but it cannot initialize, download, manage, or display Offline Maps. Check _RegionalOffline.supportStatus()_ before showing the offline entry point. If it returns `TOMTOM_REQUIRED`, disable the entry point and prompt the user to switch to `NGLTomTom`.

## Initialize Regional Offline Maps

_RegionalOffline_ is the process-level entry point. The SDK maintains a single download-management instance internally, so the application does not need to create, retain, or release an additional client.

```kotlin
import ai.nextbillion.maps.Nextbillion
import ai.nextbillion.maps.regionaloffline.release.client.RegionalOffline
import ai.nextbillion.maps.regionaloffline.release.client.RegionalOfflineSupportStatus
import ai.nextbillion.maps.style.NGLWellKnownTileServer
import android.app.Application
import android.util.Log

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        Nextbillion.getInstance(
            this,
            BuildConfig.NEXTBILLION_API_KEY,
            NGLWellKnownTileServer.NGLTomTom,
        )

        when (RegionalOffline.supportStatus()) {
            RegionalOfflineSupportStatus.SUPPORTED -> {
                if (!RegionalOffline.initialize(this)) {
                    Log.e("App", "Regional Offline initialization failed")
                }
            }
            RegionalOfflineSupportStatus.TOMTOM_REQUIRED ->
                Log.w("App", "Regional Offline requires NGLTomTom")
            RegionalOfflineSupportStatus.NEXTBILLION_NOT_INITIALIZED ->
                Log.e("App", "Initialize Nextbillion before Regional Offline")
        }
    }
}
```

To register `Application` in the manifest, use:

```xml
<application
    android:name=".App"
    ... />
```

`initialize()` is thread-safe and idempotent. Repeated calls with the same CDN configuration return “true”. A different CDN configuration returns `false` and does not replace the running instance. It also returns `false` when the current tile server or the explicit _RegionalOfflineConfig.dataSource_ is not TomTom. Calling _RegionalOffline.initialize()_ is not required when the application only displays previously downloaded TomTom maps.

## Custom CDN (Optional)

Most applications should use the default SDK endpoint. Configure a custom CDN only when you have deployed a complete region catalog, package set, and preview bundle matching the SDK version.

```kotlin
RegionalOffline.initialize(
    this,
    mapsBaseUrl = "https://your-cdn.example.com/path/maps",
)
```