Using Scene Viewer to display interactive 3D models in AR from an Android app or browser

Scene Viewer is an immersive viewer that enables 3D and AR experiences from your website or Android app. It lets users of Android mobile devices easily preview, place, view, and interact with web-hosted 3D models in their environment.

Most Android browsers support Scene Viewer. Scene Viewer has been successfully implemented by many Google partners to reliably support 3D and AR experiences. It also powers these experiences for Google Search.

Implementation is straightforward:

• Web-based experiences require only properly-formatted links on a web page.

• App-based experiences require only integrating a few lines of Java code.

Scene Viewer runtime requirements

To experience AR with Scene Viewer, users must have an:

• An ARCore supported device running Android 7.0 Nougat (API Level 24) or later.
• An up to date (recent) version of Google Play Services for AR. This service is automatically installed and kept up to date on the vast majority of ARCore supported devices.
• An up to date version of the Google app. This app comes pre-installed and is also automatically kept up to date on the vast majority of ARCore supported devices.

To provide for cases where either Google Play Services for AR or the Google app aren't present or the installed versions are too old, you can specify a fallback URL that launches an alternative experience, for example, a web page, an error message, or a fallback experience that you have built.

Supported use cases

Launch Scene Viewer using an explicit intent (3D or AR)

To support the widest range of Android devices, use an explicit Android intent to launch Scene Viewer. The explicit intent can be triggered from an HTML page or a native Android app. The intent will be handled by the Google app that comes pre-installed on ARCore supported Android devices.

Depending on configured intent parameters and device capabilities, interactive 3D models can be placed in the user's environment or fall back to displaying in a 3D viewer.

• If Google Play Services for AR is present on the device, as is up to date, Scene Viewer will show the model in an AR native view or 3D view.

• If Google Play Services for AR isn't present, or isn't up to date, Scene Viewer gracefully falls back to displaying the model in a 3D view.

• If a 3D model cannot be displayed, for example because the Google app is not installed, or is an old version, the S.browser_fallback_url parameter will be used to display a fallback web page instead.

Launch Scene Viewer from HTML or Java

<a href="intent://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf#Intent;scheme=https;package=com.google.android.googlequicksearchbox;action=android.intent.action.VIEW;S.browser_fallback_url=https://developers.google.com/ar;end;">Avocado</a>

Intent sceneViewerIntent = new Intent(Intent.ACTION_VIEW);
sceneViewerIntent.setData(Uri.parse("https://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"));
sceneViewerIntent.setPackage("com.google.android.googlequicksearchbox");
startActivity(sceneViewerIntent);

Intent versioning

The intent version is indicated by the version number after arvr.google.com/scene-viewer. For example, the initial release used version 1.0. When newer Scene Viewer features are required, you may launch Scene Viewer with a higher intent version corresponding with the features you require.

Intent version 1.1 added support for intent:// links, which can launch directly into an Android app rather than to a URL. If you would like Scene Viewer to guarantee that this functionality is available when launched, and fail to launch otherwise, launch scene viewer with an intent to intent://arvr.google.com/scene-viewer/1.1.

Supported intent parameters

The following parameters are supported for an explicit intent to the Google Search package.

Intent Parameter	Allowed Values	Comments
file (required)	A valid URL	This URL specifies the glTF or glb file that should be loaded into Scene Viewer. This should be URL-escaped.
S.browser_fallback_url (required for HTML-based intents)	A valid URL	This is a Google Chrome feature supported only for web-based implementations. When the Google app is not present on the device, this is the URL that Google Chrome navigates to.
mode (optional)	3d_preferred (default)	Scene Viewer displays the model in 3D mode with a View in your space button. If Google Play Services for AR isn't present on the device, the View in your space button is hidden.
	3d_only	Scene Viewer launches with the model displayed in 3D mode, even if Google Play Services for AR is present on the device. The View in your space button is never shown.
	ar_preferred	Scene Viewer launches in AR native mode as the entry mode. The user is given the option to switch between AR and 3D modes via the View in your space and View in 3D buttons. If Google Play Services for AR isn't present, Scene Viewer gracefully falls back to 3D mode as the entry mode.
	ar_only	When using this value, you should launch via an explicit Android intent to com.google.ar.core. Note: Do not use ar_only mode when launching via explicit Android intent to Google app.
