Edit

Configuring Azure Spatial Anchors in a Unity project

  • Article

This guide will show you how to get started with the Azure Spatial Anchors SDK in your Unity project.

Project requirements

When you start a new Unity project, you can choose between the Unity XR Plug-in Framework and Legacy Built-in XR.

The XR Plug-in Framework is only supported on ASA SDK version 2.9.0 or later. To target the XR Plug-in Framework, use Unity 2020.3 (LTS), and AR Foundation 4.1.7 with the following packages, depending on your platform:

  • Mixed Reality OpenXR Plugin: 1.1.2
  • Windows XR Plugin: 4.5.0
  • ARCore XR Plugin: 4.1.7
  • ARKit XR Plugin: 4.1.7

Configuring a project

Before including the Azure Spatial Anchors SDK in your Unity project, be sure to install the required packages through the Unity Package Manager.

Choose ASA version

To determine which ASA SDK version to use in your Unity project, please select your version of Unity below.

Support for Unity 2020 was added with ASA SDK 2.9.0. We suggest using the latest ASA SDK for Unity 2020 development.

Important

If using the Mixed Reality OpenXR plugin, ASA SDK 2.10.0 is the minimum supported version. If using Windows XR 4.5.1 or later, ASA SDK 2.11.0 is the minimum supported version.

Download ASA packages

The next step is to download the Azure Spatial Anchors packages for Unity.

To use Azure Spatial Anchors in Unity, you need to download both the core package (com.microsoft.azure.spatial-anchors-sdk.core) and a platform-specific package for each platform that you plan to support.

Platform Required package names
HoloLens com.microsoft.azure.spatial-anchors-sdk.core@<version_number>
com.microsoft.azure.spatial-anchors-sdk.windows@<version_number>
Android com.microsoft.azure.spatial-anchors-sdk.core@<version_number>
com.microsoft.azure.spatial-anchors-sdk.android@<version_number>
iOS com.microsoft.azure.spatial-anchors-sdk.core@<version_number>
com.microsoft.azure.spatial-anchors-sdk.ios@<version_number>

Note

The Mixed Reality Feature Tool currently only supports Windows.

Continue to the next step. You'll use the Mixed Reality Feature Tool in a later step.

Import ASA packages

This step requires that the Mixed Reality Feature Tool is downloaded and available.

  1. Follow the Mixed Reality Feature Tool documentation to set up the tool and learn how to use it.
  2. Install
    1. Azure Spatial Anchors SDK Core
    2. Azure Spatial Anchors SDK for <your platform(s)>
    3. Mixed Reality OpenXR Plugin if using OpenXR - located under Platform Support

Extra Configurations

If you are developing for HoloLens or Android please follow the additional setup steps below

Configure your Unity project XR settings

When developing MixedReality apps on HoloLens, you need to set the XR configuration in Unity. For more information, see Setting up your XR configuration - Mixed Reality | Microsoft Docs and Choosing a Unity version and XR plugin - Mixed Reality | Microsoft Docs.

Azure Spatial Anchors SDK versions 2.9.0 or earlier only provide support for the Windows XR plugin (com.unity.xr.windowsmr), so the Azure Spatial Anchors windows package has an explicit dependency on the Windows XR Plugin.

Azure Spatial Anchors SDK versions 2.10.0 or later provide support for both the Mixed Reality OpenXR plugin (com.microsoft.mixedreality.openxr) and the Windows XR plugin com.unity.xr.windowsmr. You need to include either the com.microsoft.mixedreality.openxr package or the com.unity.xr.windowsmr package in your project depending on your choice.

Configure your Unity project capabilities

Be sure to enable the following capabilities in your Unity project:

  • SpatialPerception
  • InternetClient
  • PrivateNetworkClientServer

Warning

Failure to enable the PrivateNetworkClientServer capability may lead to a failure to query anchors when the device is using a network that is configured to be private.