SDK for iOS Developer's Guide

Fleet Telematics Custom Routes

Fleet Telematics Custom Routes (FTCR) API provides functionality to calculate a route, show it on map and perform simple turn-by-turn navigation using HERE map data and customers' private map data. FTCR API is similar to common routing and navigation, but it offers limited functionality compare to them. For more information about use cases that can be covered by FTCR, check Fleet Telematics Custom Routes API Developer's Guide.

FTCR Classes

Class	Description
`NMAFTCRRouter`	Route calculation executor for Fleet Telematics Custom Route.
`NMAFTCRRoutePlan`	Contains all information needed to calculate the ftcr route.
`NMAFTCRRouteOptions`	Contains options for ftcr route calculation.
`NMAFTCRRoute`	Represents a distinct Fleet Telematics custom path connecting two or more waypoints.
`NMAMapFTCRRoute`	Represents a `NMAFTCRRoute` that can be displayed on a `Map`.
`NMAFTCRNavigationManager`	A navigation manager class that provides guidance advice and information along the FTCR routes.
`NMAFTCRLaneInformation`	Represents information about lane information on the `NMAFTCRManeuver`.
`NMAFTCRManeuver`	Represents information about maneuver on the `NMAFTCRRoute`.
`NMAFTCRRouteWarning`	Describes warning for `NMAFTCRRoute`.

FTCR route calculation

Steps to calculate NMAFTCRRoute are the same as for common routing. Use classes from ftcr directory: NMAFTCRRouter, NMAFTCRRoutePlan and NMAFTCRRouteOptions to calculate a route. Note, that route calculation only works in online mode. See example to calculate FTCR route below:

- (void)calculateRoute
{
  // waypoints setup
  NMAGeoCoordinates* startGeo = [[NMAGeoCoordinates alloc] initWithLatitude:52.514184 longitude:13.316419];
  NMAGeoCoordinates* destinationGeo = [[NMAGeoCoordinates alloc] initWithLatitude:52.512272 longitude:13.383096];
  NMAWaypoint* start = [[NMAWaypoint alloc] initWithGeoCoordinates: startGeo];
  NMAWaypoint* destination = [[NMAWaypoint alloc] initWithGeoCoordinates: destinationGeo];

  // fleet telematics options
  NMAFTCRRoutePlan *plan = [[NMAFTCRRoutePlan alloc] initWithWaypoints:@[start, destination]];
  // set overlay name if needed
  plan.overlay = @"OVERLAYNAME";
  plan.options = [[NMAFTCRRouteOptions alloc] init];
  // other transport modes such as Truck, Pedestrian, Scooter, Bike and Bus are also supported.
  plan.options.transportMode = NMAFTCRTransportModeCar;
  // see API reference to check all possible routing options
  plan.options.routingType = NMAFTCRRoutingTypeFastest;
  NMAGeoCoordinates* topLeft = [[NMAGeoCoordinates alloc] initWithLatitude:52.521842 longitude:13.375375];
  NMAGeoCoordinates* bottomRight = [[NMAGeoCoordinates alloc] initWithLatitude:52.518212 longitude:13.380335];
  [plan.options addAvoidArea:[[NMAGeoBoundingBox alloc] initWithTopLeft:topLeft
                                bottomRight:bottomRight]];

  _router = [[NMAFTCRRouter alloc] init];
  [_router calculateRouteWithPlan:plan
          completionBlock:^(NSArray<NMAFTCRRoute *> *routes, NSError *error) {
    if (!error && routes && routes.count > 0) {
      [self startNavigationWithRoute:[routes firstObject]];
    }
  }];
}

FTCR turn-by-turn guidance

NMAFTCRNavigationManager allows developer to perform simple turn-by-turn guidance along the route. It is possible to simulate the route as well as navigate route using custom LocationDataSource in PositioningManager. Note, FTCR navigation has limited functionality compare to NavigationManager: map matcher is only based on route geometry from the online server response, re-routing is only available in online mode and some navigation events like speed warning are not suported. See example to start FTCR navigation below:

- (void)startNavigationWithRoute:(NMAFTCRRoute *)route
{
  // add route to the map
  _ftcrCurrentRoute = [[NMAMapFTCRRoute alloc] initWithRoute:route];
  [_activeMapView addMapObject:_ftcrCurrentRoute];

  // set first route coordinate as map center
  [_activeMapView setGeoCenter:[route.geometry firstObject]];

  // show indicator on the map
  _activeMapView.positionIndicator.visible = YES;

  NMAFTCRNavigationManager *ftcrNavigationManager = [NMAFTCRNavigationManager sharedNavigationManager];
  ftcrNavigationManager.map = _activeMapView;
  ftcrNavigationManager.mapTrackingMode = NMAFTCRTrackingModeFollow;
  ftcrNavigationManager.mapTrackingTilt = NMAFTCRTrackingTilt3D;
  [ftcrNavigationManager addListener:self];

  // also supports simulation and navigation using PositionSimulator
  [ftcrNavigationManager startWithRoute:route];
}

- (void)navigationManager:(nonnull NMAFTCRNavigationManager *)navigationManager
    didRerouteWithRoute:(nullable NMAFTCRRoute *)reroute
          error:(NSError* _Nullable)error
{
  // We must remove old route from the map and add new one, SDK does not do that
  // automatically
  if (!error && reroute) {
    [_activeMapView removeMapObject:_ftcrCurrentRoute];
    _ftcrCurrentRoute = [[NMAMapFTCRRoute alloc] initWithRoute:reroute];
    [_activeMapView addMapObject:_ftcrCurrentRoute];
  }
}

- (void)navigationManager:(nonnull NMAFTCRNavigationManager *)navigationManager
     hasCurrentManeuver:(nullable NMAFTCRManeuver *)maneuver
       nextManeuver:(nullable NMAFTCRManeuver *)nextManeuver
{ }


- (void)navigationManagerDidReachDestination:(nonnull NMAFTCRNavigationManager *)navigationManager
{ }

- (void)navigationManager:(nonnull NMAFTCRNavigationManager *)navigationManager
     didReachStopover:(NSInteger)stopoverIndex
{ }


- (void)navigationManagerWillReroute:(nonnull NMAFTCRNavigationManager *)navigationManager
{ }

- (void)navigationManager:(nonnull NMAFTCRNavigationManager*)navigationManager
 didUpdateLaneInformation:(nonnull NSArray<NMAFTCRLaneInformation *> *)laneInformationList
{ }