Tutorial: Share Azure Spatial Anchors across sessions and devices

In this tutorial, you'll learn how to use Azure Spatial Anchors to create anchors during one session and then locate them, on the same device or on a different one. These same anchors could also be located by multiple devices in the same place and at the same time.

Persistence

Azure Spatial Anchors is a cross-platform developer service that allows you to create mixed reality experiences using objects that persist their location across devices over time. When you're finished, you'll have an app that can be deployed to two or more devices. Azure Spatial Anchors created by one instance can be shared to the others.

You'll learn how to:

  • Deploy an ASP.NET Core Web App in Azure that can be used to share anchors, storing them in memory for a duration of time.
  • Configure the AzureSpatialAnchorsLocalSharedDemo scene within the Unity Sample from our Quickstarts to take advantage of the Sharing Anchors Web App.
  • Deploy and run to one or more devices.

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites

To complete this tutorial, make sure you have:

It's worth noticing that, although you'll be using Unity and an ASP.NET Core Web App in this Tutorial, it is only to show an example on how to share Azure Spatial Anchor identifiers across other devices. You can use other languages and back-end technologies to achieve the same goal. Also, the ASP.NET Core Web App used in this Tutorial has a dependency on .NET Core 2.2 SDK. It runs fine on regular Azure Web Apps (for Windows), but will currently not work on Azure Web Apps for Linux.

Create a Spatial Anchors resource

Go to the Azure portal.

In the left navigation pane in the Azure portal, select Create a resource.

Use the search box to search for Spatial Anchors.

Search for Spatial Anchors

Select Spatial Anchors. In the dialog box, select Create.

In the Spatial Anchors Account dialog box:

  • Enter a unique resource name, using regular alphanumeric characters.

  • Select the subscription that you want to attach the resource to.

  • Create a resource group by selecting Create new. Name it myResourceGroup and select OK. A resource group is a logical container into which Azure resources like web apps, databases, and storage accounts are deployed and managed. For example, you can choose to delete the entire resource group in one simple step later.

  • Select a location (region) in which to place the resource.

  • Select New to begin creating the resource.

    Create a resource

After the resource is created, Azure Portal will show that your deployment is complete. Click Go to resource.

Deployment complete

Then, you can view the resource properties. Copy the resource's Account ID value into a text editor because you'll need it later.

Resource properties

Under Settings, select Key. Copy the Primary key value into a text editor. This value is the Account Key. You'll need it later.

Account key

Download the Unity sample project

Clone the samples repository by running the following command:

git clone https://github.com/Azure/azure-spatial-anchors-samples.git

Deploy your Sharing Anchors Service

Open Visual Studio, and open the project at the Sharing\SharingServiceSample folder.

Open the publish wizard

In Solution Explorer, right-click the SharingService project and select Publish.

The Publish Wizard starts. Select App Service > Publish to open the Create App Service dialog box.

Sign in to Azure

In the Create App Service dialog box, select Add an account and sign in to your Azure subscription. If you're already signed in, select the account you want from the drop-down list.

Note

If you're already signed in, don't select Create yet.

Create a resource group

A resource group is a logical container into which Azure resources like web apps, databases, and storage accounts are deployed and managed. For example, you can choose to delete the entire resource group in one simple step later.

Next to Resource Group, select New.

Name the resource group myResourceGroup and select OK.

Create an App Service plan

An App Service plan specifies the location, size, and features of the web server farm that hosts your app. You can save money when hosting multiple apps by configuring the web apps to share a single App Service plan.

App Service plans define:

  • Region (for example: North Europe, East US, or Southeast Asia)
  • Instance size (small, medium, or large)
  • Scale count (1 to 20 instances)
  • SKU (Free, Shared, Basic, Standard, or Premium)

Next to Hosting Plan, select New.

In the Configure Hosting Plan dialog box, use these settings:

Setting Suggested value Description
App Service Plan MySharingServicePlan Name of the App Service plan.
Location West US The datacenter where the web app is hosted.
Size Free The pricing tier that determines hosting features.

Select OK.

Create and publish the web app

In App Name, enter a unique app name (valid characters are a-z, 0-9, and -), or accept the automatically generated unique name. The URL of the web app is https://<app_name>.azurewebsites.net, where <app_name> is your app name.

Select Create to start creating the Azure resources.

After the wizard finishes, it publishes the ASP.NET Core web app to Azure and then opens the app in your default browser.

Published ASP.NET web app in Azure

The app name you used in this section is used as the URL prefix in the format https://<app_name>.azurewebsites.net. Take note of this URL because you'll need it.

Set up your device in Unity

In Unity, open the project in the Unity folder. Unity might prompt you about a different Unity version between the project and the one you've installed on your machine. This warning is okay, as long as your version of Unity Editor is newer than the one the project was created with. In that case, just click Continue. If your Unity Editor version is older than the one the project needs, click Quit, and upgrade your Unity Editor.

Unity window

Set up an Android Device

Open Build Settings by selecting File > Build Settings.

In the Platform section, select Android. Change the Build System to Gradle and ensure the Export Project checkbox doesn't have a check mark.

Select Switch Platform to change the platform to Android. Unity might prompt you to install Android support components if they're missing.

Unity Build Settings window

Close the Build Settings window.

Download and import the ARCore SDK for Unity

