Migration guide to 5
Migration Guide to 5.+
This guide is provided to assist with the migration from Mapsted SDK v4.6 to v5.+.
Android
We have restructured various key parts of the mobile sdk, as outlined below.
Initialization of Mapsted SDK vs Starting/Stopping Location Services
In 4.6, the sdk-core required location permissions to successfully initialize. As a result, location services were automatically enabled when the mobile sdk was in use. In 5.+, we have provided additional control, flexibility, and customization in terms of the use of location services within the mobile sdk. In particular, we have separated the concepts of initialization from starting/stopping location services.
In 4.6, CustomParams and CustomMapParams could be used as a type of global/static initializer of the mobile SDK to provide customizable parameters for SDK usage. In 5.+, the appropriate params must be supplied for initialization. These are outlined in the table below.
| Sdk | Params class | Extends |
|---|---|---|
| sdk-core | CoreParams | -- |
| sdk-map | CustomMapParams | CoreParams |
| sdk-map | CustomParams | CustomMapParams |
As can be seen, due to the inheritance relationship, a single instance of CustomParams can be created and supplied for initializing each of the foundational sdks.
coreApi.setup().initialize(params, new CoreApi.CoreInitCallback() {
@Override
public void onSuccess() {
if (hasLocationPermissions()) {
// For example, if we have location permissions then start location services immediately
coreApi.setup().startLocationServices(getApplicationContext(), new CoreApi.LocationServicesCallback() {
@Override
public void onSuccess() {
}
@Override
public void onFailure(SdkError sdkError) {
}
});
}
}
@Override
public void onStatusUpdate(SdkStatusUpdate sdkUpdate) {
}
@Override
public void onFailure(SdkError sdkError) {
}
});
Passing Params Between Activities/Fragments
If you wish to initialize a CustomParam instance once and then pass it to various Activities or Fragments for use with initializing the mobile sdk, the best approach would be to json serialize the object and pass it as a string. Please find the example below.
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// ...
// Step 1. Parse params from json
Intent intent = getIntent();
Bundle bundle = intent.getExtras();
CustomParams params = null;
String paramsJson = bundle != null ? bundle.getString(SET_CUSTOM_PARAMS_JSON, null) : null;
if (paramsJson != null) {
params = new Gson().fromJson(paramsJson, CustomParams.class);
}
// Step 2. Set appropriate map and/or ui container views
if (params == null) {
params = CustomParams.newBuilder(this, fl_base_map_content, fl_map_ui_content).build();
}
else {
params.setActivity(this);
params.setMapContainer(fl_base_map_content);
params.setUiContainerView(fl_map_ui_content);
}
// Step 3. Use Params to initialize
mapUiApi.setup().initialize(params, new MapUiApi.MapUiInitCallback() {
@Override
public void onCoreInitialized() {
}
@Override
public void onMapInitialized() {
}
@Override
public void onLocationServicesStarted() {
}
@Override
public void onSuccess() {
}
@Override
public void onFailure(SdkError sdkError) {
}
@Override
public void onStatusUpdate(SdkStatusUpdate sdkUpdate) {
}
});
}
sdk-core
A summary of the modulorized CoreApi is shown below. For the initial 5.+ release, where possible, we have attempted to avoid modifying any of the method signatures and focused primarily on reorganizing them to aid with the initial adoption process.
| CoreApi Methods | Description |
|---|---|
| coreApi.setup() | Used for initializing |
| coreApi.sensors() | Used for sensor-related methods (e.g., determining missing sensors, accuracy callbacks) |
| coreApi.properties() | Used for property related information and functionalities |
| coreApi.buildings() | Used for building related information and functionalities |
| coreApi.utilities() | Used for various common functions |
| coreApi.locations() | Used for location-based data and functionalities |
| coreApi.config() | Used for config-related information |
| coreApi.routing() | Used for routing-related information and functionalities |
| coreApi.analytics() | Used for reporting mobile app analytics usage and for setting analytics-related functionalities |
| coreApi.licence() | Used for licence related information |
| coreApi.lifecycle() | Used for reporting lifecycle-related information (e.g., onResume, onDestroy) |
sdk-map
A summary of the modulorized MapApi is shown below. For the initial 5.+ release, where possible, we have attempted to avoid modifying any of the method signatures and focused primarily on reorganizing them to aid with the initial adoption process.
| MapApi Methods | Description |
|---|---|
| mapApi.setup() | Used for initializing |
| mapApi.data() | Access or modify the data used by the map module (e.g., select/draw/remove property, select entity) |
| mapApi.mapView() | Used for accessing additional map view-related functionality |
| mapApi.mapView().customView() | Used for adding/managing custom views on the map |
| mapApi.mapView().customPlot() | Used for adding/managing custom plot elements on the map |
| mapApi.mapView().layers() | Used for managing property/building layers on the map |
| mapApi.mapView().layout() | Used for managing map layout (e.g., notification bar details) |
| mapApi.mapView().config() | Used for managing map config details (e.g., styles, 2D vs 3D) |
| mapApi.mapView().camera() | Used for managing map camera details (e.g., zoom, tilt, move) |
| mapApi.mapView().data() | Used for accessing/managing data source associated with the mapview |
| mapApi.wayfinding() | Used for wayfinding-related information and functionalities |
| mapApi.lifecycle() | Used for reporting lifecycle-related information (e.g., onResume, onDestroy) |
sdk-map-ui
Initialization
The MapUiApi has undergone a significant overhaul. MapstedSdkController has now been renamed to MapstedMapUiApi to be more consistent with the rest of the mobile-sdk naming convention. For example, in terms of initializing a MapUiApi instance, please see the sample code below.
// In 4.6
MapUiApi mapUiApi_old = MapstedSdkController.newInstance(context);
// In 5.+
MapUiApi mapUiApi_new = MapstedMapUiApi.newInstance(context);
A summary of the modulorized MapUiApi is shown below. For the initial 5.+ release, where possible, we have attempted to avoid modifying any of the method signatures and focused primarily on reorganizing them to aid with the initial adoption process.
| MapUiApi Methods | Description |
|---|---|
| mapUiApi.setup() | Used for initializing |
| mapUiApi.tags() | Used for tag creation/management |
| mapUiApi.customUi() | Used for injecting/managing custom UI views |
| mapUiApi.itinerary() | Used for itinerary management |
| mapUiApi.utils() | Used for various common functions |
| mapUiApi.locale() | Used for various language/locale-related functions |
| mapUiApi.lifecycle() | Used for reporting lifecycle-related information (e.g., onResume, onDestroy) |
iOS
The public-facing API for v5 has remained largely unchanged, so no significant migration is necessary.
Please see the release notes for the specific changes in each release.