Upgrading from Nutiteq

Upgrading from Nutiteq Maps SDK 3.x

CARTO Mobile SDK is built on top of well-known and proven Nutiteq Maps SDK product (https://developer.nutiteq.com), which is used by hundreds of app developers and millions of end-users over about 10 years of history. Therefore the CARTO Mobile SDK version number starts with 4.0. If your app already uses Nutiteq SDK, then in the most part the upgrade from Nutiteq SDK 3.x to CARTO Mobile SDK 4.0 is straightforward.

There are several high-level reasons why we strongly recommend to upgrade to CARTO Mobile SDK if your app was previously developed with Nutiteq SDK 3.x:

• CARTO Mobile SDK is in active development while Nutiteq SDK is in maintenance mode. This means that all issues will be resolved with CARTO SDK first and only the critical ones are back-ported to Nutiteq SDK.
• The new SDK is open source with permissive open source license (BSD) and we plan to accept improvements and fixes from the community.
• The new SDK has better samples (especially for Xamarin/Windows Phone) and better documentation.
• The new SDK is safer to use and has much better error diagnostics via exceptions.
• The API of the new SDK, while similar to the old API, is cleaner and is designed with future extensions in mind.

Following guidelines are for Android, but for iOS the general steps (API changes) are basically same.

Simple changes

• The name of the library is now carto-mobile-sdk.jar/.aar, while the name of the native component of the library is libcarto_mobile_sdk.so. This can be imported with Gradle/Maven config: com.carto:carto-mobile-sdk:snapshot@aar

• Classes under com.nutiteq.* are moved to com.carto.* classes.

• Classes with Nutiteq prefix are renamed to classes with Carto prefix.

• com.nutiteq.wrappedcommons.* classes are moved to other modules. For example, com.nutiteq.wrappedcommons.MapPosVector is now com.carto.core.MapPosVector (in the same package as com.carto.MapPos).

• com.nutiteq.wrappedcommons.UnsignedCharVector is replaced with com.carto.core.BinaryData, which provides better interop support with Java byte arrays.

• When creating bitmaps, Nutiteq SDK required hard to explain 'power-of-two' flag. This flag is removed from CARTO Mobile SDK and the APIs are simpler.

• LineStyleBuilder.setLineJointType is renamed to LineStyleBuilder.setLineJoinType, and the corresponding enums are also renamed.

• UTFGridRasterTileLayer is removed from the SDK, UTF grid functionality is integrated into base TileLayer class.

Non-trivial changes

• com.nutiteq.ui.MapEventListener functionality is now split between 2 classes: com.carto.ui.MapEventListener and com.carto.layers.VectorElementEventListener. The instance of VectorElementEventListener must be attached to the VectorLayer that should receive events about clicks on its vector elements, while the instance of MapEventListener only receives general map-related events. The following custom listener in Nutiteq SDK

public class MyMapEventListener extends MapEventListener {
  @Override
  public void onMapMoved() {
    ...
  }

  @Override
  public void onMapClicked(MapClickInfo mapClickInfo) {
    ...
  }

  @Override
  public void onVectorElementClicked(VectorElementsClickInfo vectorElementsClickInfo) {
    ...
  }
}

should be split into 2 classes in CARTO Mobile SDK:

public class MyMapEventListener extends MapEventListener {
  @Override
  public void onMapMoved() {
    ...
  }

  @Override
  public void onMapClicked(MapClickInfo mapClickInfo) {
    ...
  }
}

public class MyVectorElementEventListener extends VectorElementEventListener {
  @Override
  public boolean onVectorElementClicked(VectorElemensClickInfo vectorElementClickInfo) {
    ...
    return true; // NOTE the return value; if true, then the click is handled, otherwise passed to the next element.
  }
}

• CARTO Mobile SDK uses exceptions where appropriate (and often Java checked exceptions), while Nutiteq SDK only logged in case of errors and did not notify the application about errors. For example, when instantiating CartoPackageManager, IOExceptions may be thrown if SDK fails to create or open the specified package database folder.

• Screenshot capture method captureRendering has moved from MapView class to MapRenderer class. The following snippet can be used in CARTO Mobile SDK:

mapView.getMapRenderer().captureRendering(new RendererCaptureListener() {
  @Override
  public void onMapRendered(Bitmap bitmap) {
    ...
  }
});

• Vector element Metadata can now hold any structured type in CARTO Mobile SDK and is not limited to strings, as in Nutiteq SDK. com.carto.core.Variant class must be now used to hold the metadata that can be read from JSON or serialized into JSON. To convert string-based metadata to Variant: Variant v = new Variant("string metadata"). To read string from Variant: String str = v.getString().

• Creating MBVectorTileDecoder requires few additional steps:

BinaryData styleBinary = AssetUtils.loadAsset("nutibright.zip");
CompiledStyleSet styleSet = new CompiledStyleSet(new ZippedAssetPackage(styleBinary));
VectorTileDecoder decoder = new MBVectorTileDecoder(styleSet);

While the same code in Nutiteq SDK looked like this:

UnsignedCharVector styleBytes = AssetUtils.loadAsset("nutibright.zip");
MBVectorStyleSet styleSet = new MBVectorStyleSet(styleBytes);
VectorTileDecoder decoder = new MBVectorTileDecoder(styleSet);

• There are lots additional of minor tweaks and cleanups, changes should be quite simple. No features have been removed.