Navigation SDK - Android

Navigation SDK provides a comprehensive toolkit for integrating basic & advanced navigation capabilities into your Android applications. Whether you're developing a mobile navigation app, a fleet management solution, or a location-based service, our SDK offers the tools you need to deliver seamless and reliable navigation experiences to your users. With the Navigation SDK, you can access a wide range of features, including real-time turn-by-turn navigation, route planning, traffic-aware routing, and waypoint addition. Our SDK is designed to be easy to integrate, allowing you to focus on building compelling navigation experiences without the complexity of managing underlying navigation logic.

Purpose

The primary purpose of the Ola-Maps-Navigation SDK is to enable developers to integrate mapping, route preview and turn-by-turn navigation functionalities into their Android applications seamlessly.

Pre-Requirements for Setup

1. Version Required:
  • minSdkVersion: 21
  • Java sourceCompatibility: JavaVersion.VERSION_11
2. GPS Permission:
  • Ensure that your application has the necessary permissions to access the device's GPS.
  • GPS permission is required to load maps effectively.

Setting Up the SDK

  • 1. Download SDK:
    Obtain the OlaMapSDK.aar SDK file.
  • 2. Add SDK Dependency:
    • Place the SDK file in your project's libs directory.
    • Include the library in your project by adding the following dependencies to your app-level build.gradle file.
//OlaMap SDK
implementation(files("libs/OlaMapSdk.aar"))
//Required for OlaMap SDK
implementation "org.maplibre.gl:android-sdk:10.2.0"
implementation "org.maplibre.gl:android-sdk-directions-models:5.9.0"
implementation "org.maplibre.gl:android-sdk-services:5.9.0"
implementation "org.maplibre.gl:android-sdk-turf:5.9.0"
implementation "org.maplibre.gl:android-plugin-markerview-v9:1.0.0"
implementation "org.maplibre.gl:android-plugin-annotation-v9:1.0.0"
implementation "com.moengage:moe-android-sdk:12.6.01"
// Used in sample app
implementation "androidx.lifecycle:lifecycle-extensions:2.0.0"
implementation "androidx.lifecycle:lifecycle-compiler:2.0.0"
implementation "androidx.core:core-ktx:1.10.1"
implementation "androidx.appcompat:appcompat:1.5.1"
implementation "com.google.android.material:material:1.7.0"
implementation "androidx.constraintlayout:constraintlayout:2.1.4"
3. Define view in xml:
  • Add OlaMapView to your XML layout file.
  • We integrate the OlaMapView widget into the XML layout of your activity.
<!-- Integrate OlaMapView Widget -->
<androidx.constraintlayout.widget.ConstraintLayout android:layout_width="match_parent" android:layout_height="match_parent">
  <!-- Your existing layout code -->
  <!-- Add OlaMapView -->
  <com.ola.maps.navigation.v5.navigation.OlaMapView android:id="@+id/olaMapView" android:layout_width="match_parent" android:layout_height="match_parent" />
</androidx.constraintlayout.widget.ConstraintLayout>
4. Map view initialization:
  • Obtain an instance of OlaMapView using binding or findViewById.
  • Implement MapStatusCallback listener in your Activity.
  • Initialize the OlaMaps Navigation SDK using your custom configuration via the initialize() method of OlaMapView.
  • Override the onMapReady() method to define actions to be performed when the map is ready.
  • Upon receiving the OnMapReady callback, the Ola-Map is loaded, and further functionalities can be utilized.
// Implement MapStatusCallback Interface
class MainActivity : AppCompatActivity(), MapStatusCallback {
    var isMapReady = false
    override fun onCreate(savedInstanceState: Bundle?) {
        //Your existing code 
        //call onCreate function of OlaMapView after layout initialize
        olaMapView?.onCreate(savedInstanceState)
        //call initialize function of OlaMapView with custom configuration
        olaMapView?.initialize(
            mapStatusCallback = this,
            olaMapsConfig = OlaMapsConfig.Builder()
                .setApplicationContext(applicationContext) //pass the application context here, it is mandatory
                .setMapBaseUrl("<Base-Url>") // pass the Base URL of Ola-Maps here (Stage/Prod URL), it is mandatory
                .setApiKey("<API_KEY>")
                .setProjectId("Orgination-ID") //Pass the Origination ID here, it is mandatory
                .setMapTileStyle(MapTileStyle.DEFAULT_LIGHT_STANDARD) //pass the MapTileStyle here, it is Optional.
                .setMinZoomLevel(3.0)
                .setMaxZoomLevel(21.0)
                .setZoomLevel(14.0)
                .build()
        )
    }

