Navigation SDK - iOS

Navigation SDK provides a comprehensive toolkit for integrating basic & advanced navigation capabilities into your iOS 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.

Specifications

Before proceeding, ensure that you meet the following prerequisites:

Minimum iOS version: iOS 13.0
Xcode Version: 12 or later

Sample App

Please refer to theGithub Sample Appfor getting better clarity on same.

Setup Map

You have to download OlaNavigation SDK and import all the xcframeworks in your iOS project. Make sure you embed all the frameworks in General > Frameworks, Libraries and Embedded Content. Next, You need to add Location Permission Authorization in your Info.plist file,

<key>NSLocationWhenInUseUsageDescription</key>
<string>App wants to access your location</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>App wants to access your location</string>

Now, you are good to initialize the OlaMapService,

import OlaMapNavigation

// Default Initialization
let olaMapService = OlaMapService(
    auth: .apiKey(key: "API-KEY-FROM-PLATFORM-DASHBOARD"),
    tileURL: "TILE-URL",
    projectId: "PROJECT-ID-FROM-PLATFORM-DASHBOARD"
)

// Or, Initialize Service as per your need
let olaMapService = OlaMapService(
    auth: .apiKey(key: "API-KEY-FROM-PLATFORM-DASHBOARD"),
    tileURL: "TILE-URL",
    projectId: "PROJECT-ID-FROM-PLATFORM-DASHBOARD",
    userId: nil
)
)

Parameter name	Description
apikey	API Key from Platform Dashboard
tileURL	Refer Tiles API in API Reference
projectId	Refer Dashboard for Project Identifier
userId	Custom UserID which is identified by Organization

Load the map using the service instance. Ideally this method should be called in viewdidLoad() method of viewcontroller

override func viewDidLoad() {
    super.viewDidLoad()
    
    olaMapService.loadMap(onView: self.view)
    olaMapService.addCurrentLocationButton(self.view)
    olaMapService.setCurrentLocationMarkerColor(UIColor.systemBlue)
    olaMapService.setRotatingGesture(true)
    olaMapService.recenterMap()
    olaMapService.delegate = self
    olaMapService.setMaxZoomLevel(16.0)
}

Annotation

To draw an annotation, we need to call setAnnotationMarker with coordinate and Annotation View. Make sure, you have unique Identifier for every nnotation you have on map.

private lazy var bikeAnnotationView: OlaAnnotationView = {
    let annotationView =  CustomAnnotationView(identifier: "destination-marker", image: UIImage(named: "img_bike"))
        annotationView.bounds = CGRect(x: 0, y: 0, width: 50, height: 50)
        return annotationView
}()

Add Annotation

If you want to show the annoattion on the map you can use CustomAnnotationView andsetAnnotationMarker

// Draw Annotation
self.olaMap.setAnnotationMarker(at: self.coordinate, annotationView: self.bikeAnnotationView, identifier: self.bikeAnnotationView.reuseIdentifier ?? "NA")
self.olaMap.setCamera(self.coordinate.getCLCoordinate2D())

Remove Annotation

You can remove a marker from the map by calling this method removeAnnotation.

self.olaMap.removeAnnotation(by: "annotation-id")

Polygons

Polygons are designed to define solid regions within a closed loop which can be used to mark a particular zone. They consist of a series of coordinates in an ordered sequence.

You can draw Polygons by calling this method drawPolygon(), here is the example below:

let coordinates: [OlaCoordinate] = [
    OlaCoordinate(latitude: 12.9320745, longitude: 77.6137873),
    OlaCoordinate(latitude: 12.931336, longitude: 77.6141494),
    OlaCoordinate(latitude: 12.9308027, longitude: 77.6167565),
    OlaCoordinate(latitude: 12.9317333, longitude: 77.6170891),
    OlaCoordinate(latitude: 12.9322679, longitude: 77.6142218),
    OlaCoordinate(latitude: 12.9320745, longitude: 77.6137873),
]
let strokeColor: UIColor = .black
let strokeWidth: CGFloat = 2
let zoneColor: UIColor = .gray

olaMapService.drawPolygon(identifier: "polygon", coordinates, zoneColor: zoneColor, strokeColor: strokeColor, storkeWidth: strokeWidth)

To draw circle call this method drawCircle(), here is the example below:

let strokeColor: UIColor = .black
let strokeWidth: CGFloat = 2
let zoneColor: UIColor = .gray
let coordinate = OlaCoordinate(latitude: 12.931336, longitude: 77.6141494)

let radius = 30
olaMapService.drawCircle(id: "circle_id", centerCoordinate: coordinate, radius: radius, strokeColor: strokeColor, zoneColor: zoneColor, strokeWidth: strokeWidth)

Polyline

Polylines allow you to draw lines on the map. The below example demonstrates how to draw a polyline.

