Location capabilities in Adaptive Card Extension

Article
01/18/2024

Microsoft added support for two geolocation actions, unique to Viva Connections, in the SharePoint Framework (SPFx) v1.15 release.

Important

This tutorial also assumes that you've already built an SPFx Adaptive Card Extension.

To learn how to create your first an SPFx Adaptive Card Extension, try out this tutorial.

New action types for geolocation

There are 2 Location actions:

Get Location
Show Location

Get Location

The VivaAction.GetLocation action takes user’s current device location or opens a location picker and returns the location chosen by the user. The Viva Connections browser client uses Bing Maps for the mapping experience:

{
  "id": "originLocation",
  "type": "VivaAction.GetLocation",
  "title": "Select location on the map",
  "parameters": {
    "chooseLocationOnMap": true
  }
}

When the optional parameter property ChooseLocationOnMap is set to true, the action will open a map, and user will get to choose a location on the map. If set to false (the default setting), it will fetch user's current device location.

Show Location

The VivaAction.ShowLocation action displays a map that displays the user's current location on the map or a specified location:

{
  action: {
    type: 'VivaAction.ShowLocation',
    parameters: {
      locationCoordinates: {
        latitude: 28.6132039578389,
        longitude: 77.229488240066
      }
    }
  }
}

It takes an optional location parameter: locationCoordinates.

To show a specific location, set the optional locationCoordinates property the location coordinates (latitude and longitude).

The locationCoordinates object consists of the following properties:

{
  /**
   * Latitude of the location.
   */
  latitude: number;

  /**
   * Longitude of the location.
   */
  longitude: number;

  /**
   * Timestamp (optional).
   */
  timestamp?: number;

  /**
   * Accuracy of the location (optional).
   */
  accuracy?: number;
}

Tutorial and Examples

You can take a look at this tutorial which goes over the step by step details of how you could create a card with geolocation actions.

The following examples describe the geolocation action and their purpose.

Get user's current location

In your template JSON, introduce the following action:
```
"actions": [{
  type: 'VivaAction.GetLocation',
  id: 'Get Location'
}]
```
When this action gets invoked, user's current geolocation is fetched and is passed to the Third Party Developer via the onAction callback.

Note

In this case, map doesn't show up.
Select location from a map

In your template JSON, introduce the following action:
```
"actions": [{
  type: 'VivaAction.GetLocation',
  id: 'Get Location',
  parameters: {chooseLocationOnMap: true}
}]
```
When this action gets invoked, a map pointing to user's current location opens up and the user gets to select and share the location of their choice. The selected location's coordinates are passed to the Third Party Developer via the onAction callback.
Display user's current location

In your template JSON, introduce the following action:
```
"actions": [{
  type: 'VivaAction.ShowLocation',
  id: 'Show Location'
}]
```
When this action gets invoked, a map opens up and the user's current location coordinates are shown on it.

Display a specified location

In your template JSON, introduce the following action:

"actions": [{
  type: 'VivaAction.ShowLocation',
  id: 'Show Location',
  parameters: {
    locationCoordinates: {
      latitude: 28.6132039578389,
      longitude: 77.229488240066
    }
  }
}]

When this action gets invoked, a map opens up and it shows the location coordinates specified in the action.

Access geolocation actions via card-designer card's property pane

If you don't want to write code, but still wish to see how the geolocation actions work, then you can explore this tutorial which lets you create cards with geolocation actions via property pane.

Note

Theses geolocation actions can be added on the CardView or the buttons of the CardView or inside the QuickView.

Permission and error codes

For the location APIs to work, the user must grant the browser permission to access device's location.

Error Code	Error Description
PermissionDenied	User has denied the permission to access location
InternalError	An unexpected error happened while invoking the location APIs
HostNotSupported	The location action is being used in an unsupported environment

Callbacks for Card Developers

When the action VivaAction.GetLocation is invoked, we pass the fetched location coordinates via the onAction callback.

Note

onAction callback is not invoked for VivaAction.ShowLocation.

For actions: VivaAction.GetLocation and VivaAction.ShowLocation, if the user lands into an error state, then an onError callback will get invoked, to which we pass the action name and the error code.

Availability of geolocation actions

The support matrix for location capabilities in Viva Connections is the following:

Action	Teams Desktop and Web	Teams Mobile	SharePoint (browser)
Get Location	Not Supported	Supported	Supported
Show Location	Not Supported	Supported	Supported

Share via