Implement custom AR button

This document describes how to integrate a custom button into your application to display Roomle product configurations in Augmented Reality (AR) on mobile devices.

Overview:

Roomle's AR functionality leverages the native AR frameworks of iOS (AR Quick Look) and Android (Google Scene Viewer). Therefore, the implementation of an AR button must be device-dependent.

1. Device Detection: First, determine if the user is accessing the page with an iOS, Android, or Desktop device.

2. Fetching Data: Depending on the device, the appropriate 3D model (USDZ for iOS, glTF/GLB for Android) is fetched via the Roomle API.

3. Launching AR View:

   • iOS: The USDZ model is opened directly in the AR Quick Look viewer.

   • Android: A specific Intent link is constructed and invoked to launch the GLB model in the Google Scene Viewer.

   • Desktop: A QR code is displayed, linking to a mobile landing page. This page then performs steps 1-3 for mobile devices.

Prerequisites:

• You need a valid configurationId for the Roomle product you want to display in AR.

You have to save the configuration to get the configurationID:

await RoomleConfigurator.extended.saveCurrentConfiguration();

Implementation Details:

1. Device Detection:

Implement logic (e.g., using JavaScript navigator.userAgent or a suitable library) to identify the user's operating system. You need to differentiate between iOS, Android, and others (Desktop).

2. Fetching 3D Assets:

Use the following Roomle API V2 endpoints to get the URLs for the required 3D files. Replace :configurationId with the ID of your configuration.

• For iOS (USDZ):

  JavaScript

  /**
   * Generates the URL to fetch the USDZ file for a given configuration ID.
   * @param {string} configurationId - The ID of the Roomle configuration.
   * @returns {string} The full URL to the USDZ file.
   */
  const getUsdzUrl = (configurationId) => {
    return (
      'https://api.roomle.com/v2' +
      '/configurations/' +
      configurationId +
      '/3dAssets/usdz/conf.usdz'
    );
  };

• For Android (GLB):

  JavaScript

  /**
   * Generates the URL to fetch the GLB file (glTF Binary) for a given configuration ID.
   * @param {string} configurationId - The ID of the Roomle configuration.
   * @returns {string} The full URL to the GLB file.
   */
  const getGlbUrl = (configurationId) => {
    return (
      'https://api.roomle.com/v2' +
      '/configurations/' +
      configurationId +
      '/3dAssets/glTF/conf.glb'
    );
  };

3. Launching AR View:

• iOS Implementation:

  1. Call getUsdzUrl(configurationId) to get the URL for the USDZ file.

  2. Redirect the browser directly to this URL. iOS recognizes the .usdz extension and automatically opens the AR Quick Look viewer.JavaScript

     // Example:
     const usdzUrl = getUsdzUrl('YOUR_CONFIG_ID');
     window.location.href = usdzUrl; // Or use an equivalent method in your framework

• Android Implementation:

  1. Call getGlbUrl(configurationId) to get the URL for the GLB file.

  2. Construct the following Intent link. Important: The glbUrl must be URL-encoded before being inserted into the intent string.JavaScript

     // Example:
     const glbUrl = getGlbUrl('YOUR_CONFIG_ID');
     const encodedGlbUrl = encodeURIComponent(glbUrl); // Important: Encode the URL!
     
     const intentUrl =
      'intent://arvr.google.com/scene-viewer/1.0?file=' +
       glbUrl +
       '&mode=ar_only' +
       '&resizable=false' +
       '&enable_vertical_placement=true' +
       '#Intent;scheme=https;package=com.google.android.googlequicksearchbox;action=android.intent.action.VIEW;end;'
     
     window.location.href = intentUrl; // Or use an equivalent method

  3. When this Intent link is invoked, Android opens the Google Scene Viewer with the 3D model.

• Desktop Implementation:

  1. If a desktop device is detected, display a QR code instead of a direct link.

  2. The QR code should encode a URL pointing to a specially created mobile landing page (e.g., https://your-domain.com/ar-mobile?configId=YOUR_CONFIG_ID).

  3. On this mobile landing page, perform the device detection again (Step 1) and then trigger the appropriate iOS or Android implementation (Step 3).

  4. You can use JavaScript libraries (like qrcode.js) to dynamically generate the QR code in the browser, or create it server-side.