Migration from V6 to V8¶

The major APIs’ differences between Pointr V6 SDK and V8 SDK are related to the User Interface classes. The Map Widget and all related classes have been the most affected since now the SDK has Pointr’s latest 3D maps technology with new UI components for most of the mobile features. The managers based structure is mostly the same except for the removal of MapManager, the renaming of the terms venue and facility and other minor changes.

Migrating to the v8 iOS SDK from v6 requires the following steps.

1. Replacing the SDK with the new version¶

This can be done in the following 2 ways:

• Manually - Replacing the v6 .xcframework file with the v8 .xcframework file in your app bundle. Embed & Sign the framework in the General tab of your target.
• Cocoapods - Changing the version of PointrKit in your project’s Podfile with 8.0.0

2. Add the new PointrContent.zip provided by us¶

This is a crucial step as the new zip file uses our v8 APIs.

3. Adding the Maplibre framework¶

• Manually - Adding the MapBox .xcframework (Maplibre) file (provided by us) to your app bundle. Embed & Sign the framework in the General tab of your target.
• Cocoapods - Adding the Pointr SDK to your Podfile (Step 1) automatically downloads the correct version of Maplibre, so there is nothing to be done if you are using Cocoapods.

4. Remove conformance to PointrBaseDelegate in the class where you initialise and start Pointr. Instead start Pointr like below and handle its states accordingly.¶

Replace the following code:

Swift Code:

Pointr.setSharedInstance(Pointr(params: params))
Pointr.sharedInstance().addListener(self)
Pointr.sharedInstance().startWith { (state, messages) in
    print("Pointr state '\(state)' (\(messages?.count ?? 0) warnings)")
    for message in messages ?? [] {
        print("Warning- \(message)")
    }
}

Swift Code:

Pointr.shared.start(with: params, onStateChanged: { [weak self] (state) in
    DispatchQueue.main.async {
        self?.handlePointrStateChange(state)
    }
})

Swift Code:

func onPointrBaseStateChanged(to state: PointrState, withMessages messages: [String]?) {
     PTRDispatchAsyncOnMainQueue { [weak self] in
        switch state {
        case .validating:
            //handle Pointr validating state
        case .registering:
            //handle Pointr registering state
        case .configuring:
            //handle Pointr configuring state
        case .running:
            //handle Pointr running state
        case .off:
            //handle Pointr off state
        default:
            break
        }
    }
} 

With:

Swift Code:

func handlePointrStateChange(_ state: PointrState) {
    switch state {
    case .validating:
        //handle Pointr validating state
    case .registering:
        //handle Pointr registering state
    case .configuring:
        //handle Pointr configuring state
    case .running:
        //handle Pointr running state
    case .off, .failedValidation, .failedRegistration:
        //handle other Pointr states
    default:
        break
    }
}

5. Other API changes.¶

Venue and Facility types¶

Venue and facility terms have been renamed to Site and Building across the entire SDK. This includes, class names, protocols, properties and methods.

Examples of classes and Protocols:

Examples of properties (across several classes):

Examples of Methods:

Pointr class¶

Access Pointr’s singleton using the shared property.

Swift Code:

let pointr = Pointr.shared

Access Pointr’s managers using optional properties. Example for site manager:

Swift Code:

Pointr.shared.siteManager?.venues()

Changes in PTRMapWidgetViewController API¶

• func showPoiDetails(_ poi: PTRPoi) -> Allows third party integrators to show POI details view of the given Poi.
• func showPathFinding(pathSession: PTRPathSession, destination: PTRPoi) -> Allows third party integrators to start a path session within the context of Pointr Maps. To learn more about creating PTRPathSession’s please refer to the Pathfinding section of our Doc center.
• func showRouteSummary(path: PTRPath, destination: PTRPoi) -> Allows third party integrators to show the route summary view of the given poi. This shows a view that includes the distance, estimated time, and the route steps to arrive at the given Poi.

Changes in PTRMapViewController API¶

• func rotateToDirection(_ direction: CLLocationDirection, animated: Bool)
  • direction: The heading of the map, measured in degrees clockwise from true north
  • animated: Flag to determine changing should be animated or not.
• resetNorth() -> This method resets the orientation back to the northern heading with animation. This is for when the map is in Rotational mode. Please refer to the Map Modes section of our doc center.
• All the methods regarding MapDrawables are removed.
• All the methods related to MapTrackingModes are removed. Now the operations related to MapModes should be handled using the mapWidget.mapTrackingModeEventsHandler

