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 and simple:

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

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

Supported use cases

Intended use case Recommended application Benefits
From a button or link on a website or Android app, launch a native AR view of a 3D model.

If Google Play Services for AR isn't present on the device, fall back gracefully to showing the model in a Scene Viewer-powered 3D mode.
Launch Scene Viewer using an explicit intent to the Google Search package, and choose an appropriate mode setting for displaying the 3D model.
  • ar_preferred: Always starts in an AR viewer, and users can manually switch to a 3D viewer. If Google Play Services for AR isn’t present, gracefully falls back to starting in the 3D viewer.
  • 3d_preferred: Always starts in a 3D viewer, and users can manually switch to an AR viewer. If Google Play Services for AR isn’t present, users can’t switch away from 3D viewer.
  • 3d_only: Always displays only in a 3D viewer, with no way for users to switch to an AR viewer.
  • Support the widest possible range of devices.
  • Automatically fall back to native 3D mode of Scene Viewer for non-AR use cases.
From a button or link on a website or Android app, launch a native AR view of a 3D model.

If Google Play Services for AR isn't present on the device, control the fallback behavior.
Launch Scene Viewer using an explicit intent to Google Play Services for AR (ARCore), and choose an appropriate mode setting for displaying the 3D model.
  • ar_preferred: Always starts in AR viewer, and users can manually switch to a 3D viewer. If Google Play Services for AR isn’t present, Scene Viewer falls back to behavior you configure.
  • ar_only: Always displays in AR viewer only, with no ability to switch to a 3D viewer. If Google Play Services for AR isn’t present, falls back to behavior you configure. For example, you might launch your own full-screen 3D experience or show a friendly error message indicating the user's device doesn't yet support AR capabilities.
Use your own 3D model viewer or provide another fallback response of your own design for non-AR use cases.
Host an inline view of a 3D model on your website, and allow the user to manually enter into a full-screen native AR mode. Use <model-viewer> or any other web-based 3D viewer to launch Scene Viewer natively displaying the 3D model in AR.
  • Launch Scene Viewer natively in AR directly from a 3D model embedded in a web page.
  • Provide users a 3D experience on a surface you own and control, with the option of gradually transitioning them to a more immersive AR experience once you understand their intent to do so.

Launch Scene Viewer using an explicit intent to the Google Search package (3D or AR)

To support the widest range of Android devices, use an explicit Android intent to launch Scene Viewer from the com.google.android.googlequicksearchbox Search package. The explicit intent can be triggered from an HTML page or a native Android app.

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, Scene Viewer can show the model in an AR native view or 3D view.

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

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

<a href="intent://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>

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

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

Supported intent parameters

The following parameters are supported for an explicit intent to the Google Search 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 the Google app com.google.android.googlequicksearchbox is not present on the device, this is the URL it 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 com.google.android.googlequicksearchbox.

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.
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.

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://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;"&gt;Avocado&lt;/a&gt;

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

Intent sceneViewerIntent = new Intent(Intent.ACTION\_VIEW);
sceneViewerIntent.setData(Uri.parse("https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf?mode=ar\_only"));
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 (com.google.ar.core) is not present on the device, 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.

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.
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.

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 (com.google.ar.core) 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 web fallback url will launch if the correct version of the Google app is
    // not available.
    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 is the intent launching URL that triggers Scene Viewer on Android
    // and falls back to fallbackUrl if the Google app is not available.
    const sceneViewerUrl =
    
    'intent://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 links 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 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 user taps this button, it switches to a native AR view and invites the user to place the model in their environment.

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

File requirements for models

Scene Viewer has the following support and limitations for models.

File format supportglTF 2.0/glb, using these extensions:
  • KHR_materials_unlit
  • KHR_texture_transform
Animation
  • Looping skeletal animation
  • Looping rigid animation
  • Looping transform animation
