HERE SDK for iOS (Premium Edition)

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.
NMAFTCRNavigationManager A navigation manager class that provides guidance advice and information along the FTCR routes.
NMAMapFTCRRoute Represents a NMAFTCRRoute that can be displayed on a Map.
NMAFTCRLaneInformation Represents information about lane information on the NMAFTCRManeuver.
NMAFTCRManeuver Represents information about maneuver on the 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];
  // see API reference to check all possible routing options
  plan.options.transportMode = NMAFTCRTransportModeCar;
  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: it does not support voice guidance, map matcher is only based on route geometry from the online server response and re-routing is only available in online mode. 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
{ }