06 – Using Custom Pois in WYF

The Situm WYF library provides a set of methods for creating, storing, and managing customizable points of interest (POIs) on both Android and iOS devices. Unlike regular POIs that are created via dashboard, custom POIs are created, managed, and stored locally on the device.

Warning! As of now, only one custom POI can be created per device.

Managing Custom POIs #

As it has been stated before, the Situm WYF library exposes a set of methods that allows for custom POI creation and modification, on the following sections we will lay out how to use each one of these methods.

Creation of a Custom POI #

To create a custom POI, use the startCustomPoiCreation method, which takes optional arguments such as the name, description, and custom selected and unselected icons. The usage of this method will trigger the UI to show the edition mode. On this graphical interface we distinguish three elements:

• A blue marker that allows you to select a custom location on the map. This blue marker will always be displayed on the middle of the screen, you must move the map to select the desired location.
• A blue button with a tick on the center which should be used to confirm where the custom POI is located on the map and therefore save the custom POI.
• A red button with a cross on the center which should be used to exit the creation mode.

Once the custom POI is saved, it will appear on the map with the icon that was specified via arguments o a default one if no icon is supplied.

You can interact with this custom POI as with any other regular POI. That is, you can select the custom POI on the map and navigate to it once it is selected. Additionally when the custom POI is selected, a new button appears that lets the user delete it.

On Android, once the library has finished loading you can invoke startCustomPoiCreation to create the custom POI. This method admits for the definition of a callback, which is an instance of ActionsCallback to notify the application of the creation process’s state.

On iOS, you can invoke the startCustomPoiCreation method by providing a name, description and the corresponding icons for the custom POI.

A basic example of how to use this method is shown on the following snippets:

 SitumMapsLibrary mapsLibrary = null; 
 ...

 // Create bitmaps for the custom poi's icons
 Bitmap selectedIconBitamp = BitmapFactory.decodeFile("/path/to/selected/icon/file.jpg");
 Bitmap deSelectedIconBitamp = 
     BitmapFactory.decodeFile("/path/to/deselected/icon/file.jpg");

 // Start custom poi creation
 mapsLibrary.startCustomPoiCreation("My custom POI", "This is a custom POI",
         selectedIconBitamp, deSelectedIconBitamp, new ActionsCallback() {
     @Override
     public void onActionStarted() {
         Log.d(TAG, "Creation mode for custom POI initialized");
     }

     @Override
     public void onActionConcluded() {
         Log.d(TAG, "Creation mode for custom POI exited");
     }
 });

// Start custom poi creation
SITFLNativeMapView.library?.startCustomPoiCreation(
    name: "Custom poi",
    description: "Description of your custom poi",
    markerIcon: UIImage(named: "yourIcon.png"),
    markerIconSelected: UIImage(named: "yourSelectedIcon.png")
)

Retrieval of a Custom POI #

To retrieve a saved custom POI’s basic information, use the getCustomPoi method which takes the identifier of the custom POI as an argument.

In Android you can do this by the means of the method getCustomPoi. This method returns a CustomPoi object. In order to do it on iOS, you would use the method getCustomPoi, which obtains an instance of CustomPoi.

A basic example of usage is shown in the following code snippet:

// Obtain an instance of the saved custom poi given its id
CustomPoi customPoi = mapsLibrary.getCustomPoi(poiId);
Log.d(TAG, "Custom POI retrived " + customPoi.getName());

// Obtain an instance of the saved custom poi given its id
let customPoi = SITFLNativeMapView.library?.getCustomPoi(id: poiId)

Selection of a Custom POI #

To select a saved custom POI, use the selectCustomPoi method by providing the custom POI’s identifier.

To be able to do that on Android we would need to use the method selectCustomPoi. On iOS you would invoke the method selectCustomPoi with the custom POI’s identifier as argument and a callback for the result of the action.

A basic demonstration on how to select a custom POI is as follows:

// Select custom poi given its ID
mapsLibrary.selectCustomPoi(poiId, new ActionsCallback() {
    @Override
    public void onActionStarted() {
        Log.d(TAG, "Custom POI selection started");
    }

    @Override
    public void onActionConcluded() {
        Log.d(TAG, "Custom POI selection finished");
    }
});

