Tutorial: Share spatial anchors across sessions and devices
Azure Spatial Anchors is a cross-platform developer service with which you can create mixed-reality experiences by using objects that persist their location across devices over time.
In this tutorial, you use Azure Spatial Anchors to create anchors during one session and then locate them on the same device or a different one. The same anchors can also be located by multiple devices in the same place and at the same time.
In this tutorial, you'll learn how to:
- Deploy an ASP.NET Core web app in Azure that you can use to share anchors, and store the anchors in memory for a specified period 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 the anchors to one or more devices.
If you don't have an Azure subscription, create a free account before you begin.
Prerequisites
Before you begin this tutorial, be sure you've met the following prerequisites:
- Read the Azure Spatial Anchors overview.
- Complete one of the 5-minute quickstarts.
Note
Android/NDK and iOS/Swift quickstarts don't currently showcase the capabilities explained in this tutorial.
- A basic knowledge of either:
- A Windows computer with Visual Studio 2019 or later, and the ASP.NET and web development workload.
- The .NET Core 3.1 SDK.
- One or more of the following devices on which to deploy and run an app: HoloLens, HoloLens 2, iOS, or Android.
Note
You'll be using Unity and an ASP.NET Core web app in this tutorial, but the approach here is only to provide an example of how to share Azure Spatial Anchors identifiers across other devices. You can use other languages and back-end technologies to achieve the same goal.
Create a Spatial Anchors resource
Go to the Azure portal.
On the left pane, select Create a resource.
Use the search box to search for Spatial Anchors.
Select Spatial Anchors, and then select Create.
On the Spatial Anchors Account pane, do the following:
Enter a unique resource name by 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 then select OK.
A resource group is a logical container into which Azure resources, such as 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 Create to begin creating the resource.
After the resource is created, the Azure portal shows that your deployment is complete.
Select Go to resource. You can now view the resource properties.
Copy the resource's Account ID value into a text editor for later use.
Also copy the resource's Account Domain value into a text editor for later use.
Under Settings, select Access Key. Copy the Primary key value, Account Key, into a text editor for later use.
Download the sample project
Clone the samples repository by running the following commands:
git clone https://github.com/Azure/azure-spatial-anchors-samples.git
cd ./azure-spatial-anchors-samples
Deploy the Sharing Anchors service
Open Visual Studio, and then open the project in the Sharing\SharingServiceSample folder.
Open the publish wizard
In Solution Explorer, right-click the SharingService project, and then select Publish.
The Publish Wizard starts.
Select App Service > Publish to open the Create App Service pane.
Sign in to Azure
Sign in to the Azure portal.
On the Create App Service pane, select Add an account, and then 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, such as 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 then 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 you host 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.
On the Configure Hosting Plan pane, 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 dashes (-), 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.
The app name you used in this section is used as the URL prefix in the format https://<app_name>.azurewebsites.net. Copy this URL to a text editor for later use.
Deploy the sample app
The Java Android sample supports sharing across devices.
In Android Studio, open the SharedActivity.java file from the samples folder.
Enter the URL that you copied in the previous step (from your ASP.NET web app Azure deployment) as the value for SharingAnchorsServiceUrl in the SharedActivity.java file.
Replace the index.html in the URL with api/anchors. It should look like this: https://<app_name>.azurewebsites.net/api/anchors.
Deploy the app to your device.
After the app starts, on the Choose A Demo pane, use the left and right arrows to select the LocalShare option. Then tap Go!.
Follow the instructions in the app. You can select Create & Share Anchor or Locate Shared Anchor.
With Create & Share Anchor, you can create an anchor and save it to your sharing service. In return, you will get back an identifier for it that you can use to retrieve it from the sharing service. You can then run the second scenario, Locate Shared Anchor, from either your device or a different one.
With Locate Shared Anchor, you can locate previously shared anchors by entering the identifier mentioned earlier. After you pick your scenario, the app will guide you with further instructions. 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, start a new session, and then locate it.
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 Azure portal menu or Home page, select Resource groups. Then, on the Resource groups page, select myResourceGroup.
On the myResourceGroup page, make sure that the listed resources are the ones you want to delete.
Select Delete resource group, type myResourceGroup in the text box to confirm, and then select Delete.
Next steps
In this tutorial, you deployed an ASP.NET Core web app in Azure, and you configured and deployed a Unity app. You created spatial anchors with the app, and you shared them with other devices by using your ASP.NET Core web app.
You can improve your ASP.NET Core web app so that it uses Azure Cosmos DB to persist the storage of your shared spatial anchors identifiers. By adding Azure Cosmos DB support, you can have your ASP.NET Core web app create an anchor today. Then, by using the anchor identifier that's stored in your web app, you can have the app return days later to locate the anchor again.