Download the unitypackage file from the ARCore SDK for Unity 1.7 releases. Back in the Unity project, select Assets > Import Package > Custom Package and then select the unitypackage file you previously downloaded. In the Import Unity Package dialog box, make sure all files are selected and then select Import.

Set up an iOS Device

Open Build Settings by selecting File > Build Settings.

In the Platform section, select iOS.

Select Switch Platform to change the platform to iOS. Unity might prompt you to install iOS support components if they're missing.

Unity Build Settings window

Close the Build Settings window.

Download and import the Unity ARKit Plugin

Download Unity ARKit Plugin version 2.0.0 and extract the archive.

Copy the contents of the Assets folder from the extracted Unity ARKit Plugin folder to the sample's Assets folder.

Configure the account identifier and key

In the Project pane, navigate to Assets/AzureSpatialAnchorsPlugin/Examples and open the AzureSpatialAnchorsLocalSharedDemo.unity scene file.

The next step is to configure the app to use your account identifier and account key. You copied them into a text editor when setting up the Spatial Anchors resource.

In the Project pane, navigate to Assets\AzureSpatialAnchorsPlugin\Examples\Resources. Select AzureSpatialAnchorsDemoConfig. Then, in the Inspector pane, enter the Account Key as the value for Spatial Anchors Account Key and the Account ID as the value for Spatial Anchors Account Id.

In the Inspector pane, enter the Sharing Anchors Service url (from your ASP.NET web app Azure deployment) as the value for Base Sharing Url, replacing index.html with api/anchors. It should look like this: https://<app_name>.azurewebsites.net/api/anchors.

Save the scene by selecting File > Save.

Deploy to your device

Deploy to Android device

Sign in on your Android device and connect it to your computer by using a USB cable.

Open Build Settings by selecting File > Build Settings.

Under Scenes In Build, ensure all the scenes have a check mark next to them.

Make sure Export Project doesn't have a check mark. Select Build And Run. You'll be prompted to save your .apk file. You can pick any name for it.

Once the app starts, in the Choose A Demo dialog, use the left or right arrows to select the LocalShare option, and tap Go!. Follow the instructions in the app. You can select Create & Share Anchor or Locate Shared Anchor.

The first scenario lets you create an anchor that can be located later on the same device or on a different one. The second scenario, if you've already run the app, either on the same device or on a different one, allows you to locate previously shared anchors. After you pick your scenario, the app will guide you with further instructions around what to do. For example, you'll be asked to move your device around to collect environment information. Later on, you'll place an anchor in the world, wait for it to save, and so on.

Deploy to an iOS device

Open Build Settings by selecting File > Build Settings.

Under Scenes In Build, ensure all the scenes have a check mark next to them.

Select Build. In the dialog box that opens, select a folder to export the Xcode project to.

When the export is complete, a folder that contains the exported Xcode project will appear.

Note

If a window asking you if you want to replace or append appears, we recommend that you select Append because it's faster. You should only need to select Replace if you're changing assets in your scene. (For example, if you're adding, removing, or changing parent/child relationships, or if you're adding, removing, or changing properties.) If you're only making source code changes, Append should be enough.

Open the Xcode project

In the exported Xcode project folder, run this command in the Terminal to install the necessary CocoaPods for the project:

pod install --repo-update

Now you can open Unity-iPhone.xcworkspace to open the project in Xcode:

open ./Unity-iPhone.xcworkspace

Note

If you see a library not found for -lPods-Unity-iPhone error, you probably opened the .xcodeproj file instead of the .xcworkspace file.

Select the root Unity-iPhone node to view the project settings, and then select the General tab.

Under Signing, make sure Automatically manage signing is enabled. If it's not, enable it, and then select Enable Automatic in the dialog box that appears to reset the build settings.

Under Deployment Info, make sure the Deployment Target is set to 11.0.

Deploy the app to your iOS device

Connect the iOS device to the Mac and set the active scheme to your iOS device.

Select the device

Select Build and then run the current scheme.

Deploy and run

Once the app starts, in the Choose A Demo dialog, use the left or right arrows to select the LocalShare option, and tap Go!. Follow the instructions in the app. You can select Create & Share Anchor or Locate Shared Anchor.

The first scenario lets you create an anchor that can be located later on the same device or on a different one. The second scenario, if you've already run the app, either on the same device or on a different one, allows you to locate previously shared anchors. After you pick your scenario, the app will guide you with further instructions around what to do. For example, you'll be asked to move your device around to collect environment information. Later on, you'll place an anchor in the world, wait for it to save, and so on.

In Xcode, stop the app by selecting Stop.

Clean up resources

In the preceding steps, you created Azure resources in a resource group. If you don't expect to need these resources in the future, you can delete them by deleting the resource group.

From the left menu in the Azure portal, select Resource groups and then select myResourceGroup.

On the resource group page, make sure that the listed resources are the ones you want to delete.

Select Delete, type myResourceGroup in the text box, and then select Delete.

Next steps

In this tutorial, you've deployed an ASP.NET Core Web App in Azure, and then configured and deployed a Unity App. You created Spatial Anchors with the app, and shared them with other devices by using your ASP.NET Core Web App.

To learn more about how to improve your ASP.NET Core Web App so that it uses Azure Cosmos DB to store your shared Spatial Anchor identifiers, continue to the next tutorial. Azure Cosmos DB will give persistence to your ASP.NET Core Web App. Doing so will allow your app to create an anchor today, and come back days later to be able to locate it again, by using the anchor identifier stored in your web app.