Social reports

_{Estimated reading time: 5 minutes}

Social reports are user-generated alerts about real-time driving conditions or incidents on the road. These reports can include various types of information, such as accidents, police presence, road constructions and more.

Users can create new reports, with the possibility to provide information such as category, name, image and other parameters. They can provide feedback, enabling voting on the accuracy of incidents and commenting on reported events. They can confirm or deny the validity of reports, delete their own reports, and contribute additional comments for further context. These interactions help enhance the accuracy and reliability of the information shared within the community.

Social reports are visible by all users with the social overlay enabled, given a compatible map style.

Uploading a Social Report

Before uploading a social report, it must first be prepared. The SocialOverlay class provides methods like prepareReporting and prepareReportingCoords to handle the report preparation phase. The prepareReporting method takes a category ID and uses the current user's location, while prepareCoordinates accepts both a category ID and a Coordinates entity, enabling reporting from a different location. Those methods return an integer, called prepareId which is later passed to report method, in order to upload a social overlay item.

The following code snippet performs prepare and report of a social overlay item:

// Get the reporting id (uses current position)
int idReport = SocialOverlay.prepareReporting(categId: 0);

// Get the subcategory id
SocialReportsOverlayInfo info = SocialOverlay.reportsOverlayInfo;
List<SocialReportsOverlayCategory> categs = info.getSocialReportsCategories();
SocialReportsOverlayCategory cat = categs.first;
List<SocialReportsOverlayCategory> subcats = cat.overlaySubcategories;
SocialReportsOverlayCategory subCategory = subcats.first;

// Create the other required parameters
Uint8List image = await ImageGenerator.createReferenceImage(size: const Size(100, 100), format: ImageFileFormat.png);
ParameterList params = ParameterList.create();

// Report
GemError res = SocialOverlay.report(idReport, subCategory.uid,"TEST MAGIC LANE", image, ImageFileFormat.png, params);

The report is displayed for a limited duration before being automatically removed.

The report method might return the following GemError values:

• invalidInput if the category id is invalid/ the parameters are ill formatted or if the snapshot is an invalid image.
• suspended if the rate limit for the user is exceeded.
• expired if the prepared report is too old.
• notFound if no accurate data source is detected.
• scheduled if the operation will proceed later, when internet connection is stable.

warning

Most report categories require the use of the prepareReporting method, ensuring higher report accuracy by confirming the user’s proximity to the reported location. See the Get started with Positioning guide for more information about configuring the data source.

warning

While reporting events, the prepareReporting method needs to be in preparing mode (categId=0) rather than dry run mode (categId !=0).

Updating a Social Report

In order to update an existing report's parameters the SocialOverlay.updateReport(item, params) method can be used as shown below:

List<OverlayItem> overlays = mapController.cursorSelectionOverlayItems();

SearchableParameterList params = overlays.first.previewData;
GemParameter param = params.findParameter("location_address");
param.value = "New address";

GemError error = SocialOverlay.updateReport(item: overlays.first, params: params);

The structure of the SearchableParameterList object passed to the update method should follow the structure returned by the OverlayItem's previewData. The keys of the fields accepted can be found inside PredefinedOverlayGenericParametersIds and PredefinedReportParameterKeys.

The report method might return the following GemError values:

• invalidInput if the SearchableParameterList's structure is incorrect.
• scheduled if the operation will be later completed.

Deleting a Social Report

This is accomplished through SocialOverlay.deleteReport(overlayItem), with the restriction that only the original creator of the report has the authority to delete it.

The delete method might return the following GemError values:

• invalidInput if the item is not a social report overlay item or not the result of an alarm notification.
• accessDenied if the user does not have the required rights.
• scheduled if the operation will be later completed.

Interact with a Social Report

Provide positive feedback

Users can provide positive feedback for a reported event using SocialOverlay.confirmReport(), which increases the value of the score key within OverlayItem.previewData.

Provide negative feedback

If a report is found to be inaccurate, it can be denied by other users using SocialOverlay.denyReport(), which accepts an OverlayItem object as its parameter.

If a reports gets many downvotes it will be removed.

Both confirmReport and denyReport will return the following GemError values:

• invalidInput if the item is not a social report overlay item or not the result of an alarm notification.
• accessDenied if the user already voted.
• scheduled if the operation will be later completed.

Add comment

Additionally, users can contribute comments to a reported event by calling SocialOverlay.addComment, as shown below:

final overlays = mapController.cursorSelectionOverlayItems();
SocialOverlay.addComment(item: overlays.first, comment: "This is an added comment");

Added comments can be viewed within the OverlayItem's previewData

The addComment method will return the following GemError values:

• invalidInput if the item is not a social report overlay item or not the result of an alarm notification.
• connectionRequired if no internet connection is available.
• busy if another comment operation is in progress.