migration guide to 6.1.0 Android
Migration Guide to 6.1.0+
This guide assists developers in migrating from Mapsted SDK v6.0.17 to v6.1.0+.
Android Migration
We have restructured the routing and navigation features in the mobile SDK as outlined below.
Overview
The sdk version v6.1.0, includes the major Routing API changes. This document outlines the necessary steps and highlights key changes for transitioning from the old routing structures to the new ones. This update is part of our initiative to separate Routing from Navigation and to enable multiple route alternatives, offering more robust and flexible routing solutions
Key Migration Highlights
- Routing and Navigation are separated for clean usage
- Fully employed the builder pattern to create route request objects
- Separate RoutingCallback and NavigationCallback for routing and navigation respectively. These are successor for RoutingStatusCallback
- Route Error with error type and message
- Other features include multiple route paths per destination.
Migration Steps
1. Add and remove listener for the Routing and Navigation callbacks
Our callback feature (pre-v6.1.0) could only add a callback return to the request's origin, preventing dynamic routing or navigation. This limited application complexity and versatility as subsequent actions couldn't be directed based on callback events. Beginning form sdk version 6.1.0 onwards user can add callback dynamically using following code snippet-
/**
* Register listener for RoutingRequestCallback events
* @param listener object of RoutingRequestCallback to receive callbacks
* @return whether or not successful
*/
boolean addRoutingRequestListener(RoutingRequestCallback listener);
/**
* Unregister listener for RoutingRequestCallback events
* @param listener object of RoutingRequestCallback to stop callbacks
* @return whether or not successful
*/
boolean removeRoutingRequestListener(RoutingRequestCallback listener);
/**
* Register listener for NavigationCallback events
* @param listener object of NavigationCallback to receive callbacks
* @return whether or not successful
*/
boolean addNavigationListener(NavigationCallback listener);
/**
* Unregister listener for NavigationCallback events
* @param listener object of NavigationCallback to stop receiving callbacks
* @return whether or not successful
*/
boolean removeNavigationListener(NavigationCallback listener);
2. Make Route Request
Beginning form sdk version 6.1.0 onwards user can create request using following code snippet-
// Create IndoorOutdoor options
val indoorOutdoorOptions = IndoorOutdoorRouteOptions.Builder()
.setAccessibleEntrance(true)
.setPreferIndoorRoute(true)
.setPreferOutdoorRoute(true)
.setPreferIndoorRoute(true)
.setPreferOutdoorRoute(true)
.setIncludePrimaryEntrance(true)
.setIncludeSecondaryEntrance(true)
.setIncludeBuildingToBuildingEntrance(true)
.setIncludeEmergencyEntrance(true)
.setIncludeRestrictedEntrance(true)
.build()
// Create Route options
val routeOptions = RoutingOptions.Builder()
.setItineraryOptimization(true)
.setIncludeElevators(true)
.setIncludeStairs(true)
.setIncludeEscalators(true)
.setIncludeRamps(true)
.setIndoorOutdoorOptions(indoorOutdoorOptions)
.build()
// Create Routing constraints
val routingConstraints = RoutingConstraints.Builder()
.addRoutingImpact(routingImpact)
.setAccessLevel("{key}")
.build()
// Create Route requests
val routeRequest = RouteRequest.Builder(propertyId)
.setStartWaypoint(startWaypoint)
//you can add multiple destination way points
.addDestinationWaypoint(destinationWayPoint)
//optional
.setRoutingOptions(routeOptions)
//optional
.setRoutingConstraints(routingConstraints)
.build()
3. Handling Route Request Callback
Our pre-v6.1.0 version route request are created as follows:
coreApi.routing().requestRoute(request, new RoutingRequestCallback() {
@Override
public void onSuccess(@NonNull RouteResponse routeResponse) {
if (onComplete != null) {
onComplete.accept(null);
}
hideProgressBar();
// handle route response
}
@Override
public void onError(@NonNull RouteResponse routeResponse) {
if (onComplete != null) {
onComplete.accept(null);
}
hideProgressBar();
RouteErrorType errorType = routeResponse.getRouteError().getErrorType();
List<String> allAlertIds = getAlertIdsFromResponse(routeResponse);
RouteRequestError routeRequestError = RouteRequestError.from(
errorType,
getRouteErrorString(errorType),
allAlertIds
);
// handle route error response
}
});
Beginning form sdk version 6.1.0 onwards user can listen to route request callbacks using following code snippet-
coreApi.routing().addRoutingRequestListener(object: RoutingRequestCallback{
override fun onSuccess(routeResponse: RouteResponse) {
// Handle route response
}
override fun onError(routeResponse: RouteResponse) {
//Handle Route response error
}
})
4. Start Navigation
Our pre-v6.1.0 version navigation is created as follows:
mapApi.getCoreApi().routing().startNavigation(selectedRoute, null);
Beginning form sdk version 6.1.0 onwards user can start navigation using following code snippet-
coreApi.routing().startNavigation(
route,
routePathType,
routeResponse.getOptions(),
routeResponse.getConstraints(),
null
)
5. Stop Navigation
Our pre-v6.1.0 version stop navigation are created as follows:
coreApi.routing().removeNavigationListener(this);
coreApi.routing().stopNavigation();
Beginning form sdk version 6.1.0 onwards user can stop navigation using following code snippet-
coreApi.routing().stopNavigation();
6. Handling Navigation Callback
Our pre-v6.1.0 version navigation callback are created as follows:
coreApi.routing().requestRoute(request, new RoutingStatusCallback() {
@Override
public void onRoutingStatus(boolean isRoutingModeOn, Route route) {
Logger.d("onRoutingStatus: isRoutingModeOn=%s, route=%s, ", isRoutingModeOn, route);
}
@Override
public void onRouteSegmentReached(RouteSegment currentRouteSegment, List<RouteSegment> visitedRouteSegments, List<RouteSegment> upcomingRouteSegments) {
Logger.d("onRouteSegmentReached: currentRouteSegment=%s, visitedRouteSegments=%s, upcomingRouteSegments=%s, ", currentRouteSegment, visitedRouteSegments, upcomingRouteSegments);
}
@Override
public void onRouteInstruction(RouteNode routeNode, RouteNode nextKeyNodeNextQuickInstruction) {
Logger.d("onRouteInstruction: routeNode=%s, nextKeyNodeNextQuickInstruction=%s ", routeNode, nextKeyNodeNextQuickInstruction);
}
@Override
public void onUserProgressAlongRoute(RouteUserProgress routeUserProgress) {
Logger.d("onUserProgressAlongRoute: routeUserProgress=%s, ", routeUserProgress);
}
});
Beginning form sdk version 6.1.0 onwards user can navigation callback using following code snippet-
coreApi.routing().addNavigationListener(object: NavigationCallback{
override fun onNavigationInitSuccess(navState: NavigationState) {
Logger.d("onNavigationInitSuccess: navState=%s", navState);
}
override fun onNavigationInitFailure(error: NavigationError) {
Logger.d("onNavigationInitFailure: error=%s", error);
}
override fun onRouteSegmentReached(
currentSegment: RoutePathSegment,
visitedSegments: List<RoutePathSegment>,
upcomingSegments: List<RoutePathSegment>
) {
Logger.d("onRouteSegmentReached: currentSegment=%s, visitedSegments=%s, upcomingSegments=%s", currentSegment, visitedSegments, upcomingSegments);
}
override fun onRouteInstruction(
currentInstruction: RoutePointInstruction,
nextInstruction: RoutePointInstruction,
afterInstruction: RoutePointInstruction?
) {
Logger.d("onRouteInstruction: currentInstruction=%s, nextInstruction=%s, afterInstruction=%",
currentInstruction, nextInstruction, afterInstruction);
}
override fun onUserProgressAlongRoute(state: NavigationState) {
Logger.d("onUserProgressAlongRoute: state=%s", state);
}
override fun onRouteRecalculation(
state: NavigationState,
newRoute: Route,
routePathType: RoutePathType
) {
Logger.d("onRouteRecalculation: routePath=%s, ", routePath);
}
override fun onDestinationReached(destination: Waypoint) {
Logger.d("onDestinationReached: destination = %s, ", destination.getName());
}
override fun onNavigationStopped() {
}
})