The animation will be played on loop. If the glTF file contains multiple animations, Scene Viewer plays only the first animation.
Recommended limits The overall performance of assets depends on setting constraints and making tradeoffs between vertices, materials, texture resolution, mesh per material, and other factors. Use the following guidelines to optimize what works best for your assets.
  • Number of triangles: The recommended limit is 100,000 triangles, but targeting the lowest number will maintain high performance in Scene Viewer. 30,000 to 50,000 is an ideal range.
  • Number of materials: The recommended limit is 10 materials, two of which can be alpha. Target the lowest number possible to keep the asset performing well.
  • Mesh per material: 1
  • Max texture resolution: 2048 × 2048
  • Bone (including non-weighted joints): 254 (hard limit)
  • Bone weights per vertex limit: 4 (hard limit)
  • UV: 1 UV per mesh (hard limit)
  • Model size: 10 MB (bigger models may result in poor user experience)
Shadow supportHard shadows are automatically rendered by Scene Viewer when placing an object, so we recommend against baking shadows into your model.
Texture support
  • PNG format: PNG-24, indexed PNG-8. JPGs are preferred when there is no transparency to reduce size.
  • Color space: sRGB
MaterialPBR
File loadingHTTPS
Scene
  • Axis: right-handed, with these properties:
    • +X is right
    • +Y is up
    • -Z points forward from the origin (in other words, the "front" of an asset should be facing +Z)
  • Scale: 1 unit = 1 meter (as defined by the glTF specification to ensure the model is placed in AR in true scale)

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 online previewer 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 online previewer tool in a browser.

    • 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 previwer 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

Error Code Severity Message Current Supported Values
INVALID_INPUT_FILE_EXTENSION Error The input file [filename] has a file extension that is not supported by the validator.
REC_INPUT_BINARY_SIZE_EXCEEDED Warning The provided user input has a binary size that exceeds the limit recommended by the Scene Viewer specification, which is a recommended size limit of [size] MB. 10
MAX_INPUT_BINARY_SIZE_EXCEEDED Error The provided user input has a binary size that exceeds the maximum limit supported by the Scene Viewer specification, which is a maximum size limit of [size] MB. 15
UNSUPPORTED_GLTF_EXTENSION_USED Error The extension [ext] in the glTF is not supported by the Scene Viewer specification. ['KHR_materials_pbrSpecularGlossiness', 'KHR_materials_unlit', 'KHR_texture_transform']
ANIMATION_LIMIT_EXCEEDED Error The number of animations in the glTF exceeds the limit supported by the Scene Viewer specification, which is a maximum of [num] animations. 1
MORPH_TARGET_USED Error The glTF contains a morph target, which is not supported by the Scene Viewer specification.
MATERIAL_LIMIT_EXCEEDED Warning The number of materials in the glTF exceeds the limit recommended by the Scene Viewer specification, which is a maximum of [num] materials. 10
TEXTURE_RESOLUTION_LIMIT_EXCEEDED Warning The resolution of the image at index [idx] in the glTF exceeds the limit recommended by the Scene Viewer specification, which is a maximum resolution of [res] x [res]. 2048 x 2048
UV_LIMIT_EXCEEDED Error The number of UV per mesh in the glTF exceeds the limit supported by the Scene Viewer specification, which is a maximum of [num] UV per mesh. 1
VERTEX_COLOR_USED Error The glTF contains a vertex color, which is not supported by the Scene Viewer specification.
JOINT_LIMIT_EXCEEDED Error The number of joints in the glTF exceeds the limit supported by the Scene Viewer specification, which is a maximum of [num] joints. 254
TRIANGLE_LIMIT_EXCEEDED Warning The number of triangles in the glTF exceeds the limit recommended by the Scene Viewer specification, which is a maximum of [num] triangles. 100,000
PRIMITIVE_MODE_UNSUPPORTED Error The primitive mode [mode] is not supported by the Scene Viewer specification. {4 : Triangle List, 5 : Triangle Strip, 6 : Triangle Fan}
MISSING_PBR_METALLIC_ROUGHNESS Information The material at index [idx] is missing the pbrMetallicRoughness property. This is not required by the Scene Viewer specification if metallic and roughness factors are used instead. If neither of these are used, then the material will use default values, which may lead to unintended behavior.