MapControl
The MapControl
is a control that allows you to display maps in your app. Currently, Uno supports MapControl
on iOS and Android.
Architecture
Although MapControl
is defined in Uno.UI
, to function, it requires an additional package to be installed, Uno.UI.Maps
, which supplies the actual implementation. This is done to avoid imposing an unnecessary dependency on applications that don't use maps, and also to allow alternative map providers (eg, Google Maps on iOS) to be easily supported in the future.
The current implementation uses the native UIKit Map for iOS and the Google Play Services Map control for Android.
How to use MapControl in an Uno Platform app
Install the Uno.WinUI.Maps NuGet package in the Android and/or iOS head projects of your app.
Add the
MapResources
resource dictionary toApplication.Resources
in yourApp.xaml
file:<Application.Resources> <MapResources xmlns="using:Uno.UI.Maps"/> </Application.Resources>
(Windows and Android) Obtain an API key for your app, following the instructions below.
(Android) Configure permissions in the manifest, following the instructions below.
Add
MapControl
to your app (<MapControl xmlns="using:Microsoft.UI.Xaml.Controls.Maps" />
).
Sample XAML
Here's a complete sample:
<Page x:Class="MapControlSample.MainPage"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:MapControlSample"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:maps="using:Microsoft.UI.Xaml.Controls.Maps"
mc:Ignorable="d"
Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="auto" />
<RowDefinition Height="*" />
</Grid.RowDefinitions>
<StackPanel>
<Slider Minimum="1"
Maximum="20"
StepFrequency=".5"
Header="ZoomLevel"
x:Name="zoomSlider"
Value="12" />
</StackPanel>
<maps:MapControl Grid.Row="1"
ZoomLevel="{Binding ElementName=zoomSlider, Path=Value, Mode=TwoWay}" />
</Grid>
</Page>
The above code will display Page with a Map Control and a slider that will be used to change the ZoomLevel.
Platform support
Feature | Android | iOS | Wasm |
---|---|---|---|
Display a map | X | X | |
Display a path | X | ||
Customize pushpins with icon | |||
Fully template pushpins | |||
Show user's location on map | |||
Toggle native Locate-Me button visibility | |||
Toggle native Compass button visibility |
Usage
Get API key for the map component
To use the map component, you will need an API key for Windows and Android. Here are the steps to retrieve it.
Windows
For the detailed procedure for Windows, see Request a maps authentication key documentation.
Login to your account or register if you don't have one
Go to MyAccount -> Keys
Click on create a new key
Enter the following information:
- Application name
- Application URL (optional)
- Key type
- Application type
Hit Create and get the key
The key will be set as the value for the parameter MapServiceToken for the MapControl object.
Android
Create a project in the Google Developers Console.
Enable Map Service. In case this is your first time using the Google Maps API you will need to enable it before using it.
- Go to https://console.developers.google.com
- Login with a Google account
- Click on "Enable APIs and Services"
- Select "Maps SDK for Android" and click on Enable
Generate an API key.
- If you are coming from step-2 just navigate back until you are again in the dashboard, otherwise, go to https://console.developers.google.com and login with a Google account.
- Go to the Credentials section on the left-hand side menu
- Click on "Create Credentials", then "API key"
- Copy the key generated as this will be the one we will use later in the application
Note: For apps in production we suggest restricting the keys to be used only by your Android app. This is possible by using the SHA-1 fingerprint of your app.
For a detailed procedure on how to retrieve the SHA-1 fingerprint for your Android application, please follow this link: https://developers.google.com/maps/documentation/android-api/signup#release-cert
Configure your application
- For Android
Add the following to AndroidManifest.xml:
<uses-library android:name="com.google.android.maps" />
Add the API key to
AssemblyInfo.cs
.[assembly: MetaData("com.google.android.maps.v2.API_KEY", Value = "YOUR_API_KEY")]
Replace the text YOUR_API_KEY with the key generated in previous step.
Note: Since this key might vary depending on the platform and environment we suggest using a constant class where the key could be retrieved from.
Add the relevant permissions to
AssemblyInfo.cs
. For example, if you wish to access the user location[assembly: UsesPermission(Android.Manifest.Permission.AccessFineLocation)] [assembly: UsesPermission("com.myapp.permission.MAPS_RECEIVE")] [assembly: Permission(Name = "com.myapp.permission.MAPS_RECEIVE", ProtectionLevel = Android.Content.PM.Protection.Signature)]