// Select custom poi given its ID
SITFLNativeMapView.library?.selectCustomPoi(id: poiId, completion:
 { selectCustomPoiResult in
    switch selectCustomPoiResult {
    case .success:
        print("Successfully selected the custom poi")
    case .failure(let reason):
        print("Error selecting custom poi: \(reason)")
    }
})

As a result of the invokation of this method, the custom POI will appear as selected and the camera will focus on the custom POI.

Deletion of a Custom POI #

Finally, a custom POI can also be removed programmaticaly through the method removeCustomPoi, which takes the identifier of the custom POI we want to delete as an argumento. The invokation of this method results on the deletion of the custom POI from both the local storage and the screen.

The deletion can be perfomed on Android with removeCustomPoi. On Android, you can pass an instance of ActionsCallback as a callback to monitor the state of the deletion action. The same deletion operation can be done on iOS with the method removeCustomPoi.

The next code extract exemplifies how to use this method:

// Delete stored custom poi given its id
mapsLibrary.removeCustomPoi(poiId, new ActionsCallback() {
    @Override
    public void onActionStarted() {
        Log.d(TAG, "Custom POI deletion started");
    }

    @Override
    public void onActionConcluded() {
        Log.d(TAG, "Custom POI deletion finished");
    }
});

// Delete stored custom poi given its id
SITFLNativeMapView.library?.removeCustomPoi(id: poiId)

Listening for changes #

The Situm WYF library enables you to set up a listener for incoming changes on custom POIs created within your application. Four events, namely onCustomPoiCreated, onCustomPoiSelected, onCustomPoiDeselected, and onCustomPoiRemoved, are defined.

To listen for custom POI changes on Android you need to define a class that implements the OnCustomPoiChangeListener interface and thus implements the methods onCustomPoiCreated, onCustomPoiSelected, onCustomPoiDeselected, onCustomPoiRemoved. All of these methods return the instance of CustomPoi which was the object of the change.

Equivalently, on iOS you need to implement the protocol OnCustomPoiChangeListener and its methods onCustomPoiCreated, onCustomPoiRemoved, onCustomPoiSelected and onCustomPoiDeselected. All of them return the instance of CustomPoi that changed.

The following code snippet shows a simple example of how to set up the listener.

public class MainActivity extends AppCompatActivity implements OnCustomPoiChangeListener {
    SitumMapsLibrary mapsLibrary = null;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Set up the library
        LibrarySettings librarySettings = new LibrarySettings();
        mapsLibrary = new SitumMapsLibrary(R.id.maps_library_target, this, librarySettings);

        // Bind this class as a listener for custom POI changes
        mapsLibrary.setOnCustomPoiChangeListener(this);

        // Load the library
        mapsLibrary.load();
    }

    // Listen for creation events
    @Override
    public void onCustomPoiCreated(CustomPoi customPoi) {
        Log.d(TAG, "A custom POI was created " + customPoi.getName());
    }

    // Listen for selection events
    @Override
    public void onCustomPoiSelected(CustomPoi customPoi) {
        Log.d(TAG, "A custom POI was selected " + customPoi.getName());
    }

    // Listen for deselection events
    @Override
    public void onCustomPoiDeselected(CustomPoi customPoi) {
        Log.d(TAG, "A custom POI was deselected " + customPoi.getName());
    }

    // Listen for deletion events
    @Override
    public void onCustomPoiRemoved(CustomPoi customPoi) {
        Log.d(TAG, "A custom POI was removed " + customPoi.getName());
    }
}

class YourViewController: UIViewController, OnCustomPoiChangeListener {
    override func viewWillAppear(_ animated: Bool) {
        let library = SitumMapsLibrary(...)
        library.setOnCustomPoiChangeListener(listener: self)
    }

    public func onCustomPoiCreated(customPoi: CustomPoi) {
        print("On Custom Poi created detected")
    }

    public func onCustomPoiRemoved(customPoi: CustomPoi) {
        print("On Custom Poi removed detected")
    }

    public func onCustomPoiSelected(customPoi: CustomPoi) {
        print("On Custom Poi selected detected")
    }

    public func onCustomPoiDeselected(customPoi: CustomPoi) {
        print("On Custom Poi deselected detected")
    }
}

Use Cases #

One potential application for the methods described herein is a “Find My Car” application. Please refer to this example implemented in Flutter to see how such an implementation would look like. The following images show a preview of the application: