Merge pull request SharePoint#7781 from SidGulatiMsft/geolocationDocumentation

Documentation for geolocation action in Adaptive Card Extension

Author: andrewconnell

docs/images/viva-extensibility/geolocation/geoloactionAppIcon.png

@@ -0,0 +1,179 @@
+---
+title: Location capabilities in Adaptive Card Extension
+description: Geolocation is a new action that the SharePoint Adaptive Card Extension framework supports, which enables third party developers to come up with their ___location specific scenarios.
+ms.date: 04/06/2022
+ms.prod: sharepoint
+ms.localizationpriority: high
+---
+# Location capabilities in Adaptive Card Extension
+
+> [!NOTE]
+> The geolocation capability in Adaptive Card Extension will be available in SPFx v1.15.
+> 
+> So make sure that you have installed it before proceeding further.
+> 
+> For more information on installing the SPFx v1.15 Preview, see [SharePoint Framework v1.15 release notes](../../../../release-1.15.md).
+> 
+> This tutorial also assumes that you have already built a SharePoint Adaptive Card Extension.
+> 
+> To learn how to create your first SharePoint Adaptive Card Extension, try out [this tutorial](../../../get-started/build-first-sharepoint-adaptive-card-extension.md).
+
+### New action types for geolocation
+
+There are 2 Location actions:
+
+1. Get Location
+1. Show Location
+
+### Get Location:
+
+Gives user’s current device ___location or opens a ___location picker and returns the ___location chosen by the user. In the browser it uses Bing Maps as the mapping interface.
+
+The ACE action for Get Location is: `VivaAction.GetLocation`.
+
+It takes an optional boolean parameter: `ChooseLocationOnMap`.
+
+If the property `ChooseLocationOnMap` is set to `true`, then the action will open a map, and user will get to choose a ___location on the map, otherwise, it will fetch user's current device ___location.
+
+### Show Location:
+
+With this action, a map shows up on the screen on which you can either show the user's current ___location on the map or you can show your specified coordinates on the map.
+
+The ACE action for Show Location is: `VivaAction.ShowLocation`.
+
+It takes an optional ___location parameter: `locationCoordinates`.
+
+To show a specific ___location, you should pass the ___location coordinates (latitude and longitude) via the `locationCoordinates` parameter.
+
+The `locationCoordinates` object consists of the following properties:
+
+```typescript
+{
+  /**
+   * 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](./GeolocationTutorial.md) 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.
+
+1. **Get user's current ___location**
+
+    In your template JSON, introduce the following action:
+
+    ```json
+    "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. 
+
+1. **Select ___location from a map**
+
+    In your template JSON, introduce the following action:
+    
+    ```json
+    "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.
+
+1. **Display user's current ___location**
+
+    In your template JSON, introduce the following action:
+    
+    ```json
+    "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.
+
+1. **Display a specified ___location**
+
+    In your template JSON, introduce the following action:
+    
+    ```json
+    "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](./GeolocationPropertyPane.md) which lets you create cards with geolocation actions via property pane.
+
+> [!NOTE]
+> Theses geolocation actions can be added on the card view or the buttons of the card view or inside the quick view.
+
+### Permission and error codes
+
+For the ___location APIs to work, the user has to grant the 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
+
+> [!NOTE]
+> These new actions are **only available in the browser** currently. Viva Connections desktop and Viva Connections mobile support will be enabled later.
+After General Availability the support matrix for actions will look like:
+
+Action       | Viva Connection Desktop | Viva Connections Mobile | Browser
+------------- | ------------- | ------------- | -------------
+Get Location  | Not Supported | Supported | Supported
+Show Location | Not Supported | Supported | Supported

docs/images/viva-extensibility/geolocation/geoloactionCardView.png

@@ -0,0 +1,71 @@
+---
+title: Explore Geolocation capability via property pane of card-desinger card in Adaptive Card Extension
+description: Geolocation is a new action that the SharePoint Adaptive Card Extension framework supports, and in this tutorial we see how we can explore this capability via the property pane of the card-designer card.
+ms.date: 04/06/2022
+ms.prod: sharepoint
+ms.localizationpriority: high
+---
+
+# Explore Geolocation capability via property pane of card-desinger card in Adaptive Card Extension
+
+In this tutorial we will see how we can use the card-designer card's property pane to explore geolocation actions.
+
+We will:
+
+- Update the card strings
+- Introduce geolocation actions on the Card View, Primary button and Secondary button
+
+First, figure out the ___domain to the URL of your SharePoint tenant and site you want to use for testing and access the `workbench.aspx` page. For example: `https://contoso.sharepoint.com/sites/devsite/_layouts/workbench.aspx`.
+
+Here, click on the '+' icon in the middle of the page, and add the `card-designer` card on the canvas.
+
+Next, click the pencil icon adjacent to this card to open the property pane.
+
+### Update the card strings
+
+Here, first set the `card size` to `Large`.
+
+To provide descriptive labels, change `Title` to `GeoLocation`, `Heading` to `GeoLocation Demo` and `description` to `Demo GeoLocation Actions`. 
+
+![Adding strings in the property pane of card designer card](../../../../../../docs/images/viva-extensibility/geolocation/geoloactionPropertyPaneStrings.png)
+
+### Adding action on Card View
+
+Under `Actions`, click the drop-down menu of `card action` and select `Select ___location from a map` option.
+
+![Set the on-click action to "Select ___location from a map" from the drop-down menu of card-view](../../../../../../docs/images/viva-extensibility/geolocation/geoloactionPropertyPaneCardAction.png)
+
+### Adding action on Primary button
+
+Next, for the `Primary Button`, set the `Title` to `My Location` and from its action drop-down menu, select `Display a specified or current ___location`.
+
+![Set the on-click action to "Display a specified or current ___location" from the drop-down menu for the primary button](../../../../../../docs/images/viva-extensibility/geolocation/geoloactionPropertyPanePrimaryButtonAction.png)
+
+### Adding action on Secondary button
+
+Finally, for the `Secondary Button`, set the `Title` to `Custom Location` and from its action drop-down menu, select `Display a specified or current ___location`.
+
+Next, turn on the `Display a specified ___location` toggle button.
+
+This will bring up two text boxes for ___location coordinates.
+
+Here you may provide any ___location coordinates of your choice.
+
+For our example, we are putting in `27.98884062493244` as the value for the text-box labeled `latitude` and `86.9249751` for the text-box labeled `longitude`. These are the coordinates of Mount Everest.
+
+![Set the on-click action to "Display a specified or current ___location" from the drop-down menu for the secondary button and pass coordinates of your choice in the respective ___location text-boxes](../../../../../../docs/images/viva-extensibility/geolocation/geoloactionPropertyPaneSecondaryButtonAction.png)
+
+### Try the geolocation actions
+
+Now close the property pane and click `Preview` from the top right hand corner of the page:
+
+- Click on the card itself to select a ___location from the map
+- Clicking on `My ___location` will open a map showing your current ___location
+- Clicking on `Show custom ___location` will open a map showing your custom ___location (Mount Everest)
+
+You can now check out the three geolocation actions that you introduced via the property pane. 
+
+![Card-Designer card with geolocation actions configured](../../../../../../docs/images/viva-extensibility/geolocation/geoloactionPropertyPaneCardGenerated.png)
+
+> [!NOTE]
+> This property-pane experience doesn't allow you to introduce onAction callback, and hence the action `Select ___location from a map` is actually a no-op.