Getting Started

1. Install required software

Windows 10 FCU	Unity 2019.3+	Visual Studio
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

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

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 to get akey.

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

3. Setup a Unity project

• Option 1: Use the Sample Project.

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

  • Clone the repository
  • After cloning, use Unity Hub to open the SampleProject folder.
  • Once the project has opened, follow the instructions to provide the developer key.

• Option 2: Add the SDK to an existing project.

  This requires modifying Unity's package manifest to include a reference to the SDK package.

  • 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",
    
        <NOTE: Existing dependencies should not be modified.>
    
      }
    }

  • Return to the Unity Editor; A dialog should appear showing the progress of importing the new package.

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

4. Create a map

• Add a new GameObject to the Scene.
• Add a MapRenderer component to the GameObject: Add component -> Scripts -> Microsoft.Maps.Unity -> MapRenderer

5. Provide a Bing Maps develper key

After creating a Bing Maps key, it needs to be provided to the map.

• Option 1: Create a resource file to store the key.

  • In the Assets directory of the project, create a directory named Resources.
  • In the Resources directory, create a file named MapSessionConfig.txt.
  • Copy the developer key into MapSessionConfig.txt.
  • Finally, ignore this file from source control e.g., add MapSessionConfig.txt to gitignore.

• Option 2: Provide the key manually.

  • Set the MapSession key source to Do Not Save.
  • Using a custom script, load the key how you chose e.g., setup an Azure Function to retrieve the key, as explained in this blog post.
  • Set the key on the MapSession.DeveloperKey property.

6. Click the Play button!

Checkout Configuring the MapRenerer for more details on the various map visualization options.

---

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.