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
- The Request Permissions prompt is automatically displayed when a relevant Teams API is initiated. For more information, see request device permissions.
- Device permissions are different in the browser. For more information, see browser device permissions.
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:

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
Зворотний зв’язок
Надіслати й переглянути відгук про