Get Location Action

The action module for this action is "vb/action/builtin/geolocationAction".

This action provides a declarative access to geographical location information associated with the hosting device. This action requires the user's consent. As a best practice, it should only be fired on a user gesture. Doing so will allow users to more easily associate the system permission prompt for access with the action they just initiated.

Parameter Name	Description
maximumAge	A positive long value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity, the device must return a cached position regardless of its age.
timeout	A positive long value representing the maximum length of time, in milliseconds, that the device is allowed to take in order to return a position. The default value is Infinity, meaning that getCurrentPosition() won't return until the position is available.
enableHighAccuracy	A boolean that indicates the application would like to receive the best possible results. If true, and if the device is able to provide a more accurate position, it will do so. This can result in slower response times or increased power consumption. If false (the default value), the device can save resources by responding more quickly or using less power. On mobile devices, enableHighAccuracy should be set to true in order to use GPS sensors.

If the geolocation API is supported in the browser, geolocationAction returns a JSON Position object that represents the position of the device at a given time.

Return Type	Description	Example
Object	The Position interface represents the position of the concerned device at a given time. The position, represented by a Coordinates object, comprehends the 2D position of the device, on a spheroid representing the Earth, but also its altitude and its speed. Position.coords returns a Coordinates object defining the current location. Position.timestamp returns a DOM timestamp representing the time at which the location was retrieved.	Latitude and longitude can be accessed from the Position's coordinates as follows: [[$chain.results.getCurrentLocation.coords.latitude ]] [[$chain.results.getCurrentLocation.coords.longitude ]] where getCurrentLocation is a geolocationAction.

If geolocation is not supported by the browser, or a parameter with a wrong type is detected, a failure outcome is returned. If a PositionError occurs when obtaining geolocation, a failure outcome with a PositionError.code payload is returned. Possible PositionError.code values are:

• PositionError.PERMISSION_DENIED
• PositionError.POSITION_UNAVAILABLE
• PositionError.TIMEOUT

For every failure, a descriptive error message can be obtained from the action chain, such as [[ $chain.results.getCurrentLocation.error.message ]].

An example of using the geolocation action:

"chains": {
  "getCurrentLocation": {
    "root": "geolocation1",
    "description": "",
    "actions": {
      "geolocation1": {
        "module": "vb/action/builtin/geolocationAction",
        "parameters": {
          "timeout": 50000,
          "maximumAge": "{{Infinity}}"
        },
        "outcomes": {
          "failure": "fireNotification1",
          "success": "assignVariables1"
        }
      },
      "fireNotification1": {
        "module": "vb/action/builtin/fireNotificationEventAction",
        "parameters": {
          "summary": "[[ $chain.results.geolocation1.error.message ]]",
          "type": "error",
          "displayMode": "persist"
        }
      },
      "assignVariables1": {
        "module": "vb/action/builtin/assignVariablesAction",
        "parameters": {
          "$page.variables.coords": {
            "source": "{{ $chain.results.geolocation1.coords }}",
            "auto": "always"
          }
        }
      }
    }
  }
},