    // Override onMapReady method
    override fun onMapReady() {
        isMapReady = true
        // Implement your Ola-Maps logic here when the map is ready
    }
}

//call onStop() of SDK before removing the OlaMaps
override fun onStop() {
    super.onStop()
    olaMapView?.onStop()
}

//call onDestroy() of SDK to remove the Maps
override fun onDestroy() {
    olaMapView?.onDestroy()
    super.onDestroy()
}

Features

  1. Route Preview
  2. Riding Mode
  3. Turn-by-turn or navigation

Route Preview

Route preview offers users a comprehensive overview of multiple routes between destinations, presenting ETA, distance, and potential traffic conditions. This allows users to compare and select the most optimal route tailored to their preferences, ensuring a smooth and efficient journey.

  1. API Call:
    • Call the route direction API to obtain route information.
  2. Transformation:
    • Transform the API response route data into the SDK's DirectionsRoute class asynchronously.
  3. NavigationMapRoute:
    • Create an instance of NavigationMapRoute using getNavigationMapRoute() method.
  4. Route Display:
    • Use addRoutesForRoutePreview() method of NavigationMapRoute to display the routes.
  5. Route Removal:
    • To remove route preview, call removeRoute() method.
  6. Marker Removal:
    • Remove all markers using removeAllMarkers() method.
Render the routes on the map(with traffic):
  • Transform Route Data, Create an instance of NavigationMapRoute, and addRoutesForRoutePreview() method to display the routes.
  • To enable the feature you have to follow the below code snippet.

import com.ola.maps.navigation.v5.navigation.direction.transform

// initialize this variable after onMapReady callback
val navigationRoute = isMapReady ?: olaMapView?.getNavigationMapRoute() : null
val directionsRouteList = arrayListOf<DirectionsRoute>()
// For asynchronous call we can plan for coroutines or any other async call
lifecycleScope.launch(Dispatchers.IO) {
    directionsRouteList.add(transform(routeInfoData))
}
// Once we get the transformed response from SDK, we can call addRoutesForRoutePreview method to show the routes
navigationRoute?.addRoutesForRoutePreview(directionsRouteList)
Show ETA view:
  • To Show the ETA in your route you have to add the below style in your xml OlaMapView Widget.
<style name="NavigationMapRoute">
  <item name="enableSoftTurnArrowState">true</item>
  <item name="showTimeMarkerView">true</item>
  <item name="originWaypointIcon">@drawable/ic_route_icon_empty</item>
</style>
<com.ola.maps.navigation.v5.navigation.OlaMapView
  android:id="@+id/map_view"
  style="@style /NavigationMapRoute;"
  android:layout_width="0dp"
  android:layout_height="0dp"
  app:layout_constraintBottom_toBottomOf="parent"
  app:layout_constraintEnd_toEndOf="parent"
  app:layout_constraintStart_toStartOf="parent"
  app:layout_constraintTop_toTopOf="parent"
  app:navigationDarkTheme="@style/NavigationViewDark"
  app:navigationLightTheme="@style/NavigationViewLight"
/>
Customization of the route line, markers:
  • You can customize the line width, different traffic signal colors, line shield color of your RouteLines in your .style file.
<item name="routeSevereCongestionColor">@color/mapbox_navigation_route_layer_congestion_red</item>
<item name="routeShieldColor">@color/mapbox_navigation_route_shield_layer_color</item>
<item name="routeShieldLowColor">@color/mapbox_navigation_route_shield_low_color</item>
<item name="routeShieldModerateColor">@color/mapbox_navigation_route_shield_moderate_color</item>
<item name="routeShieldHeavyColor">@color/mapbox_navigation_route_shield_heavy_color</item>
<item name="routeShieldJamColor">@color/mapbox_navigation_route_shield_jam
Remove Route Preview and All Markers: 
// Remove Route Preview
navigationRoute?.removeRoute()
// Remove All Markers
olaMapView?.removeAllMarkers()