let polylineSetOlaToKormangla: [OlaCoordinate] = [
    OlaCoordinate(latitude: 12.93177, longitude: 77.616370000000003),
    OlaCoordinate(latitude: 12.93168, longitude: 77.616870000000006),
    OlaCoordinate(latitude: 12.931610000000001, longitude: 77.616900000000001),
    OlaCoordinate(latitude: 12.931000000000001, longitude: 77.616770000000002),
    OlaCoordinate(latitude: 12.93097, longitude: 77.616709999999997),
    OlaCoordinate(latitude: 12.931480000000001, longitude: 77.614249999999998),
    OlaCoordinate(latitude: 12.93075, longitude: 77.614389999999986),
    OlaCoordinate(latitude: 12.93022, longitude: 77.61472999999998),
    OlaCoordinate(latitude: 12.92999, longitude: 77.614869999999982),
    OlaCoordinate(latitude: 12.929869999999999, longitude: 77.614949999999979),
    OlaCoordinate(latitude: 12.92981, longitude: 77.615049999999982),
    OlaCoordinate(latitude: 12.92975, longitude: 77.615239999999985),
]

self.olaMap.showPolyline(identifier: "polyline-id", .solid, self.polylineSetOlaToKormangla, .darkGray)

Listening to events

We can listen to 2 types of event

Longpress event
Tap event
MapRegion changed event

Tap and Longpress Events

To listen to events, you must implement the OlaMapServiceDelegate protocol. Typically, you implement this protocol on the view controller that displays the map. Below is an example:

override  func  viewDidLoad() {
    super.viewDidLoad()
    
    olaMapservice.loadMap(self.view)
    olaMapservice.delegate = self
}

// MARK: OlaMapServiceDelegate

public  func  didTapOnMap(_ coordinate: OlaCoordinate){
    let tapCoordinate = coordinate.getCLCoordinate2D()
    print("You tapped at (tapCoordinate.latitude), (tapCoordinate.longitude)")
}

public  func  didLongTapOnMap(_ coordinate: OlaCoordinate) {
    let tapCoordinate = coordinate.getCLCoordinate2D()
    print("You long pressed at (tapCoordinate.latitude), (tapCoordinate.longitude)")
}

Map Region changed Events

Using the OlaMapServiceDelegate, you can listen when map region changes. Gesture param with it signifies the reason for change

func  mapViewDidChange(gesture: OlaMapGesture) {  
    // To get the center coordinates of the map this is the optional coordinate  
    let coordinate = olaMapService.centerCoordinateOfMap  
}
    
func  mapViewDidBecomeIdle() {  
    // To get the center coordinates of the map this is the optional coordinate  
    let coordinate = olaMapService.centerCoordinateOfMap  
}

Navigation

Enhance your mobile app with seamless, turn-by-turn navigation. Harness the capabilities of Ola Maps to deliver real-time navigation with intuitive voice guidance. You can instantiate navigation service as follows

lazy var navigationService: OlaMapNavigationService = {
      let navigationService =  OlaMapNavigationService(
        auth: .apiKey(key: "API-KEY-FROM-PLATFORM-DASHBOARD"), 
        tileURL: "TILE-URL", 
        projectId: "PROJECT-ID-FROM-PLATFORM-DASHBOARD"
      )
      navigationService.setDebugLogs(true)
      navigationService.isCompassViewHidden = false
      navigationService.compassViewMargins = CGPoint(x: 20, y: 500)
      return navigationService
}()

Parameter name	Description
apikey	API Key from Platform Dashboard
tileURL	Refer Tiles API in API Reference
projectId	Refer Dashboard for Project Identifier
userId	Custom UserID which is identified by Organization

Route Data

To enable navigation, you must supply route data to the navigation service. This data can be obtained from the Direction Service.

Please refer to theAPI documentationfor further details.

Navigation Features

Manage Navigation
Navigation callbacks
Instructions

Manage Navigation

Start Navigation

Once Route data is fetched from above section, we can call navigate()api on navigation service to display route and start navigation using following code snippet

self.navigationService.navigate(
      jsonData: jsonData, 
      origin: <Origin_Coordinate>, 
      destination: <Destination_Coordinate>, 
      mode: .driving
    ) { state in
      switch state {
      case .success(vc: let navigationVC):
        // Embed navigationVC in your viewController
      case .failed(let error):
          print("Error : (error.message)")                    
      }
}

End Navigation

Once navigation has been started it can be terminated any time using following api

self.navigationService.endNavigation()

Navigation callbacks

You can listen to navigation events using the OlaMapNavigationServiceDelegate protocol. Below is an example:

func didNavigationCompleted() {
      print("✅ Navigation Completed")
}
  
func didReroute(_ lastLocation: CLLocation) {
      // Call direction API to get new route
}
  
func regionIsChanging(_ gesture: OlaMapGesture) {
      print("ℹ️ Region is changing")
}

Instructions

Text Instructions

Once Navigation starts, user will get callbacks depending on journey progress he is making

func didUpdateVisualInstruction(_ instruction: OlaVisualInstruction) {
      // Update label with instruction to indicate next turn to your user
      print("***************  == (instruction.tertiaryInstruction)")
}

Audio Instructions

We can enable audio guide for user during journey using following api. Also Voice guidance can be programatically toggled using toggleVoiceNavigation() api

navigationService.disableDefaultVoiceNavigation = false
self.navigationService.toggleVoiceNavigation()

To get callback of when instructions has been played, implement following method from OlaMapNavigationServiceDelegate

func didUpdateAudioInstruction(_ instruction: OlaAudioInstruction) {
    // Audio instruction has been played
    print("***************  == (instruction.primaryInstruction)")
}

Dependencies

OlaMapNavigationSDK is dependent on following Dependencies

MapLibre, '5.9.0',
MoEngageAnalytics, '9.15.2',
OlaTurf, '6.5.0',
OlaMapDirections,