Preparation

Preparation to use Global iNavi Navigation SDK

To use Global iNavi Navigation SDK an APP KEY for authentication is required. For APP KEY issuance, please make a request through our business manager.

Project Environment Setup

AndroidiOS

Since the Global iNavi Navigation SDK is distributed through a separate repository, add the repository configuration and the SDK dependency to build.gradle file at both the project level and the app module level as shown below.

/* Root Project build.gradle.kts */
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://repo.inavi.com/artifactory/navigation") }
    }
}

/* App Module build.gradle */
dependencies {
    implementation 'com.inavisys.navisdk.ui:ui-android:+'
}

Recommended: Specify a Fixed Version

While the example uses + for convenience, we highly recommend specifying a fixed version number (e.g., 1.0.0) instead of the wildcard to ensure build stability. Please check the latest version in the release notes.

For iOS, add the package dependency using Swift Package Manager (SPM).

1. In Xcode, go to File > Add Package Dependencies...
2. In the 'Enter Package URL' textbox, enter the URL below
3. https://github.com/inavi-systems/Global-iNavi-Navigation-SDK

---

APP KEY Configuration

Two methods are provided below for configuring the issued APP KEY.

Warning

An authentication error will occur during initialization if the APP KEY is not configured.

AndroidiOS

Configure in AndroidManifest.xml

Add the <meta-data> tag within the <application> tag.

<meta-data
    android:name="com.inavi.navisdk.appkey"
    android:value="YOUR_APP_KEY" />

Configure in Info.plist

Add the iNaviAppKey key to your project's Info.plist file and set your App Key as the value.

<key>iNaviAppKey</key>
<string>YOUR_APP_KEY</string>

---

Permissions & Capabilities

The SDK automatically requests necessary permissions during initialization.

AndroidiOS

Ensure your AndroidManifest.xml includes location permissions:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

1. Background Modes : To ensure navigation continues while the app is in the background, enable Background Modes in Xcode.

   1. Go to Project Targets > Signing & Capabilities.
   2. Click + Capability and select Background Modes.
   3. Check the following options:
      • Location updates: To track vehicle position in the background.
      • Audio, AirPlay, and Picture in Picture: To play voice guidance instructions in the background.

2. Permissions : Ensure your Info.plist includes location usage description:

   <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
   <string>This app requires location access for navigation.</string>
   <key>NSLocationUsageDescription</key>
   <string>This app requires location access for navigation.</string>
   <key>NSLocationWhenInUseUsageDescription</key>
   <string>This app requires location access for navigation.</string>
   

---

Initialization

Initialization is the process of loading map data and authenticating the SDK to make it ready for use. The initialization process is performed asynchronously, and the result is delivered via a callback listener.

AndroidiOS

Call NaviController.initalizeNavi() passing the Activity context and an implementation of OnNaviInitializeListener.

NaviController.initalizeNavi(this, object : OnNaviInitializeListener {
    override fun onMapReady(orbisMapFragment: Any?) {
        // 1. Map Ready: SDK is ready to display the map
        // IMPORTANT: You must manually add the Fragment to your container
        (orbisMapFragment as? Fragment)?.let { fragment ->
            supportFragmentManager.beginTransaction()
                .replace(R.id.map_container, fragment)
                .commit()
        }
    }

    override fun onInitSuccess() {
        // 2. Initialization Success: All SDK features are now available
        // You can now use search, routing, navigation, etc.
        Log.d(TAG, "SDK initialization completed successfully")
    }

    override fun onInitFail(errorCode: Int, errorMsg: String) {
        // 3. Initialization Fail: An error occurred during initialization
        // Common errors: Invalid APP KEY, network failure, permission denied
        Log.e(TAG, "SDK initialization failed: [$errorCode] $errorMsg")
        // Handle error (show message to user, retry, etc.)
    }
})

Call InaviController.shared.naviInitialize() passing the UIViewController, the UIView (map container), and a completion closure.

import iNaviNavigationSdk

// In your UIViewController
@IBOutlet weak var mapContainer: UIView!

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)

    InaviController.shared.naviInitialize(
        viewController: self,
        mapContainer: mapContainer
    ) { status in
        switch status {
        case .onMapReady(let mapView):
            // Map Ready
            // The SDK has attached the map view to mapContainer.
            break

        case .success:
            // Initialization Success
            print("Init Success")
            break

        case .fail(let errorMsg):
            // Initialization Fail
            print("Init Failed: \(errorMsg)")
            break

        @unknown default:
            fatalError("Unknown status")
        }
    }
}

Step-by-Step Initialization

1. onMapReady / .onMapReady
   • Android: This callback is called when the SDK is ready to display the map. You must manually use FragmentManager to add the map Fragment.
   • iOS: Called when the map view is created and attached to the container.

Common Failure Scenarios:

• Invalid or missing APP KEY: The APP KEY is not configured or is incorrect
• Network connection failure: Unable to connect to the server for authentication or map download
• Permission denied: User denied required permissions (location)
• Map data download failure: Unable to download necessary map data

Recommended Actions:

• Display an error message to the user with the errorMsg
• For network errors, offer a retry option
• For permission errors, guide the user to grant permissions in settings
• For APP KEY errors, verify the configuration and contact support

---

See More

For detailed API documentation, see: initalizeNavi(Android), initalizeNavi(iOS)