Integrate location capabilities

You can integrate the location capabilities of native device with your Teams app.

You can use Microsoft Teams JavaScript client SDK, which provides the tools necessary for your app to access the user’s native device capabilities. Use the location APIs, such as getLocation and showLocation to integrate the capabilities within your app.

Note

This topic reflects version 2.0.x of the Microsoft Teams JavaScript client SDK. If you are using an earlier version, refer to the Teams JS SDK overview for guidance on the differences between the latest TeamsJS and earlier versions.

Advantages of integrating location capabilities

The main advantage of integrating location capabilities in your Teams apps is that it allows web app developers on Teams platform to leverage location functionality with Microsoft Teams JavaScript client SDK.

Following examples show how the integration of location capabilities is used in different scenarios:

  • In a factory, the supervisor can track the attendance of workers by asking them to take a selfie in the vicinity of the factory and share it through the specified app. The location data also gets captured and sent along with the image.
  • The location capabilities enable the maintenance staff of a service provider to share authentic health data of cellular towers with the management. The management can compare any mismatch between captured location information and the data submitted by maintenance staff.

To integrate location capabilities, you must update the app manifest file and call the APIs. For effective integration, you must have a good understanding of code snippets for calling the location APIs. It's important to familiarize yourself with the API response errors to handle the errors in your Teams app.

Note

Currently, Microsoft Teams supports for location capabilities is available for mobile clients only.

Update manifest

Update your Teams app manifest.json file by adding the devicePermissions property and specifying geolocation. It allows your app to ask for requisite permissions from users before they start using the location capabilities. The update for app manifest is as follows:

"devicePermissions": [
    "geolocation",
],

Note

Location APIs

You must use the following set of APIs to enable your device's location capabilities:

API Description
getLocation Gives user’s current device location or opens native location picker and returns the location chosen by the user.
showLocation Shows location on map.

Note

The getLocation() API comes along with following input configurations, allowChooseLocation and showMap.
If the value of allowChooseLocation is true, then the users can choose any location of their choice.
If the value is false, then the users cannot change their current location.
If the value of showMap is false, the current location is fetched without displaying the map. showMap is ignored if allowChooseLocation is set to true.

The following image depicts web app experience of location capabilities:

web app experience for location capabilities

Code snippets

Calling getLocation API to retrieve the location:

import {location} from "@microsoft/teams-js"

let locationProps = {"allowChooseLocation":true,"showMap":true};
if(location.isSupported()) {
    const locationPromise = location.getLocation(locationProps);
    locationPromise.
        then((result) => {output(JSON.stringify(result));}.
        catch((error) => {output(error);});
}
else {/*Handle case where capability isn't supported */}

Calling showLocation API to display the location:

import {location} from "@microsoft/teams-js"

let location = {"latitude":17,"longitude":17};
if(location.isSupported()) {
    const locationPromise = location.showLocation(location);
    locationPromise.
         then((result) => {/*Successful map display*/}).
         catch((error) => {/*Failed map display*/});
}
else {/*Handle case where capability isn't supported */}

Error handling

You must ensure to handle these errors appropriately in your Teams app. The following table lists the error codes and the conditions under which the errors are generated:

Error code Error name Condition
100 NOT_SUPPORTED_ON_PLATFORM API isn't supported on the current platform.
500 INTERNAL_ERROR Internal error is encountered while performing the required operation.
1000 PERMISSION_DENIED User denied location permissions to the Teams App or the web-app.
4000 INVALID_ARGUMENTS API is invoked with wrong or insufficient mandatory arguments.
8000 USER_ABORT User cancelled the operation.
9000 OLD_PLATFORM User is on old platform build where implementation of the API isn't present. Upgrading the build should resolve the issue.

Code sample

Sample name Description C# Node.js
App check-in current location Users can check-in the current location and view all the previous location check-ins. View View

See also