Merge pull request #74107 from mikematteson/azure-maps-new-articles-batch

ShawnJackson · web-flow · commit c92b3a775c67 · 2019-04-23T09:55:53.000-05:00
Edit pass: azure-maps-new-articles-batch
diff --git a/articles/azure-maps/how-to-use-services-module.md b/articles/azure-maps/how-to-use-services-module.md
@@ -1,5 +1,5 @@
 ---
-title: Using the Services module - Azure Maps | Microsoft Docs
+title: Use the services module - Azure Maps | Microsoft Docs
 description: Learn how to use the Azure Maps services module.
 author: rbrundritt
 ms.author: richbrun
@@ -10,88 +10,89 @@ services: azure-maps
 manager: cpendleton
 ---
 
-# Using the Azure Maps Services module
+# Use the Azure Maps services module
 
-The Azure Maps Web SDK provides a services module that is a helper library that makes it easy to use the Azure Maps REST services in web or Node.js applications using JavaScript or TypeScript.
+The Azure Maps Web SDK provides a *services module*. This module is a helper library that makes it easy to use the Azure Maps REST services in web or Node.js applications by using JavaScript or TypeScript.
 
-## Using the services module in a web page
+## Use the services module in a webpage
 
 1. Create a new HTML file.
-2. Load in the Azure Maps Services module. This can be done using one of two options;
+1. Load the Azure Maps services module. You can load it in one of two ways:
+    - Use the globally hosted, Azure Content Delivery Network version of the Azure Maps services module. Add a script reference to the `<head>` element of the file:
 
