Getting Started

1. Install required software

Windows 10 FCU	Unity 2019.3+	Visual Studio 2017+
To develop apps for mixed reality headsets, you need the Windows 10 Fall Creators Update or newer	Check the Unity Support Matrix for a list of supported Unity versions	Visual Studio is used for code editing, deploying and building UWP app packages

2. Create a Bing Maps key

A Bing Maps developer key is required to enable the mapping functionality of the SDK.

1. Sign-in to the Bing Maps Dev Center.

   • For new accounts, follow the instructions at Creating a Bing Maps Account.

2. Select My keys under My Account, and select the option to create a new key.

3. Provide the following required information to create a key:

   • Application name: The name of the application.
   • Key type: Basic or Enterprise. Key types are explained here.
   • Application type: Select Other Public Mobile App.

4. Click the Create button. The new key displays in the list of available keys. This key will be used later when setting up the Unity project.

For more information about how developer key usage is accounted, see Understanding Bing Maps Transactions.

3. Setup a Unity project

Option 1: Clone the sample project

This repo contains a Sample Project which can be cloned or downloaded and then opened in Unity.

The sample project provides a good starting point. It is configured to use the latest version of the SDK, a recent snapshot of MRTK, and it contains a collection of sample scenes.

Option 2: Start from scratch

The SDK can also be added to an existing Unity project. This requires modifying Unity's package manifest to include a reference to the SDK package.

1. Locate the Unity project's folder.

   In the Packages directory, open manifest.json.

   Append the scopedRegistries section to the beginning of the manifest and modify dependencies as follows:

   {
     "scopedRegistries": [
       {
         "name": "Maps SDK for Unity",
         "url": "https://unity.virtualearth.net/npm/registry/",
         "scopes": [
           "com.microsoft.maps"
         ]
       }
     ],
     "dependencies": {
       "com.microsoft.maps.unity": "0.11.1",
   
       <Existing dependencies: Do not remove>
   
     }
   }

2. Open the Unity editor for the corresponding project. A dialog should appear showing the progress of importing the new package.

3. If the project targets the universal render pipeline (URP), install the support package.

4. Create a map

5. Add a new GameObject to the Scene.

6. Add a MapRenderer component to the GameObject: Add component -> Scripts -> Microsoft.Maps.Unity -> MapRenderer

7. In the MapSession component, provide the Bing Maps key.

When the Bing Maps key is set in Editor mode, it's value will be serialized to the Scene or prefab. Alternatively, the key can be set in play mode programmatically via MapSession.DeveloperKey.

Once a valid key is provided, the map will render. See Configuring the MapRenderer for more details.

Updating the SDK

When new versions of the SDK are published, they will be shown in Package Manager.

To be notified when new versions are available, watch for updates to the Changelog.

Migrating to 0.9.0+

Versions before the release of 0.9.0 were provided as a NuGet package and used a NuGet plugin for Unity to manage installation and updates of the SDK.

As of version 0.9.0, the SDK is available as a Unity package which can be installed and updated from within the editor using the Package Manager window.

To migrate from an older version of the SDK to 0.9.0 or newer, follow the steps below.

1. NuGet -> UPM

To migrate from the NuGet package to the NPM package:

1. Remove the Microsoft.Maps.Unity NuGet package.
   • Nuget -> Manage Nuget Packages
   • Go to Installed tab
   • Uninstall Microsoft.Maps.Unity
2. If no other NuGet packages are being used in the project, the NuGet plugin can be removed by deleting the following:
   • Assets\Nuget directory
   • Assets\Nuget.config
   • Assets\Packages directory
   • Assets\Packages.config
3. Next, follow the steps here to install the latest version of the SDK via the Package Manager.

2. Fixing script errors due to GUID changes

Version 0.9.0 introduced various breaking changes due to moving components from the DLL to scripts.

An editor extension has been provided to automate the process of upgrading the GUIDs.

In the editor, go to Assets -> Maps SDK for Unity -> Upgrade Component GUIDs

Other breaking changes to APIs are not automated. If more information is required to resolve other errors in the scripts, refer to the Changelog for description of APIs that were modified.