link (optional)	A valid URL	A URL for an external webpage. If present, a button will be surfaced in the UI that intents to this URL when clicked.
title (optional)	Valid string	A name for the model. If present, it will be displayed in the UI. The name will be truncated with ellipses after 60 characters.
sound (optional)	A valid URL	A URL to a looping audio track that is synchronized with the first animation embedded in a glTF file. It should be provided alongside a glTF with an animation of matching length. If present, the sound is looped after the model is loaded. This should be URL-escaped.
resizable (optional)	true (default) false	When set to false, users will not be able to scale the model in the AR experience. Scaling works normally in the 3D experience.
enable_vertical_placement (optional)	false (default) true	When set to true, users will be able to place the model on a vertical surface.

UX guidance

To provide the best possible UX for users, we recommend that the visible calls to action convey that the user is about to enter an immersive environment.

For 3D viewer experiences, we recommend a call to action labeled View in 3D that looks like one of the following images:

Launch Scene Viewer using an explicit intent to Google Play Services for AR (AR mode only)

AR mode in Scene Viewer is powered by Google Play Services for AR.

To ensure that AR is available in Scene Viewer, you can use an explicit Android intent from a website or native Android app to launch Scene Viewer via the com.google.ar.core package and provide a browser_fallback_url. This way, you can ensure that all users either have a native AR experience via Scene Viewer or a fallback experience that you have built yourself. For example, you might build fallback experiences such as your own 3D viewer or a graceful error message.

To trigger the explicit intent from HTML, use the following syntax:

<a href="intent://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf&mode=ar_only#Intent;scheme=https;package=com.google.ar.core;action=android.intent.action.VIEW;S.browser_fallback_url=https://developers.google.com/ar;end;">Avocado</a>;

To trigger the explicit intent from Java, use the following code:

Intent sceneViewerIntent = new Intent(Intent.ACTION_VIEW);
Uri intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.0").buildUpon()
    .appendQueryParameter("file", "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf")
    .appendQueryParameter("mode", "ar_only")
    .build();
sceneViewerIntent.setData(intentUri);
sceneViewerIntent.setPackage("com.google.ar.core");
startActivity(sceneViewerIntent);

Supported intent parameters

The following parameters are supported for an explicit intent to the Google Play Services for AR package.

Intent Parameter	Allowed Values	Comments
browser_fallback_url (required for HTML-based intents)	A valid URL	This is supported only for web-based implementations. When Google Play Services for AR is not present on the device or not up to date, this is the URL it navigates to.
mode (optional)	ar_only	Scene Viewer always launches the 3D model in a native AR view and hides any UI for switching to the Scene Viewer 3D viewer. If Google Play Services for AR isn't present, Scene Viewer launches the URL you set in the browser_fallback_url for web-based experiences. For app-based experiences, Scene Viewer falls back to an alternate experience such as an error message or another experience that you have built yourself.
	ar_preferred	Scene Viewer launches in AR native mode as the entry mode and provides users the option to switch between AR and 3D modes via the View in your space and View in 3D buttons. If Google Play Services for AR isn't present, Scene Viewer launches the URL you set in the browser_fallback_url for web-based experiences. For app-based experiences, Scene Viewer falls back to an alternate experience such as an error message or another experience that you have built yourself.