-    a. Use the globally hosted CDN version of the Azure Maps services module by adding a script reference to the `<head>` element of the file:
-    
-	```html
-	<script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas-service.min.js"></script>
-	```
-    
-    b. Alternatively, load the Azure Maps Web SDK source code locally using the [azure-maps-rest](https://www.npmjs.com/package/azure-maps-rest) NPM package and host it with your app. This package also includes TypeScript definitions.
-    
-	> npm install azure-maps-rest
+        ```html
+        <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas-service.min.js"></script>
+        ```
+
+    - Alternatively, load the Azure Maps Web SDK source code locally by using the [azure-maps-rest](https://www.npmjs.com/package/azure-maps-rest) npm package, and then host it with your app. This package also includes TypeScript definitions. Use this command:
     
-    Then add a script reference to the `<head>` element of the file:
+        > **npm install azure-maps-rest**
     
-	```html
-	<script src="node_modules/azure-maps-rest/dist/js/atlas-service.min.js"></script>
-	```
+        Then, add a script reference to the `<head>` element of the file:
 
-3. To initialize a service URL client endpoint, you must first create an authentication pipeline. Use your own Azure Maps account key or Azure Active Directory (AAD) credentials to authenticate the search service client. In this example, the search service URL client will be created. If using a subscription key for authentication:
+         ```html
+        <script src="node_modules/azure-maps-rest/dist/js/atlas-service.min.js"></script>
+         ```
+
+1. Create an authentication pipeline. You must create the pipeline before you can initialize a service URL client endpoint. Use your own Azure Maps account key or Azure Active Directory (Azure AD) credentials to authenticate an Azure Maps Search service client. In this example, the Search service URL client will be created. 
+
+    If you use a subscription key for authentication:
 
     ```javascript
-    //Get an Azure Maps key at https://azure.com/maps
+    // Get an Azure Maps key at https://azure.com/maps.
     var subscriptionKey = '<Your Azure Maps Key>';
-    
-    //Use SubscriptionKeyCredential with a subscription key.
+
+    // Use SubscriptionKeyCredential with a subscription key.
     var subscriptionKeyCredential = new atlas.service.SubscriptionKeyCredential(subscriptionKey);
-    
-    //Use subscriptionKeyCredential to create a pipeline.
+
+    // Use subscriptionKeyCredential to create a pipeline.
     var pipeline = atlas.service.MapsURL.newPipeline(subscriptionKeyCredential, {
       retryOptions: { maxTries: 4 } // Retry options
     });
-    
-    //Create an instance of the SearchURL client.
+
+    // Create an instance of the SearchURL client.
     var searchURL = new atlas.service.SearchURL(pipeline);
     ```
-    
-    If using Azure Active Directory (AAD) for authentication:
+
+    If you use Azure AD for authentication:
 
     ```javascript
-    // Enter your Azure Actiuve Directory client ID.
+    // Enter your Azure AD client ID.
     var clientId = "<Your Azure Active Directory Client Id>";
-    
-    // Use TokenCredential with OAuth token (AAD or Anonymous).
+
+    // Use TokenCredential with OAuth token (Azure AD or Anonymous).
     var aadToken = await getAadToken();
     var tokenCredential = new atlas.service.TokenCredential(clientId, aadToken);
-    
-    // Create a repeating timeout that will renew the AAD token.
-    // This timeout must be cleared once the TokenCredential object is no longer needed.
-    // If the timeout is not cleared the memory used by the TokenCredential will never be reclaimed.
+
+    // Create a repeating time-out that will renew the Azure AD token.
+    // This time-out must be cleared when the TokenCredential object is no longer needed.
+    // If the time-out is not cleared, the memory used by the TokenCredential will never be reclaimed.
     var renewToken = async () => {
-		try {
-			console.log("Renewing token");
-			var token = await getAadToken();
-			tokenCredential.token = token;
-			tokenRenewalTimer = setTimeout(renewToken, getExpiration(token));
-		} catch (error) {
-			console.log("Caught error when renewing token");
-			clearTimeout(tokenRenewalTimer);
-			throw error;
-		}
+    try {
+      console.log("Renewing token");
+      var token = await getAadToken();
+      tokenCredential.token = token;
+      tokenRenewalTimer = setTimeout(renewToken, getExpiration(token));
+    } catch (error) {
+      console.log("Caught error when renewing token");
+      clearTimeout(tokenRenewalTimer);
+      throw error;
+    }
     }
     tokenRenewalTimer = setTimeout(renewToken, getExpiration(aadToken));
-    
-    // Use tokenCredential to create a pipeline
+
+    // Use tokenCredential to create a pipeline.
     var pipeline = atlas.service.MapsURL.newPipeline(tokenCredential, {
-		retryOptions: { maxTries: 4 } // Retry options
+    retryOptions: { maxTries: 4 } // Retry options
     });
-    
-    //Create an instance of the SearchURL client.
+
+    // Create an instance of the SearchURL client.
     var searchURL = new atlas.service.SearchURL(pipeline);
 
     function getAadToken() {
-        //Use the logged in auth context to get a token.
+        // Use the signed-in auth context to get a token.
         return new Promise((resolve, reject) => {
-            //The resource should always be https://atlas.microsoft.com/.
+            // The resource should always be https://atlas.microsoft.com/.
             const resource = "https://atlas.microsoft.com/";
             authContext.acquireToken(resource, (error, token) => {
                 if (error) {
@@ -104,51 +105,51 @@ The Azure Maps Web SDK provides a services module that is a helper library that
     }
 
     function getExpiration(jwtToken) {
-        //Decode the JWT token to get the expiration timestamp.
+        // Decode the JSON Web Token (JWT) to get the expiration time stamp.
         const json = atob(jwtToken.split(".")[1]);
         const decode = JSON.parse(json);
 
-        //Return the milliseconds until the token needs renewed.
-        //Reduce the time until renew by 5 minutes to avoid using an expired token.
-        //The exp property is the timestamp of the expiration in seconds.
+        // Return the milliseconds remaining until the token must be renewed.
+        // Reduce the time until renewal by 5 minutes to avoid using an expired token.
+        // The exp property is the time stamp of the expiration, in seconds.
         const renewSkew = 300000;
         return (1000 * decode.exp) - Date.now() - renewSkew;
     }
     ```
 
     For more information, see [Authentication with Azure Maps](azure-maps-authentication.md).
 
-4. The following code uses the newly created search service URL client to geocode an address, "1 Microsoft Way, Redmond, WA" using the `searchAddress` function and display the results as a table in the body of the page. 
+1. The following code uses the newly created Azure Search service URL client to geocode an address: "1 Microsoft Way, Redmond, WA". The code uses the `searchAddress` function and displays the results as a table in the body of the page.
 
     ```javascript
-    //Search for "1 microsoft way, redmond, wa".
+    // Search for "1 microsoft way, redmond, wa".
     searchURL.searchAddress(atlas.service.Aborter.timeout(10000), '1 microsoft way, redmond, wa').then(response => {
       var html = [];
-      
-      //Display the total results.
+
+      // Display the total results.
       html.push('Total results: ', response.summary.numResults, '<br/><br/>');
-     
-      //Create a table of the results.
+
+      // Create a table of the results.
       html.push('<table><tr><td></td><td>Result</td><td>Latitude</td><td>Longitude</td></tr>');
-      
+
       for(var i=0;i<response.results.length;i++){
         html.push('<tr><td>', (i+1), '.</td><td>', 
-					response.results[i].address.freeformAddress, 
-					'</td><td>', 
-					response.results[i].position.lat,
-					'</td><td>', 
-					response.results[i].position.lon,
-					'</td></tr>');
+          response.results[i].address.freeformAddress, 
+          '</td><td>', 
+          response.results[i].position.lat,
+          '</td><td>', 
+          response.results[i].position.lon,
+          '</td></tr>');
       }
-      
+
       html.push('</table>');
-      
-      //Add the result HTML to the body of the page.
+
+      // Add the resulting HTML to the body of the page.
       document.body.innerHTML = html.join('');
     });
     ```
 
-    Here is the fully running code sample:
+    Here's the full, running code sample:
 
 <br/>
 
@@ -176,7 +177,7 @@ Learn more about the classes and methods used in this article:
 > [!div class="nextstepaction"]
 > [TokenCredential](https://docs.microsoft.com/javascript/api/azure-maps-rest/atlas.service.tokencredential?view=azure-iot-typescript-latest)
 
-See the following articles for more code samples that use the services module:
+For more code samples that use the services module, see these articles:
 
 > [!div class="nextstepaction"]
 > [Show search results on the map](./map-search-location.md)
diff --git a/articles/azure-maps/supported-browsers.md b/articles/azure-maps/supported-browsers.md
@@ -12,43 +12,43 @@ manager: cpendleton
 
 # Web SDK supported browsers
 
-The Azure Maps Web SDK provides a helper function [atlas.isSupported](https://docs.microsoft.com/javascript/api/azure-maps-control/atlas?view=azure-iot-typescript-latest#issupported-boolean-) to detect if a web browser has the minimum required WebGL features to support loading and rendering the map control. 
+The Azure Maps Web SDK provides a helper function called [atlas.isSupported](https://docs.microsoft.com/javascript/api/azure-maps-control/atlas?view=azure-iot-typescript-latest#issupported-boolean-). This function detects whether a web browser has the minimum set of WebGL features required to support loading and rendering the map control. Here's an example of how to use the function:
 
 ```
 if(!atlas.isSupported()) {
     alert('Your browser is not supported by Azure Maps');
 } else if(!atlas.isSupported(true)) {
     alert('Your browser is supported by Azure Maps, but may have major performance caveats.');
 } else {
-    //Your browser is supported. Add your map code here.
+    // Your browser is supported. Add your map code here.
 }
 ```
 
 ## Desktop
 
-The Azure Maps Web SDK supports the following desktop browsers.
+The Azure Maps Web SDK supports the following desktop browsers:
 
-- The current and previous version of Microsoft Edge 
-- The current and previous version of Chrome 
-- The current and previous version of Firefox 
-- The current and previous version of Safari (Mac OS X) 
+- Microsoft Edge (current and previous version)
+- Google Chrome (current and previous version)
+- Mozilla Firefox  (current and previous version)
+- Apple Safari (Mac OS X) (current and previous version)
 
-See also [Target legacy browsers](#Target-Legacy-Browsers).
+See also [Target legacy browsers](#Target-Legacy-Browsers) later in this article.
 
 ## Mobile
 
-The Azure Maps Web SDK supports the following mobile browsers.
+The Azure Maps Web SDK supports the following mobile browsers:
 
--  Android
-    * Current version of Chrome on Android 6.0+
-    * Chrome WebView on Android 6.0+
+- Android
+  - Current version of Chrome on Android 6.0 and later
+  - Chrome WebView on Android 6.0 and later
 - iOS
-    * Mobile Safari on the current and previous major version of iOS
-    * UIWebView and WKWebView on the current and previous major version of iOS
-    * Current version of Chrome for iOS
+  - Mobile Safari on the current and previous major version of iOS
+  - UIWebView and WKWebView on the current and previous major version of iOS
+  - Current version of Chrome for iOS
 
 > [!TIP]
-> If you are embedding a map inside a mobile application using a WebView control, you may prefer using the [npm package of the Azure Maps Web SDK](https://www.npmjs.com/package/azure-maps-control) instead of referencing the CDN hosted version of the SDK. This will reduce loading time as the SDK will already be on the user's device and not need to be downloaded at runtime.
+> If you're embedding a map inside a mobile application by using a WebView control, you might prefer to use the [npm package of the Azure Maps Web SDK](https://www.npmjs.com/package/azure-maps-control) instead of referencing the version of the SDK that's hosted on Azure Content Delivery Network. This approach reduces loading time because the SDK is already be on the user's device and doesn't need to be downloaded at run time.
 
 ## Node.js
 
@@ -58,8 +58,9 @@ The following Web SDK modules are also supported in Node.js:
 
 ## <a name="Target-Legacy-Browsers"></a>Target legacy browsers
 
-If you need to target older browsers that may not support or have limited support for WebGL, it is recommended to use the Azure Maps Services in combination with an open-source map control such as [leaflet](https://leafletjs.com/). 
+You might want to target older browsers that don't support WebGL or that have only limited support for it. In such cases, we recommend that you use Azure Maps services together with an open-source map control like [Leaflet](https://leafletjs.com/). Here's an example:
 
+<br/>
 
 <iframe height="500" style="width: 100%;" scrolling="no" title="Azure Maps + Leaflet" src="//codepen.io/azuremaps/embed/GeLgyx/?height=500&theme-id=0&default-tab=html,result" frameborder="no" allowtransparency="true" allowfullscreen="true">
   See the Pen <a href='https://codepen.io/azuremaps/pen/GeLgyx/'>Azure Maps + Leaflet</a> by Azure Maps
@@ -69,7 +70,7 @@ If you need to target older browsers that may not support or have limited suppor
 
 ## Next steps
 
-Learn more about the Azure Maps Web SDK.
+Learn more about the Azure Maps Web SDK:
 
 > [!div class="nextstepaction"]
 > [Map control](how-to-use-map-control.md)