Changes in MapDrawables¶

• The concept of MapDrawable, MapDrawableSupplier, MapDrawableViewSupplier are all removed. For V8 the map already contains all the necessary annotations (all pois added to Pointr Cloud), so it’s not necessary to manage it in your implementation. As a result, the icons for the annotations cannot be changed from the app side. You will be able to get your designs to the Pointr team, and we will update our 3D maps accordingly.

Custom Annotations¶

• In case you still want to add your own annotations to the map, instead of using MapDrawableSupplier and MapDrawableViewSupplier as in v6, you use the addAnnotation and removeAnnotation methods on the PTRMapViewController.

• The data specific to each annotation, like location and title, is set on PTRMapViewAnnotation class, and the data related to appearance is defined on a new class named PTRMapViewAnnotationLayer.

• Annotations with the same appearance should be added to the same layer.

Swift Code:

let mapLevel = PTRMapViewLevel(levelIndex: 0, buildingId: 1, siteId: 1)
let annotation = PTRMapViewAnnotation(identifier: “id”, coordinate: coordinate, mapLevel: mapLevel, text: “Annotation Title”)
let layer = PTRMapViewAnnotationLayer(identifier: “layer_id”, icon: UIImage(named: “icon”, textColor: .red, shouldAllowOverlap: true)

mapWidget.mapViewController.addAnnotation(annotation, toLayer: layer)

NOTE:¶

• In case you want to add annotations to the map and use the SDK’s default appearance, you should call: Swift Code:

  mapWidget.mapViewController.addAnnotation(annotation)
  

PTRLocation¶

• The local coordinate system has been removed, which means the properties x and y are no longer available. The only available coordinates are now the geo coordinates, latitude and longitude, that can be accessed through the coordinate property.

• Other classes no longer descend from PTRLocation, like PTRPoi. Instead, these classes now have a property named location. Example:

• Methods that used to have arguments of type PTRLocation, have changed to PTRLocationAware type. PTRLocationAware is now the super class of classes like PTRPoi. This means that passing a PTRPoi object in these cases will still be valid, as well as passing PTRLocation objects.

Changes in Zoom & Scroll¶

• Changing the zoom level api has changed. It is now done from PTRMapViewController with the following method;
  • func setZoomLevel(_ zoomLevel: Double, animated: Bool) -> Zooms the map to desired zoom level.
    • zoomLevel? Desired Zoom Level.
    • animated? Flag to determine if zooming should be animated or not.
• @objc public func zoomTo(location: PTRLocation) method from PTRMapView has turned to func zoomToCoordinate(_ coordinate: CLLocationCoordinate2D) in PTRMapViewController, which zooms in defaultLocationZoomLevel(Double = 19.0) amount. If you want to have a custom zoom level and scroll to a location, please use func scrollToCoordinate(_ coordinate: CLLocationCoordinate2D, zoomLevel: Double) function. Or if you only want to scroll and not change zoom level, please use func func scrollToCoordinate(_ coordinate: CLLocationCoordinate2D)

Swift Code:

mapWidget.mapViewController.scrollToCoordinate(poi.location.coordinate)

Building configuration¶

PTRFacilityConfiguration class has been removed on v8. All data related to the building’s geometry like geo coordinates of the corners, center, etc, can be accessed directly on PTRBuilding objects.

Example to get north east coordinate:

Swift Code:

CLLocationCoordinate2D northEastCoordinate = building.boundingBox.northEastCoordinate

Example to get center:

Swift Code:

CLLocationCoordinate2D centerCoordinate = building.geometry.enclosingCircle.center.coordinate

Joystick¶

On v6 the joystick enabled flag is declared on PTRMapViewController.

Swift Code:

mapWidget.mapViewController.isJoystickEnabled = true

On v8, the joystick enabled flag is declared on the PTRMapWidgetConfiguration.

Swift Code:

let configuration = PTRMapWidgetConfiguration()
configuration.isJoystickEnabled = true

Changes in Listener & Handler Logic/API¶

• PTRMapViewControllerListener is removed. It is updated to PTRMapEventsListener. You can implement this interface and add it as a listener to PTRMapViewController instance with the addListener method. Some of the callbacks from PTRMapEventsListener were renamed and new ones added.
  • func mapViewController(_ mapViewController: PTRMapViewController, didTapMap mapView: PTRMapView, tapGesture: UITapGestureRecognizer) renamed func mapDidReceiveTap(_ map: PTRMapViewController)
  • func mapViewController(_ mapViewController: PTRMapViewController, mapDidChangeLevel mapView: PTRMapView, level: PTRLevel) renamed func map(_ map: PTRMapViewController, didChangeLevel level: PTRLevel)
  • func mapViewController(_ mapViewController: PTRMapViewController, didChangeMapTrackingModeFrom previousMapTrackingMode: PTRMapTrackingMode, to currentMapTrackingMode: PTRMapTrackingMode) renamed func map(_ map: PTRMapViewController, didChangeMapTrackingModeFrom previousMapTrackingMode: PTRMapTrackingMode, to currentMapTrackingMode: PTRMapTrackingMode)
  • func mapViewController(_ mapViewController: PTRMapViewController, onPoiDetailViewEvent poiDetailView: PTRPoiDetailView, event: PTRPoiDetailViewEvent) moved to PTRPoiDetailsEventsListener
  • func mapViewController(_ mapViewController: PTRMapViewController, mapDidScroll mapView: PTRMapView, rect: CGRect) renamed func map(_ map: PTRMapViewController, didScrollTo bounds: PTRMapViewBounds)
  • func mapViewController(_ mapViewController: PTRMapViewController, onRouteHeaderViewEvent routeHeaderView: PTRRouteHeaderView, event: PTRRouteHeaderViewEvent) moved to PTRRouteSummaryEventsListener
  • (added) func mapDidStartLoading(_ map: PTRMapViewController)
  • (added) func mapDidEndLoading(_ map: PTRMapViewController)
  • (added) func map(_ map: PTRMapViewController, didFailToLoadWith error: Error)
  • (added) func map(_ map: PTRMapViewController, didReceiveTapOnMarker marker: PTRMapViewMarker)
  • (added) func mapDidChangeRegion(_ map: PTRMapViewController, animated: Bool)
  • (added) func map(_ map: PTRMapViewController, didDetectSites sites: [PTRSite], buildings: [PTRBuilding])
  • (added) func map(_ map: PTRMapViewController, didDetectSitesOnFocus sitesOnFocus: [PTRSite], buildingsOnFocus: [PTRBuilding])
  • (added) func mapWillStartLoadingBaseLayers(_ map: PTRMapViewController)
• Like PTRMapViewControllerListener, you can listen to events from other components by adding listener to the related UI component. Please refer to the reference documentation of these interfaces to get an understanding of the methods available and their comments.
  • PTRSearchEventsListener -> Listen to events regarding the search bottom sheet. Like a POI click from the search list.
  • PTRPoiDetailsEventsListener -> Listen to events regarding the POI Details View Bottom sheet, which is shown after a POI click. So events like Navigate, Show action can be listened to here.
  • PTRRouteSummaryEventsListener -> Listen to events regarding the Route Summary view, which is shown after the user selects to navigate to a Poi. The action of the user is notified to these listeners, either Dismiss or Navigate
  • PTRLevelSelectorEventsListener -> Listen to the events from the Level Selector. Like LevelSelector clicked, or like user clicked on a level.
  • PTRPathFindingEventsListener -> Listen to when pathfinding is closed manually by user
  • PTRPathSessionDelegate -> Listen to path updates, callbacks will be triggered when there is an active path session
  • PTRMapEventsListener -> Listen to Map events, like tap on map, tap on Poi, level change etc.
  • PTRExitButtonEventsListener -> Listen to events regarding the action on the exit button.
  • PTRLocationEventsHandler -> Listen to location updates, or level changes by user position, or map tracking mode change
  • PTRMapTrackingModeButtonListener -> Listen to events regarding tracking mode changes and actions affecting tracking modes, like map scroll, POI highlight, map rotation, etc.
  • PTRArButtonEventsListener -> Notifies listeners when AR button is clicked
• Setting custom handlers are converted to property setters. On V6 they were conformed to the class, but with V8, they are set with property access syntax like mapwidget.handler = customHandler.
• The handler logic remains the same. They are concrete classes which implement the Listener interfaces listed above, and default behavior upon these events. To give an example, let’s say a user wants to override the behavior upon level selection, they can write a custom handler that implements the PTRLevelSelectorEventsHandler, and override the ‘levelSelector’ method. They can call super to keep the default behavior and augment it or if they do not want the default behavior they can remove the super call and add their custom behavior.