Social Report

_{Estimated reading time: 4 minutes}

In this guide you will learn how to send a social report from within an app. An interactive map is displayed, and the social report is sent automatically as soon as the map is ready.

Setup

1. Get your Magic Lane API key token: if you do not have a token, see the Getting Started guide.
2. Download the Maps & Navigation SDK for Android archive file.
3. Download the SocialReport project archive file or clone the project with git.
4. See the Configure Android Example guide.

Run the example

In Android Studio, from the File menu, select Sync Project with Gradle Files.

An android device should be connected via USB cable. Press SHIFT+F10 to compile, install and run the example on the android device.

How it works

You can open the MainActivity.kt file to see how to send a social report from within an app while displaying an interactive map.

In this example, the social report is sent automatically when the app is started, so long as a real or mock device position, such as GPS, is available.

override fun onCreate(savedInstanceState: Bundle?)
{
     super.onCreate(savedInstanceState)
     setContentView(R.layout.activity_main)
     gemSurfaceView = findViewById(R.id.gem_surface)
     statusText = findViewById(R.id.status_text)
     SdkSettings.onMapDataReady = { isReady ->
         if (isReady)
         {
             // Defines an action that should be done
             // when the world map is ready (Updated/ loaded).
             SdkCall.execute {
                 gemSurfaceView.mapView?.followPosition()
                 waitForNextImprovedPosition {
                     submitReport()
                 }
             }
         }
     }
     SdkSettings.onApiTokenRejected = {
         showDialog("TOKEN REJECTED")
     }
     requestPermissions(this)
     if (!Util.isInternetConnected(this))
     {
         showDialog("You must be connected to the internet!")
     }
}

The onCreate() function is overridden in the MainActivity: AppCompatActivity() class, and checks if internet access is available, showing a dialog message if not.
findViewById() is used to obtain pointers to the various graphical user interface elements where text or graphical data is to be displayed.
When the map is loaded, SdkSettings.onMapDataReady = { follow position is activated so the camera follows the position of the device (in case it is in a car in motion, for example):
gemSurfaceView.mapView?.followPosition()
A function is called to wait until the first good quality position of the device is received from the position sensor, such as GPS: waitForNextImprovedPosition {
When a good position has been obtained, the social report is sent automatically: submitReport()

private fun waitForNextImprovedPosition(onEvent: (() -> Unit))
{
     positionListener = PositionListener {
         if (it.isValid())
         {
             Util.postOnMain { showStatusMessage("On valid position") }
             onEvent()
             PositionService.removeListener(positionListener)
         }
     }
     PositionService.addListener(positionListener, EDataType.ImprovedPosition)
     // listen for first valid position to start the nav
     Util.postOnMain { showStatusMessage("Waiting for valid position", true) }
}

The PositionListener instance is created and added to the PositionService.addListener() to be called when a good position EDataType.ImprovedPosition is received from the GPS sensor. When that happens, the function passed in is called automatically, that is, the onEvent() parameter, which is submitReport().
In this case, causing the social report to be sent upon reading the first valid device position from the sensor.

private fun submitReport() = SdkCall.execute
{
     val overlayInfo = SocialOverlay.reportsOverlayInfo ?: return@execute
     val countryISOCode = MapDetails().isoCodeForCurrentPosition ?: return@execute
     val categories = overlayInfo.getCategories(countryISOCode) ?: return@execute
     val mainCategory = categories[0] // Police
     val subcategories = mainCategory.subcategories ?: return@execute
     val subCategory = subcategories[0] // My side
     val prepareIdOrError = SocialOverlay.prepareReporting()
     if (prepareIdOrError <= 0)
     {
         val errorMsg = if (prepareIdOrError == GemError.NotFound
         || prepareIdOrError == GemError.Required)
         {
             "Prepare error: ${GemUtil.getUIString(EStringIds.eStrGPSAccuracyIsNotGoodEnough)}"
         }
         else
         {
             "Prepare error: ${GemError.getMessage(prepareIdOrError)}"
         }
         Util.postOnMain { showDialog(errorMsg) }
         return@execute
     }
     val error = SocialOverlay.report(prepareIdOrError, subCategory.uid, socialReportListener)
     if (GemError.isError(error))
     {
         Util.postOnMain { showDialog("Report Error: ${GemError.getMessage(error)}") }
     }
     else
     {
         Util.postOnMain { showStatusMessage("Report Sent!") }
     }
}

The submitReport() function creates the report: val prepareIdOrError = SocialOverlay.prepareReporting() and if this fails, an error message is displayed in a dialog box.
Otherwise, the report, stored in prepareIdOrError is sent:
val error = SocialOverlay.report(prepareIdOrError, subCategory.uid, socialReportListener)
If sending fails, a dialog box is displayed, otherwise, a status message indicating that the report was sent is displayed at the bottom of the viewport.

Android Examples

Maps SDK for Android Examples can be downloaded or cloned with Git.