Through broker.location.*services, users have control and access to the GPS of the device.

Interaction with GPS

Mat|r offers Location data type as an integrated model:

Model Location {
  Double latitude
  Double longitude
}

along with a group of services grouped in location namespace, invoking broker.location.* from Mat|r script.

PUBLIC METHODS

Bool broker.location.hasGPS()

Return  
Bool It returns true if the device has a GPS. Otherwise, it returns false.

Bool broker.location.hasGPSAccess()

Return  
Bool It returns true if the user accepts to give location permission to the app. It returns false if the user doesn’t give permission or doesn’t have a GPS. If this method is executed for the first time, the user is asked to give permission.

void broker.location.start()

It initiates the native location manager. If this method is executed for the first time, the user is asked to give permissions. If the user gives permissions, the service starts. If the service fails, an exception is thrown. If the start()method is executed for the first time, it does not throw an exception. The method is blocking until the user gives or rejects permissions.

Exceptions
DeviceWithoutGPS – The device has no GPS.
LocationServiceAccessDenied – Error trying to access GPS without permission.

void broker.location.stop()

It stops the native location manager service. If the stop() method is executed more than once, it throws an exception. If the user wants to execute the stop method without invoking the start method before, it does not throw an exception either.

Excepciones
DeviceWithoutGPS – The device has no GPS.
LocationServiceAccessDenied – Error trying to access GPS without permission.

Bool broker.location.isReady()

Return  
Bool It returns true if the service has already obtained an update of a valid position. This means that the getLocation call
will return a Location immediately.  
Exceptions
DeviceWithoutGPS – The device has no GPS.
LocationServiceAccessDenied – Error trying to access GPS without permission.

Double broker.location.calculateDistance(Location a, Location b)

This method measures the distance between the two locations arguments, taking into consideration the curvature of the Earth. Returns the distance, measured in meters.

Arguments  
a Location: geolocalized coordinates.
b Location: geolocalized coordinates.
Returns
Double Returns the distance, measured in meters.

Location broker.location.getLocation()

It obtains and returns the current position obtained by the GPS of the device. The call is blocking until the service gets a valid position or it finishes due to timeout, throwing an exception. During the time it takes to answer the call, a “loading” image will be shown, similar to the one shown when there is a call on hold.

Return  
Location This method returns a Location model of the position obtained by the GPS.
Exceptions
DeviceWithoutGPS – The device has no GPS.
LocationServiceAccessDenied – Error trying to access GPS without permission.
LocationServiceNotStarted – The service location is stopped.
BrokerServiceTimeout – Timeout when executing broker service: ‘getLocation’

Example:

Experience MyLocation {
    Decision startBtn action("MainContext.hasGPS") label("HAS GPS?")
    Decision getLocation action("MainContext.getLocation") label("GET USER LOCATION")
}

Application {
   onInit {
        try {
            broker.location.start()
        } catch (e) {
            broker.ui.showAlert("Error", e.reason())
        }
    }
}

RuleContext MainContext {

    Rule hasGPS {
        try {
            Bool hasGPS = broker.location.hasGPS()
            broker.ui.showAlert("Location", "Has GPS: " + hasGPS.toString())
        } catch (e) {
            broker.ui.showAlert("Error", e.reason())
        }
    }

    Rule getLocation {
        try {
            Location userLoc = broker.location.getLocation()
            broker.ui.showAlert("Device Location", "(" + userLoc.latitude + ","+ userLoc.longitude + ")")
        } catch (e) {
            broker.ui.showAlert("Error", e.reason())
        }
    }
}