Riding Mode

Bike/car Mode:
  • By Default the mode is Bike/Car Mode (so no need to write extra code).
Walk Mode:
  • To set up the NavigationMapRoute for walking navigation , you can use the setWalkingProfile(true) method. This method enables the walking profile.
<NavigationMapRoute>.setWalkingProfile(false)

Turn-by-turn or navigation

    Turn-By-Turn navigation provides users with step-by-step guidance throughout their journey, offering clear and concise directions at each intersection or maneuver point. This feature ensures users stay on track by indicating upcoming turns, lane changes, and points of interest along the way, enhancing navigation accuracy and convenience for a seamless travel experience.
  1. Initialization:
    • Ensure that the route API response is transformed intoDirectionsRoutedata.
  2. Listener Implementation:
    • ImplementNavigationStatusCallback and RouteProgressListener.
  3. Listener Registration:
    • Register listeners using addRouteProgressListener() and registerNavigationStatusCallback()methods.
  4. NavigationViewOptions:
    • Create an instance of NavigationViewOptions using getNavigationViewOptions(directionsRoute) method.
  5. Start Navigation:
    • Initiate turn-by-turn navigation using startNavigation(NavigationViewOptions) method.
  6. Route Removal:
    • To remove routes, call removeRoute() method.
  7. Listener Removal:
    • Remove listeners using removeListeners() method.
  8. Marker Removal:
    • Remove all markers using removeAllMarkers() method.
Render route:
  • Transform Route Data, Create an instance of NavigationMapRoute, and addRoutesForRoutePreview() method to display the routes.
import com.ola.maps.navigation.v5.navigation.direction.transform
// initialize this variable after onMapReady callback
val navigationRoute = isMapReady ?: olaMapView?.getNavigationMapRoute() : null 
var directionsRoute : DirectionsRoute = null
// For asynchronous call we can plan for coroutines or any other async call
   lifecycleScope.launch(Dispatchers.IO) {
   directionsRoute = transform(routeInfoData)
}
// Once we get the transformed response from SDK, we can get the NavigationViewOptions instance
val navigationViewOptions = getNavigationViewOptions(directionsRoute)
// Register the listener and start the Navigation for Turn-by-Turn Mode
if (navigationViewOptions != null) {
    olaMapView?.addRouteProgressListener(this@MainActivity)
    olaMapView?.registerNavigationStatusCallback(this@MainActivity)
    olaMapView?.startNavigation(navigationViewOptions)
}
Remove Turn-By-Turn, Route and All Markers:
// Remove Route Preview
navigationRoute?.removeRoute()
// Remove Turn-By-Turn Listeners
olaMapView?.removeListeners()
// Remove All Markers
olaMapView?.removeAllMarkers()
Notify route progress changes:
  • Implement RouteProgressListener to get the turn-by-turn instructions.
import com.ola.maps.navigation.v5.navigation.listeners.NavigationStatusCallback
import com.ola.maps.navigation.v5.navigation.listeners.RouteProgressListener

    override fun onRouteProgressChange(instructionModel: InstructionModel?) {
        instructionModel?.let { it ->
            val distance = it.currentInstructionModel.getDistance()
            val imageType = it.currentInstructionModel.getImageType()
            val updatedInstructionText = it.currentInstructionModel.getTextInstruction()
        }
    }
    override fun onOffRoute(location: Location?) {
    //Need to call Route-API again for Re-Route state with current location  and destination as getting from onOffRoute      
         val routeInfoData: RouteInfoData = get from the response of Route-API
        val directionsRoute = transform(routeInfoData) // transform should be called asynchronously
        olaMapView?.updateNavigation(directionsRoute)
    }
    override fun onArrival() {
        // Show UI of once User is reached at destination
    }
Dynamic zoom level:
  • OlaMaps handles the dynamic zoom level while navigating. It automatically zooms in and out and rotates the map according to the turns and road.
Voice navigation:
  • This feature helps users to listen to the route instruction in voice.
  • To enable voice instructions in the NavigationMapRoute, you can use the OlaMapView.setVoiceInstructionEnabled(true) method. This method activates voice guidance, providing audio cues during navigation.