Getting Started

Maps SDK, a Microsoft Garage project, is ending. As of February 22, 2024, the SDK is deprecated. The SDK will be available until June 30, 2024, and the service will shut down March 1, 2025. Our team learned a lot during this experiment, and we appreciate the community's involvement with this Microsoft Garage project.

---

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.2",
    
        <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!

Check out Configuring the MapRenderer for more details on the various map visualization options.