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.

This provides a useful template for new projects because the setup and configuration is already complete.

The project includes the latest version of the SDK, a recent snapshot of MRTK, and 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.0",
   
       <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

After installing the SDK, to add a map to the scene:

1. Create a new GameObject.
2. Add a MapRenderer component to the GameObject: Add component -> Scripts -> Microsoft.Maps.Unity -> MapRenderer
3. In the MapSession component, provide the developer key. (Note, this component is automatically added after creating the MapRenderer.)

Once a valid key is provided, the map will render at runtime and in the editor as well. 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 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.