link (optional)	A valid URL	A URL for an external webpage. If present, a button will be surfaced in the UI that intents to this URL when clicked. Version 1.1 added support for intent:// links in Scene Viewer in order to allow the Scene Viewer visit button to trigger directly into other apps. Note that this should be used with care and should only be specified when an intent handler is guaranteed to be present for the given intent.
title (optional)	Valid string	A name for the model. If present, it will be displayed in the UI. The name will be truncated with ellipses after 60 characters. Version 1.1 added support for html styling of title content, with an arbitrary amount of text allowed. Note that the title should be url-escaped.
sound (optional)	A valid URL	A URL to a looping audio track that is synchronized with the first animation embedded in a glTF file.. It should be provided alongside a glTF with an animation of matching length. If present, the sound is looped after the model is loaded.
resizable (optional)	true (default) false	When set to false, users will not be able to scale the model in the AR experience. Scaling works normally in the 3D experience.
disable_occlusion (optional)	false (default) true	When set to true, objects placed in the scene always appear in front of real world objects in the scene. See [Enable occlusion](/ar/develop/depth#enable_occlusion) for more information.

UX guidance

To provide the best possible UX for users, we recommend following these guidelines.

• For AR experiences, the visible call to action should convey that the user is about to enter an immersive environment. We recommend that you use the View in your space call to action:
  

• It's possible that users may not have Google Play Services for AR installed on their device. Here is how <model-viewer> handles the fallback and you can feel free to use that piece of code as a starting point.

  // Check whether this is an Android device.
  const isAndroid = /android/i.test(navigator.userAgent);
  // This fallback URL is used if the Google app is not installed and up to date.
  const fallbackUrl = 'https://arvr.google.com/scene-viewer?file=https%3A%2F%2Fstorage.googleapis.com%2Far-answers-in-search-models%2Fstatic%2FTiger%2Fmodel.glb&link=https%3A%2F%2Fgoogle.com&title=Tiger';
  
  // This intent URL triggers Scene Viewer on Android and falls back to
  // fallbackUrl if the Google app is not installed and up to date.
  const sceneViewerUrl = 'intent://arvr.google.com/scene-viewer/1.0?file=https://storage.googleapis.com/ar-answers-in-search-models/static/Tiger/model.glb&title=Tiger#Intent;scheme=https;package=com.google.android.googlequicksearchbox;action=android.intent.action.VIEW;S.browser_fallback_url=' +
      fallbackUrl + ';end;';
  
  // Create a link.
  var a = document.createElement('a');
  a.appendChild(document.createTextNode('Tiger'));
  // Set the href to the intent URL on Android and the fallback URL
  // everywhere else.
  a.href = isAndroid ? sceneViewerUrl : fallbackUrl;
  // Add the link to the page.
  document.body.appendChild(a);
  

Using <model-viewer> to launch Scene Viewer

You can enable Scene Viewer from your website by including the <model-viewer> web component with the ar attribute.

<model-viewer ar
              ar-modes="scene-viewer webxr quick-look"
              alt="A 3D model of an astronaut."
              src="Astronaut.gltf"></model-viewer>

When viewed on an ARCore-supported Android device, a website that includes the <model-viewer> component with the ar attribute displays a button as shown in the following example.

When the scene-viewer mode is used in ar-modes, it switches to a native AR view and invites the user to place the model in their environment using Scene Viewer.

If Google Play Services with AR isn't present, tapping this button displays the model in <model-viewer>'s 3D viewer.

See the documentation for <model-viewer> for more information on how to get started with <model-viewer>.

File requirements for models

Scene Viewer has the following support and limitations for models.

Using the previewer tool to validate your 3D models

To ensure your 3D model file will display properly in Scene Viewer, use our online previewer tool to validate the files on your PC.

Validating your 3D model

To validate a model, the previewer tool needs one glb or glTF file, any associated image and bin files, and an optional audio file. The audio file will loop along with animation 0.

You can multi-select individual files, or optionally put the glb or glTF and its associated files into a zip file. (The zip file method doesn't support audio files.)

To validate your 3D model:

1. Open the online previewer tool in a browser.

2. Use one of these methods to add the files to the previewer tool:

   • Drag and drop. Select a glb or glTF file and all of its associated files (or a zip file containing these files), and drag the selected files or zip file to the previewer tool.

   • From the previewer tool. In the previewer tool, choose Scene Viewer > Load File. Select a glb or glTF file and all of its associated files (or a zip file containing these files), and click Open.

After you load the files consisting of your 3D model into the previewer tool, a console at the bottom of the browser displays the results, including any error messages.

Adding 3D models for validation

To validate a 3D model, add the files that make up the 3D model to our Model Editor tool.

To validate a model, the previewer needs the model's glb or glTF file, any associated image and bin files, and an optional audio file. You can multi-select individual files or add a single zip file.

When adding a zip file, the previewer loads the first glb or glTF it finds, as well as the associated image and bin files within that zip file.

1. Open the Model Editor tool in a browser.

2. Use one of these methods to add the files to the previewer tool:

   • To drag and drop files for validation, multi-select the glb or glTF file and any associated files (or select a zip file containing these files), and drag it to the previewer tool.

   • Select files from previewer tool. In the previewer tool, choose Scene Viewer > Load File. Multi-select the glb or glTF file and all of its associated files (or a zip file containing these files), and click Open.

Validation errors