Custom Places¶
It is possible to add custom Points of Interest (POIs). We call them Places. Places can be used for example to show the user's favorite places or places that are not available in the Sygic database. To be able to show custom places on the map, it is necessary to inject a skin definition for them.
In the next chapters, we will see how to import custom places from a JSON file, how to install them from the server or how to use them without downloading them.
Enabling Custom Places and modes¶
To enable custom places at startup, it is necessary to set Custom Places as the startupPoiProvider in the JSON Config:
"MapReaderSettings": {
"startup_poi_provider": "CustomPlaces",
}
By setting the Custom Places POI provider at startup, both map places and custom places will be visible in the map.
Setting the mode¶
There are two modes in which custom places can be used:
- Offline
- Online
Online mode means that the places are downloaded from the server while browsing the map or along the calculated route. This mode is suitable for places that are frequently updated. This is automatically managed by the SDK.
Offline mode means that the places are downloaded using the methods described below and stored in the app's database. They are not continually downloaded from the server.
Important
Before using the online or offline mode, it is necessary to set it like this:
SYCustomPlacesManager.shared()?.mode = .offline
Tip
Depending on your preferences, it might be a good idea to download the offline places upon downloading a map as the places
are tied to iso codes (and you get them via SYMapInstaller). Then, you can update them according to your needs.
Injecting a skin for Custom Places¶
To be able to see custom places on the map, you need to inject a skin definition for them. The skin definition is defined by a JSON that contains the style of the custom places, basically for groups and categories. Below is a sample of importing the skin definition:
Important
If not defined in the skin_default.xml file, it will be necessary to inject the skin at each mapView creation.
let skinDefinitionToInject = """
{
"skin": {
"poi_categories": {
"custom": {
"groups": {
"SYPotato": {
"enabled": true,
"color": "0xb38c00ff",
"icon": "0xe335",
"priority": 24,
"showWithoutText": true,
"zoomLevel": 17.9
}
},
"categories": {
"new_custom_category": {
"groupId": "SYPotato"
},
"anotherCategory": {
"groupId": "SYPotato"
}
}
}
}
}
}
"""
mapView.injectSkinDefinition( skinDefinitionToInject ) { result in
print("skin injected with result: \(result)")
}
Importing Custom Places from a JSON file¶
After having a JSON file with custom places ready, it is possible to import it using the following code:
SYCustomPlacesManager.shared()?.installOfflinePlaces(fromJson: "as_a_string") { error in
// do something
}
If you do not define a "dataset", the places wil be imported into the default dataset. The ID of the default dataset is "bf19e514-487b-43c4-b0df-9073b2397dd1".
Deleting Custom Places using a JSON file¶
It is also possible to delete custom places using a JSON file. For example, if you want to remove the custom place from custom places article, your JSON file would look like this:
{
"to_remove": [
"3047426d-849b-de0b-e82a-24c699c0b9a4"
]
}
Then, just call the same method as above to install the places. The place will be removed from the database. Removing is specified by the "to_remove" key in the JSON file. You can add/update and remove places in the same JSON file.
Installing custom places from server¶
After having the custom places uploaded to the server, it is possible to install them in your app. For further information about uploading the places to the server, please see the Custom Places API and the the Custom Places article
Installing¶
To install custom places from the server, you need to call the following method:
SYCustomPlacesManager.shared()?.installOfflinePlaces(fromDatasets: ["dataset_name"], forCountry: "iso", progress: { progress in
print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
print("finished " + error.debugDescription)
})
The method above installs places of the specified dataset for the specified country iso. Alternatively, you can install all datasets of a specific country:
SYCustomPlacesManager.shared()?.installOfflinePlaces(fromDatasets: [], forCountry: "iso", progress: { progress in
print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
print("finished " + error.debugDescription)
})
Or, you can install one dataset for all countries:
SYCustomPlacesManager.shared()?.installOfflinePlaces(fromDatasets: ["dataset_name"], forCountry: nil, progress: { progress in
print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
print("finished " + error.debugDescription)
})
Uninstalling¶
To uninstall custom places from the server, you need to call one of the following methods:
// this one uninstalls the specific dataset of the specific country
SYCustomPlacesManager.shared()?.uninstallOfflinePlaces(fromDatasets: ["dataset_name"], forCountry: "iso", completion: { error in
print("uninstalled with status: " + error.debugDescription )
})
// and using this method, you can uninstall all datasets of the specific country
SYCustomPlacesManager.shared()?.uninstallOfflinePlaces(forCountry: "iso", completion: { error in
print("uninstalled with status: " + error.debugDescription )
})
Updating¶
To update custom places from the server, you need to call the following method:
Note
Please note that this method updates all of the installed places, not just the ones from the specified country.
SYCustomPlacesManager.shared()?.updateInstalledPlaces(progress: { progress in
print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
print("finished " + error.debugDescription)
})
Search¶
You can read more about the Custom Places Search in the Custom Places Search article.