Skip to content

Commit 9a07e04

Browse files
ttorblettorble
authored
Merge pull request #266686 from yulinscottkang/native
Azure Maps migration guide for native SDKs
2 parents 270772e + b89c69d commit 9a07e04

File tree

6 files changed

+339
-8
lines changed

6 files changed

+339
-8
lines changed

‎articles/azure-maps/android-sdk-migration-guide.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
title: The Azure Maps Android SDK migration guide
3+
titleSuffix: Microsoft Azure Maps
4+
description: Find out how to migrate your Azure Maps Android SDK applications to the Web SDK using a WebView.
5+
author: sinnypan
6+
ms.author: sipa
7+
ms.date: 02/20/2024
8+
ms.topic: how-to
9+
ms.service: azure-maps
10+
---
11+
12+
# The Azure Maps Android SDK migration guide
13+
14+
Migrating from the Azure Maps Android SDK to the Web SDK in a WebView involves transitioning your existing map view from a native implementation to a web-based map using the Azure Maps Web SDK. This guide shows you how to migrate your code and features from the Android SDK to the Web SDK.
15+
16+
## Prerequisites
17+
18+
To use the Map Control in a web page, you must have one of the following prerequisites:
19+
20+
* An [Azure Maps account].
21+
* A [subscription key] or Microsoft Entra credentials. For more information, see [authentication options].
22+
23+
## Create a WebView
24+
25+
Add a `WebView` if your Android application doesn't have one. Do so by adding the `WebView` element to your layout XML or programmatically in your Java code. Be sure it's configured to occupy the desired area of your layout.
26+
27+
```xml
28+
<?xml version="1.0" encoding="utf-8"?>
29+
<androidx.coordinatorlayout.widget.CoordinatorLayout xmlns:android="http://schemas.android.com/apk/res/android"
30+
xmlns:app="http://schemas.android.com/apk/res-auto"
31+
xmlns:tools="http://schemas.android.com/tools"
32+
android:layout_width="match_parent"
33+
android:layout_height="match_parent"
34+
tools:context=".MainActivity">
35+
36+
<WebView
37+
android:id="@+id/webView"
38+
android:layout_width="match_parent"
39+
android:layout_height="match_parent"/>
40+
41+
</androidx.coordinatorlayout.widget.CoordinatorLayout>
42+
```
43+
44+
Enable internet access by adding permissions in AndroidManifest.xml.
45+
46+
```xml
47+
<uses-permission android:name="android.permission.INTERNET" />
48+
```
49+
50+
In your activity or fragment, initialize the WebView and enable JavaScript by updating the settings. Load the HTML file that contains the Web SDK code. You can either load it from the assets folder or from a remote URL.
51+
52+
```java
53+
import android.os.Bundle;
54+
import androidx.appcompat.app.AppCompatActivity;
55+
import android.webkit.WebSettings;
56+
import android.webkit.WebView;
57+
58+
public class MainActivity extends AppCompatActivity {
59+
60+
private WebView webView;
61+
62+
@Override
63+
protected void onCreate(Bundle savedInstanceState) {
64+
super.onCreate(savedInstanceState);
65+
66+
setContentView(R.layout.activity_main);
67+
webView = findViewById(R.id.webView);
68+
69+
// Enable JavaScript
70+
WebSettings webSettings = webView.getSettings();
71+
webSettings.setJavaScriptEnabled(true);
72+
73+
// Load local HTML file from /src/main/assets/map.html
74+
webView.loadUrl("file:///android_asset/map.html");
75+
}
76+
}
77+
```
78+
79+
## Set up a map with Azure Maps Web SDK
80+
81+
In your HTML file, initialize a map with your subscription key. Replace `<YOUR_SUBSCRIPTION_KEY>` with your actual key.
82+
83+
```html
84+
<!DOCTYPE html>
85+
<html>
86+
<head>
87+
<title>Azure Maps</title>
88+
<meta charset="utf-8" />
89+
<meta name="viewport" content="width=device-width, initial-scale=1" />
90+
<!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
91+
<link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css"/>
92+
<script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>
93+
<style>
94+
html,
95+
body,
96+
#map {
97+
margin: 0;
98+
height: 100%;
99+
width: 100%;
100+
}
101+
body {
102+
display: flex;
103+
flex-direction: column;
104+
}
105+
main {
106+
flex: 1 1 auto;
107+
}
108+
</style>
109+
<script type="text/javascript">
110+
// Create an instance of the map control.
111+
function InitMap() {
112+
var map = new atlas.Map("map", {
113+
center: [-122.33, 47.6],
114+
zoom: 12,
115+
authOptions: {
116+
authType: "subscriptionKey",
117+
subscriptionKey: "<YOUR_SUBSCRIPTION_KEY>"
118+
}
119+
});
120+
121+
// Wait until the map resources are ready.
122+
map.events.add("ready", function () {
123+
// Resize the map to fill the container.
124+
map.resize();
125+
});
126+
}
127+
</script>
128+
</head>
129+
<body onload="InitMap()">
130+
<main>
131+
<div id="map"></div>
132+
</main>
133+
</body>
134+
</html>
135+
```
136+
137+
Save and run the app. A map should be shown within a WebView. Add any features or functionalities that you want to use from the Web SDK. You can refer to the [Azure Maps documentation] and the [Azure Maps Code Samples website] for more use cases.
138+
139+
:::image type="content" source="./media/android-sdk-migration-guide/maps-android.png" alt-text="A screenshot of a map in a WebView.":::
140+
141+
## Communication between native code and WebView (optional)
142+
143+
To enable communication between your Android application and the WebView, you can use the WebView's `addJavascriptInterface` method to expose a Java object to the JavaScript running in the WebView. It allows you to call Java methods from your JavaScript code. For more information, see the [Android WebView documentation].
144+
145+
## Clean Up Native Map Implementation
146+
147+
Remove code related to the native Azure Maps Android SDK, including dependencies and initialization code related to `com.azure.android:azure-maps-control`.
148+
149+
## Testing
150+
151+
Test your application thoroughly to ensure the migration was successful. Check for issues related to map functionality, user interactions, and performance.
152+
153+
## Next steps
154+
155+
Learn how to add maps to web and mobile applications using the Map Control client-side JavaScript library in Azure Maps:
156+
157+
> [!div class="nextstepaction"]
158+
> [Use the Azure Maps map control]
159+
160+
[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account
161+
[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account
162+
[authentication options]: /javascript/api/azure-maps-control/atlas.authenticationoptions
163+
[Azure Maps documentation]: how-to-use-map-control.md
164+
[Azure Maps Code Samples website]: https://samples.azuremaps.com/
165+
[Android WebView documentation]: https://developer.android.com/reference/android/webkit/WebView
166+
[Use the Azure Maps map control]: how-to-use-map-control.md
167+
168+

‎articles/azure-maps/ios-sdk-migration-guide.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: The Azure Maps iOS SDK migration guide
3+
titleSuffix: Microsoft Azure Maps
4+
description: Find out how to migrate your Azure Maps iOS SDK applications to the Web SDK using a WebView.
5+
author: sinnypan
6+
ms.author: sipa
7+
ms.date: 02/20/2024
8+
ms.topic: how-to
9+
ms.service: azure-maps
10+
---
11+
12+
# The Azure Maps iOS SDK migration guide
13+
14+
Migrating from the Azure Maps iOS SDK to the Web SDK in a WebView involves transitioning your existing map view from a native implementation to a web-based map using the Azure Maps Web SDK. This guide shows you how to migrate your code and features from the iOS SDK to the Web SDK.
15+
16+
## Prerequisites
17+
18+
To use the Map Control in a web page, you must have one of the following prerequisites:
19+
20+
* An [Azure Maps account].
21+
* A [subscription key] or Microsoft Entra credentials. For more information, see [authentication options].
22+
23+
## Create a WebView
24+
25+
Add a `WebView` if your iOS application doesn't have one. Do so by adding the `WKWebView` to your storyboard or programmatically in your Swift code. Be sure it's configured to occupy the desired area of your layout.
26+
27+
```swift
28+
import UIKit
29+
import WebKit
30+
31+
class ViewController: UIViewController, WKNavigationDelegate {
32+
33+
var webView: WKWebView!
34+
35+
override func viewDidLoad() {
36+
super.viewDidLoad()
37+
38+
// Create WKWebView instance
39+
webView = WKWebView(frame: view.bounds)
40+
webView.navigationDelegate = self
41+
view.addSubview(webView)
42+
43+
// Load local HTML file
44+
loadLocalHTMLFile()
45+
}
46+
47+
func loadLocalHTMLFile() {
48+
if let htmlPath = Bundle.main.path(forResource: "map", ofType: "html") {
49+
do {
50+
let htmlString = try String(contentsOfFile: htmlPath, encoding: .utf8)
51+
webView.loadHTMLString(htmlString, baseURL: Bundle.main.bundleURL)
52+
} catch {
53+
print("Error loading HTML file: \(error)")
54+
}
55+
} else {
56+
print("HTML file not found.")
57+
}
58+
}
59+
}
60+
```
61+
62+
## Set up a map with Azure Maps Web SDK
63+
64+
In your HTML file, initialize a map with your subscription key. Replace `<YOUR_SUBSCRIPTION_KEY>` with your actual key.
65+
66+
```html
67+
<!DOCTYPE html>
68+
<html>
69+
<head>
70+
<title>Azure Maps</title>
71+
<meta charset="utf-8" />
72+
<meta name="viewport" content="width=device-width, initial-scale=1" />
73+
<!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
74+
<link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css"/>
75+
<script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>
76+
<style>
77+
html,
78+
body,
79+
#map {
80+
margin: 0;
81+
height: 100%;
82+
width: 100%;
83+
}
84+
body {
85+
display: flex;
86+
flex-direction: column;
87+
}
88+
main {
89+
flex: 1 1 auto;
90+
}
91+
</style>
92+
<script type="text/javascript">
93+
// Create an instance of the map control.
94+
function InitMap() {
95+
var map = new atlas.Map("map", {
96+
center: [-122.33, 47.6],
97+
zoom: 12,
98+
authOptions: {
99+
authType: "subscriptionKey",
100+
subscriptionKey: "<YOUR_SUBSCRIPTION_KEY>"
101+
}
102+
});
103+
104+
// Wait until the map resources are ready.
105+
map.events.add("ready", function () {
106+
// Resize the map to fill the container.
107+
map.resize();
108+
});
109+
}
110+
</script>
111+
</head>
112+
<body onload="InitMap()">
113+
<main>
114+
<div id="map"></div>
115+
</main>
116+
</body>
117+
</html>
118+
```
119+
120+
Save and run the app. A map should be shown within a WebView. Add any features or functionalities that you want to use from the Web SDK. You can refer to the [Azure Maps documentation] and the [Azure Maps Code Samples website] for more use cases.
121+
122+
:::image type="content" source="./media/ios-sdk-migration-guide/maps-ios.png" alt-text="A screenshot of a map in a WebView.":::
123+
124+
## Communication between native code and WebView (optional)
125+
126+
To enable communication between your iOS application and the WebView, you can use the `WKScriptMessageHandler` protocol provided by the `WKWebView` class. It allows you to establish a bridge for communication between JavaScript running in the WebView and your Swift code. For more information, see [WKScriptMessageHandler] in the iOS WebKit documentation.
127+
128+
## Clean Up Native Map Implementation
129+
130+
Remove code related to the native Azure Maps iOS SDK from your project, including dependencies and initialization code related to `azure-maps-ios-sdk-distribution`.
131+
132+
## Testing
133+
134+
Test your application thoroughly to ensure that the migration was successful. Check for issues related to map functionality, user interactions, and performance.
135+
136+
## Next steps
137+
138+
Learn how to add maps to web and mobile applications using the Map Control client-side JavaScript library in Azure Maps:
139+
140+
> [!div class="nextstepaction"]
141+
> [Use the Azure Maps map control]
142+
143+
[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account
144+
[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account
145+
[authentication options]: /javascript/api/azure-maps-control/atlas.authenticationoptions
146+
[Azure Maps documentation]: how-to-use-map-control.md
147+
[Azure Maps Code Samples website]: https://samples.azuremaps.com/
148+
[WKScriptMessageHandler]: https://developer.apple.com/documentation/webkit/wkscriptmessagehandler
149+
[Use the Azure Maps map control]: how-to-use-map-control.md
150+
151+

‎articles/azure-maps/media/android-sdk-migration-guide/maps-android.png

1.98 MB
Loading

‎articles/azure-maps/media/ios-sdk-migration-guide/maps-ios.png

1.54 MB
Loading

‎articles/azure-maps/toc.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ items:
181181
href: how-to-dev-guide-java-sdk.md
182182
- name: Develop with the Web SDK
183183
items:
184-
- name: Web SDK v1 migration guide
184+
- name: Web SDK migration guide
185185
href: web-sdk-migration-guide.md
186186
- name: Map control
187187
items:
@@ -283,6 +283,8 @@ items:
283283
href: web-sdk-best-practices.md
284284
- name: Develop with the Android SDK
285285
items:
286+
- name: Android SDK migration guide
287+
href: android-sdk-migration-guide.md
286288
- name: The Android map control
287289
href: how-to-use-android-map-control-library.md
288290
- name: Change the style of the map
@@ -319,6 +321,8 @@ items:
319321
href: android-map-events.md
320322
- name: Develop with the iOS SDK
321323
items:
324+
- name: iOS SDK migration guide
325+
href: ios-sdk-migration-guide.md
322326
- name: The iOS map control
323327
href: how-to-use-ios-map-control-library.md
324328
- name: Change the style of a map

0 commit comments

Comments
 (0)