Using geolocation in an Adaptive Card Extension

Introduction

Today I want to disclose how to use the geolocation actions in an Adaptive Card Extension.

Since the release of SPFx 1.14 it’s possible to use the location of the user’s device. The specific geolocation actions will be used either to retrieve the device location or to display a location on the map.

This article idea comes from a tutorial on Microsoft learn that you can find here.

As usual I’ve prepared a sample solution. If you want to go straight to the code you can find it here.

Starting with the resulting UI the card view will looks like the following:

Once opened the quick view there are the latitude and longitude of the selected location and three different buttons:

The buttons actions are:

• Choose location: will enable the user to select a location. Once selected the location and pressed the button, the latitude and longitude text will be updated.
• Get my location: will update the latitude and longitude using the device’s current coordinates.
• Show pre-defined location: will show a location defined in the code.

The first time a user clicks on one of those buttons, if not already given, the browser will request permission to use the device location:

When the user clicks on the buttons, except for the Get my location one, a dialog with a map will be shown.

In case of the Choose location button it will be possible to select a place on the map and then, after pressing the share location button, the latitude and longitude will be updated.

On the other hand, the Show pre-defined location button, will only show a map with a pre-defined pin that will not be updatable.

The Get my location button will retrieve the device location but, instead of showing the map, will only update the latitude and longitude labels.

Enough for the UI aspects, let’s dive into the code!

Show me the code

This ACE has been created using the generic card template.

This post is not meant to instruct you how to create an ACE. If you’re interested on getting started you can check my previous article here.

The geolocation that you have seen in the introductory section of this post is mostly in charge of the ACE’s quick view.

In the template we’re using the actions of type VivaAction to define which of the geolocation functions we want to use. There are two possibilities at the time of writing, and those are:

• VivaAction.GetLocation: this action will get the location of the device that’s currently opening the quick view.
• VivaAction.ShowLocation: this action will show a location based on the latitude and longitude specified in the JSON properties.

Just to have an idea of the JSON template for the quick view here is the full code:

{
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
        "type": "TextBlock",
        "text": "${description}"
    },
    {
        "type": "TextBlock",
        "text": "${latitude}"
    },
    {
        "type": "TextBlock",
        "text": "${longitude}"
    }
  ],
  "actions": [
    {
      "title": "${chooseLocationOnMap}",
      "type": "VivaAction.GetLocation",
      "parameters": {
        "chooseLocationOnMap": true
      }
    },
    {
      "title": "${getMyLocation}",
      "type": "VivaAction.GetLocation"
    },
    {
      "title": "${customLocation}",
      "type": "VivaAction.ShowLocation",
      "parameters": {
        "locationCoordinates": {
          "latitude": 41.89064893895296,
          "longitude": 12.492303960531942
        }
      }
    }
  ]
}

Now let’s cover in detail the geolocation actions!

VivaAction.GetLocation

As said before this action will get the location of the device. To use this you have, of course, to allow the browser to access the location.

To use the action in the JSON of the quick view simply define it in the following fashion:

{
  "title": "${getMyLocation}",
  "type": "VivaAction.GetLocation"
}

This is the basic use of the action. If you want to allow the user to select the location on the map you will have to specify the parameter chooseLocationOnMap and set it to true:

{
  "title": "${chooseLocationOnMap}",
  "type": "VivaAction.GetLocation",
  "parameters": {
    "chooseLocationOnMap": true
  }
}

VivaAction.ShowLocation

As said before this action will show a point on the map. To define which is the location to be displayed you will need to set the latitude and longitude properties as following:

{
  "title": "${customLocation}",
  "type": "VivaAction.ShowLocation",
  "parameters": {
    "locationCoordinates": {
      "latitude": 41.89064893895296,
      "longitude": 12.492303960531942
    }
  }
}

Hint

If you’re in Teams and cannot see the dialogs with the map, or if the get my location doesn’t retrieve any values for latitude and longitude, it might be a permission problem.

If it’s your case it might be that you have not given the right permissions to the Viva Connections application.

To give the permission to access the location, in Teams, open the settings and select App permissions :

Once opened the App permissions scroll down until you find Viva Connections and enable the location toggle:

Conclusions

Using the device’s geolocation is an easy task with the VivaAction actions. Those actions can be very useful if you need to allow your user to perform some location selection or if you want to show a specific location to the user.

Hope this helps!