Skip to main content

Set up the project

This guide begins a five-part series on creating a wayfinding experience with VPS2. In this tutorial, wayfinding means helping a user understand where they are, choose a destination, localize to that location, and follow AR guidance in the space.

You will build an app that signs a user in, loads Sites from an Organization, lets the user choose a destination, localizes to that Site with VPS2, and then shows AR wayfinding guidance and anchored content.

The procedural steps build a complete tutorial app from scratch.

This page focuses on how to add and configure the Niantic Spatial SDK (NSDK) in a new or existing Unity project.

Prerequisites​

Before you begin, make sure you have:

  • A Scaniverse account. If you do not have an account, follow directions to create a Niantic Spatial account.
  • A Scaniverse Site with its Production VPS asset already generated.
  • Unity 6000.3.14f1.
  • The platform support module for each platform you plan to build for: Android Build Support, iOS Build Support, or both.
  • A physical Android or iOS device that supports AR for the platform you will test.
  • A testing plan for localization: either be physically close to the Site you will use for testing, or prepare a playback dataset for playback-mode testing.
  • Basic familiarity with Unity scenes, prefabs, and Inspector references.

Set up a Unity AR project​

The following steps verify the minimal project setup needed for the rest of the tutorial.

  1. Open or create a Unity AR project.

    1. If you are creating a new app, create the project first with the Universal 3D template.
    2. If you are creating a new app, select Edit > Project Settings > Player, scroll to the top of the page, and set the Product Name to Wayfinding.
    3. In Edit > Project Settings > Player > Other Settings > Identification, use com.example.wayfinding as the Android Package Name or iOS Bundle Identifier. Do not reuse the sample app identifier com.nianticspatial.nsdk.vps2e2eunity.
    4. If Unity shows a package-resolution error for com.unity.modules.adaptiveperformance or com.unity.modules.vectorgraphics, open Packages/manifest.json, remove those two dependency lines, save the file, and reopen the project.

  2. Update the Unity project configuration.

    This verifies the project settings the rest of the walkthrough depends on. The project should:

    • Use Unity 6 with editor version 6000.3.14f1.
    • Choose input handling settings as Input Manager (Old). To do this, open Edit > Project Settings > Player > Other Settings in the Unity project, then set Active Input Handling to Input Manager (Old). This walkthrough uses Unity UI input handling that works with the old input handler across the Landing, Sites, and AR scenes. When the popup about new input system packages appears, choose No to use the old input path.
    • If you plan to build for Android, choose the Android tab in Player and do the following:
      1. In Settings > Player > Other Settings > Identification, set the Android Minimum API Level to Android 7.0 "Nougat" (API Level 24) or later.
      2. Enable Custom Main Manifest in Edit > Project Settings > Player > Publishing Settings so the sign-in browser can return to the app after authentication.
    • If you plan to build for iOS, choose the Apple tab in Player, then in Settings > Player > Other Settings > Configuration:
      1. Set the Target Minimum iOS Version to 14.0 or later.
      2. Set Camera Usage Description to a user-facing explanation such as Camera access is required for AR wayfinding.
      3. Set Location Usage Description to a user-facing explanation such as Location access is required to find Sites and localize AR content. These descriptions are required before the Landing permission helper can request camera or location access on iOS.

  3. Add the NSDK package to your Unity app.

    Complete the Unity NSDK steps in Set up the Niantic SDK for Unity if you want to update the project yourself. These include the following steps:

    1. Install the Niantic SDK Packages
    2. Activate the XR loader
    3. Configure the build platform.

    You can also use the AI set up skill in Set up the Niantic SDK for Unity if you want an AI agent to help set up the NSDK for you.

  4. Build the Unity project.

    A clean package import and a successful build for the platform you plan to test are the checkpoints for this step. If the build fails, return to the package installation, XR loader, and build platform steps and resolve those errors before continuing.

    • If you build for Android and Unity reports Android SDK is missing required platform API, install Android SDK platform API 33, then build again.
    • If you build for iPhone or iPad, skip the Android SDK step and build with your normal iOS signing flow instead.
    • If you are checking only that the project compiles and its basic UI opens, use Play instead of a device build. Editor validation of location-dependent map and VPS2 behavior requires the playback dataset configured in the next section.

Prepare the sample project​

Use the public vps2-wayfinding-sample app as a reference point while you work through the rest of this Unity walkthrough. The sample app is useful for comparing your implementation against a working VPS2 flow and locating the scenes, prefabs, and scripts referenced in later pages. You will inspect the startup, Sites, and VPS2 flows described in the sample app while building your own app as follows:

  1. Clone nsdk-vps2-wayfinding-sample-unity:

    git clone https://github.com/nianticspatial/nsdk-vps2-wayfinding-sample-unity.git

  2. Open the vps2-wayfinding-sample project in Unity 6000.3.14f1.

  3. Wait for Unity to finish importing, then open the Console and check for package or XR configuration errors. If the sample reports package-resolution or XR-loader errors, resolve those before you continue.

  4. Add a Mapbox public access token to the sample project so the map can load tiles.

    1. Create a Mapbox account if you do not already have one.
    2. Sign in to the Mapbox Developer Console, open the Access Tokens page, and copy a public token that starts with pk..
    3. Open Assets/Resources/Mapbox/MapboxConfiguration.txt.
    4. Replace PUT_MAPBOX_TOKEN_HERE with your Mapbox public access token.

    If you use Mapbox in your own app, you will repeat the same token step later when this tutorial copies MapboxConfiguration.txt into the standalone wayfinding project. If you choose another map provider, use that provider's configuration when you implement the map screen later in the tutorial.

  5. Configure a Playback dataset if you want the sample to use a recorded location in the Unity Editor.

    When playback is enabled, the sample uses the recorded location from the dataset, so the map and AR flow match the place where that recording was captured. This lets you test the sample in the Unity Editor without being physically present at the real Site.

    When playback is disabled, the sample can only use a manually entered test location in the Editor.

    To test playback in the Unity Editor, configure the playback dataset before you run the sample as follows:

    1. In Unity, select Edit > Project Settings.
    2. Select XR Plug-in Management.
    3. Select Niantic Spatial Development Kit.
    4. Under Playback, select the Editor tab.
    5. Select the checkbox next to Enabled to turn on playback.
    6. Set Dataset Path to a folder that contains capture.json. If you don't have your own playback dataset, see Download or create a Playback dataset for instructions and a link to a sample dataset.

  6. Build and run the sample for the platform you plan to test.

    • If you build for Android and Unity reports Android SDK is missing required platform API, install Android SDK platform API 33, then build again.
    • If you build for iPhone or iPad, skip the Android SDK step and build with your normal iOS signing flow instead.
    • If you validate only in the Unity Editor on your laptop or desktop, use Play and a playback dataset instead of a device build.

  7. If you plan to test live localization, go to the physical Site that matches the Production VPS asset you will use. If you are not close to that Site, use a playback dataset instead of expecting live VPS2 tracking to reach LIMITED, PRECISE, or TRACKED.

For the rest of this Unity walkthrough, keep two Unity projects available:

  • The public vps2-wayfinding-sample app, to use as a reference.
  • Your own Unity app, which is the app you create or modify while following this tutorial. This can be a new standalone wayfinding app or an existing app that you extend with VPS2 wayfinding.

When this tutorial tells you to create or update scenes, prefabs, or scripts, make those changes in your own app, not in the sample project.

Next steps​

Continue to Initialize the app to build the landing flow, request permissions, and route into the Site-based VPS2 flow.