Using Instant Preview

Use Instant Preview to skip the build process and test ARCore apps instantly on your phone. Click Play in Unity to preview your app using real input and output from your phone.

Overview

Instant Preview consists of an Android app for your ARCore-supported phone and a plugin for Unity.

Requirements

Instant Preview is supported on Windows (discrete GPUs only) and macOS development machines.
On Windows machines with an integrated GPU, the Unity Editor's video feed is not mirrored back to your phone.

To use Instant Preview, you'll need:

Hardware

  • An ARCore supported phone

  • A USB cable to connect your phone to your development machine

Software

See the ARCore SDK for Unity quickstart guide for complete details on software version requirements and installation.

Use Instant Preview in Unity

This guide assumes that you have already created an ARCore project in Unity. If you are new to working with ARCore, see the ARCore SDK for Unity quickstart guide for installation and setup steps.

Set up Instant Preview

  1. Open your ARCore scene in the Unity Editor.

  2. Connect your phone to your development machine via USB. Make sure that developer options and debugging are enabled on your phone.

  3. Click Play in the Unity Editor. The Instant Preview app launches and your ARCore scene starts streaming.

    • If you see a dialog on your computer or phone asking if you want to install the Instant Preview Android app, click or tap Okay to confirm.

    • If you do not have a recent enough version of ARCore installed on your phone, you might be sent to the Play Store to install ARCore before continuing.

  4. Move your phone around to detect planes, place objects, or use other ARCore functionality that you are testing in your app.

    See Handle input from your phone for details on previewing touch input in Instant Preview.

  5. Click Pause in the Unity Editor or tap the system back button on your phone to stop streaming and exit the preview.

  6. (Optional) You can change your streaming configuration to Wi-Fi while your app is paused.

Handle input from your phone

In Instant Preview, touch input on your app's AR scene does not automatically propagate input events to your Unity implementation.

To set up touch input propagation, use the InstantPreviewInput class in any controller script that references the Unity Input class. Add the following code to the top of the controller script:

#if UNITY_EDITOR
     // NOTE:
     // - InstantPreviewInput does not support `deltaPosition`.
     // - InstantPreviewInput does not support input from
     //   multiple simultaneous screen touches.
     // - InstantPreviewInput might miss frames. A steady stream
     //   of touch events across frames while holding your finger
     //   on the screen is not guaranteed.
     // - InstantPreviewInput does not generate Unity UI event system
     //   events from device touches. Use mouse/keyboard in the editor
     //   instead.
     using Input = InstantPreviewInput;
#endif

As an example, the demo scene's HelloAR Controller script uses InstantPreviewInput to detect and propagate touch input events.

The InstantPreviewInput class is similar to Unity's Input class.

Stream over a Wi-Fi connection

Instant Preview works the same way when streaming over USB or Wi-Fi.

By default, Instant Preview uses USB. Streaming over USB is best for longer development sessions.

Use Wi-Fi for shorter testing sessions or when a USB cable would restrict the phone movement that you need.

To stream over Wi-Fi:

  1. Make sure that your phone and development machine are connected to the same Wi-Fi network.

  2. Make sure that your network is configured for Instant Preview:

    • Any firewall software on your development system must be configured to allow Unity to accept TCP connections on port 49838.
    • Your router and/or network firewall must disable client isolation so that your phone and development machine can communicate directly with each other over your network.
    • Your router and/or network firewall must allow broadcast traffic from your development machine to multicast address 239.170.165.207 on port 49838.
  3. Make sure that Instant Preview is enabled. In Unity, verify that Instant Preview Enabled is checked in Edit > Project Settings > ARCore.

  4. Click Play in the Unity Editor. This makes your development machine discoverable in the Instant Preview app on your phone.

  5. On your phone, open the ARCore Instant Preview app. Follow the Set up Instant Preview steps to install this app if it is not currently installed.

  6. On your phone, tap the "Preview via…" dropdown in the app.

    • Your development machine should be listed as one of the available devices under the name of the Wi-Fi network that your phone is using. See Troubleshooting if your phone is not listed.
    • Select your development machine to begin streaming.
    • Use Play and Stop in the Unity Editor to start and stop streaming.

Disable Instant Preview

Instant Preview is enabled by default. To disable Instant Preview in the Unity Editor, go to
Edit > Project Settings > ARCore and uncheck Instant Preview Enabled.

Performance tips

Aspect ratio
Instant Preview mirrors the game window on your phone. Set your window aspect ratio to match the phone you're using for testing. If the aspect ratio does not match, your app might appear stretched in your game window or on your phone.

Use Metal in macOS
If you are working in macOS, use Metal for rendering instead of OpenGL. Go to Player Settings > Settings for PC, Mac & Linux Standalone > Other Settings > Metal Editor Support to enable Metal rendering.

Troubleshooting

  • Check for Instant Preview errors in the Unity Console.

Additionally, make sure that:

  • Another instance of Unity using Instant Preview is not running. Only one instance can run at the same time.

  • Instant Preview is enabled in your project. Make sure that Instant Preview Enabled is checked in Edit > Project Settings > ARCore.

  • Your phone is connected to your computer via USB or Wi-Fi.

  • Your phone is unlocked, with developer options and debugging enabled.

  • In Unity's Build Settings, your build platform is set to Android and you have player settings enabled for ARCore. If not, see the Unity quickstart guide for configuration details.

  • When you click Play in Unity, the Console displays Instant Preview version <version_number>.

If you are streaming via Wi-Fi:

  • Check your network and firewall settings.

  • On Windows development machines:

    1. Open the Windows Firewall with Advanced Security management panel and delete any references to Unity in the Incoming or Outgoing rules.

    2. Relaunch Unity and allow connections when prompted by Windows.

  • If you don't have a suitable Wi-Fi network, you might be able to use your phone as a hotspot:

    1. On your phone, disable mobile data to prevent your development machine from using mobile data over the hotspot.

    2. Configure and enable a secure Wi-Fi hotspot on your phone.

    3. On your development machine, connect to the Wi-Fi hotspot on your phone.

      Even without an internet connection, your development machine and phone should be able to establish an Instant Preview connection.

Limitations

Instant Preview has the following limitations.

Activity pause/resume events not supported
App activity pause events that pause and resume the ARCore Session are not supported when using Instant Preview.

ARCore Session configuration changes not supported
Session configuration cahnges such as disabling light estimation and plane finding are not supported when using Instant Preview.

Limited support for touch input
InstantPreviewInput does not support:

  • Unity UI event system events: Use your mouse or keyboard to interact with these elements directly in the Unity Editor.

Screen orientation settings
Instant Preview determines which orientation to use based on the aspect ratio of the preview window. If the aspect ratio is changed, Instant Preview will restart in order to properly match the orientation.

Send feedback about...