showPoi

Command

Creates PoiStyle from given parameters if it does not exist already and display it on MapView

Draws the client application's own points on BeNav's map (its depots, its customers, its charging network, its collection points) with its own icons. The map the driver already uses for navigation becomes the map that also shows the operation's own geography, instead of the driver switching between two applications to see both.

Each POI carries an id chosen by the client application, a position and at least one icon. Sending the command replaces whatever was displayed before, so the client application always sends the complete set it wants visible.

Worth knowing

• An icon can be a remote URL, an image bundled in the client application, or a file it shares with BeNav. The last two render with no network at all, which matters for vehicles working out of coverage.
• Icon loading is all-or-nothing per command: if one icon fails, none of that command's POIs are shown and an error says which kind of failure it was.
• Sending an empty list clears every POI, the same as hideAllPois.

Command#

{
    "jsonrpc": "2.0",
    "method": "showPoi",
    "id": "test_basic_poi",
    "params": {
        "pois": [
            {
                "id": "restaurant_garibaldi",
                "lat": 43.7031300,
                "lon": 7.2660800,
                "category": "Restaurant",
                "iconURL": "https://cdn-icons-png.flaticon.com/128/3082/3082031.png",
                "iconWidth": 40,
                "iconHeight": 40
            }
        ]
    }
}

Specific parameters:

• id Unique identifier for the Poi
• iconURL Icon source for the 2D state - a URL, an app drawable name or a granted content:// URI (see Icon sources below). Optional companions: icon3DURL, iconOnClickURL, icon3DOnClickURL for the 3D and clicked states.
• iconWidth/iconHeight Dimensions icon will be resized to.
  • Validity range for these dimensions: 1 to 512 inclusive. Set both or neither - supplying only one fails validation.
• pois List of Pois, if empty this command will behave like hideAllPois

At least one icon field must be set on every POI; a POI with no icon fails validation and the command answers -32700 parse.error. Duplicate POI ids within a single command are rejected the same way.

Besides id, lat, lon and the icon fields, a POI also accepts the optional metadata address, description, category, phoneNumber, rating, distance and photoURL.

Icon sources#

Each icon field holds one icon source. BeNav detects the kind from the value's prefix - there is nothing else to specify:

There is no fallback: if a source fails to load, that POI is not shown and the command returns an error. A POI may mix kinds across states (for example a drawable for 2D and a URL for 3D). Sizing applies to every kind.

Granting BeNav a content:// URI#

BeNav holds no media or storage permission, so it can only read a URI it has been explicitly granted. When your own application owns the icon - typically behind a FileProvider - grant read access to that specific URI before referencing it:

val iconUri: Uri = FileProvider.getUriForFile(
    context,
    "${context.packageName}.fileprovider",   // your FileProvider authority
    File(context.filesDir, "icons/poi.png")
)

context.grantUriPermission(
    "com.benomad.benav",                      // BeNav's package
    iconUri,
    Intent.FLAG_GRANT_READ_URI_PERMISSION
)

// then send showPoi with "iconURL": "content://com.yourapp.fileprovider/icons/poi.png"

The grant stays in effect until your application revokes it with revokeUriPermission, or until either application is uninstalled. If you are not certain a grant is still active, simply re-issue it before sending the command - granting the same URI twice is harmless. An ungranted content:// URI fails with 33 poi.icon.access.denied. For a deployment with no companion app to issue the grant, deliver the icon as a URL or bundle it as a drawable instead.

Response#

Success#

{
  "id": "test_basic_poi",
  "jsonrpc": "2.0",
  "result": {}
}

Error#

If the Poi's given id is already in use by another Poi

{
    "error": {
        "code": 15,
        "message": "poi.not.valid"
    },
    "id": "used_poi_id",
    "jsonrpc": "2.0"
}

If an icon cannot be produced, the POI is not shown and the command returns one of:

Icon deployment is all-or-nothing per command: if any icon of any POI fails, the command reports the error and no POI from that command is shown.