Skip to main content

Custom AR Flow

Introduction​

This guide will walk you through configuring a custom AR flow using Mimeeq's API, focusing on handling AR functionality across mobile and desktop devices. The setup includes the following flows:

  • Mobile Flow: Works out of the box. Users simply click the AR button to start the AR experience.
  • Desktop Flow: Displays a modal with a QR code and URL directing users to a mobile AR landing page.
  • Switching from Desktop to Mobile: Users can switch devices by using the QR code or URL provided in the desktop modal, which includes the AR short code necessary to continue the AR experience on mobile.

Mobile Flow​

The mobile flow is straightforward and works out of the box. When users access the AR functionality on a mobile device, they only need to click the AR button to initiate the AR experience. Mimeeq's API handles this process seamlessly.

Details​

  • Out of the Box Functionality: The mobile AR feature is enabled by default.
  • General AR Settings: General settings enable AR for customers, and per-product settings can specify AR scaling if needed.
  • Error Handling: The AR landing page manages errors. If the AR model doesn't generate correctly, a failure page is shown, allowing users to go back to the configurator or retry. If the device doesn't support AR, an incompatible device view is displayed with an option to return to the configurator.

Desktop Flow​

On desktop devices, AR functionality is not supported. When users attempt to access the AR feature, a modal is displayed containing a QR code and a URL with the arShortCode parameter. Users can scan the QR code or copy the URL to switch to a mobile device for the AR experience.

Steps​

  1. User Action: User clicks the AR button on a desktop device.
  2. Modal Display: A modal appears with a QR code and a URL containing the arShortCode.
  3. Switch to Mobile: User scans the QR code or copies the URL to access the AR experience on their mobile device.

Details​

  • Modal Content: The default modal includes the QR code and URL.
  • URL Generation: The current URL is appended with the arShortCode query parameter. Future updates may include customizable URL generation via the MimeeqApiConfig configuration object.

Switching from Desktop to Mobile​

Switching from desktop to mobile involves transferring the AR short code via the QR code or URL from the desktop modal. This ensures users can seamlessly continue their AR experience on a mobile device.

Step-by-Step Guide​

Detecting arShortCode in URL​

To properly manage the transition from the desktop flow to the mobile flow for AR, follow these steps to detect the arShortCode parameter from the URL:

  1. Check for Query Parameters:

    • Parse the URL to extract query parameters.
    • Look for the presence of the arShortCode parameter.

  2. Extracting arShortCode:

    • Once the query parameters are obtained, extract the value of the arShortCode parameter, which represents the unique identifier for the AR content.

Example JavaScript code to detect and extract the arShortCode from the URL:

// Parse URL and extract query parameters
const urlParams = new URLSearchParams(window.location.search);
const arShortCode = urlParams.get('arShortCode');

Triggering showAR Method​

After successfully detecting the arShortCode, proceed to trigger the showAR method on the mmq-embed custom element, passing the extracted arShortCode as a parameter.

// Assuming `mmq-embed` is the ID or class of the custom element
const mmqEmbedElement = document.querySelector('mmq-embed');

if (mmqEmbedElement) {
  // Trigger the `showAR` method with the extracted `arShortCode`
  mmqEmbedElement.showAR({ arShortCode });
} else {
  console.error('mmq-embed element not found. Cannot run showAR method.');
}

(Optional) Handling Incompatible AR Scenarios​

In cases where the AR content is incompatible with the current device, include an additional query parameter, incompatible, with any value. Modify the showAR method to handle this scenario:

  1. Detect Incompatible Parameter:

    • Check for the presence of the incompatible parameter in the URL.

  2. Handling Incompatible Scenario:

    • If the incompatible parameter is present, pass it along with the arShortCode to the showAR method.
    • The showAR method can then handle the incompatible scenario appropriately, such as displaying a message indicating incompatibility with the current device.
// Extracting `incompatible` parameter from URL
const incompatible = urlParams.has('incompatible');

// Triggering `showAR` method with `arShortCode` and `incompatible` flag
mmqEmbedElement.showAR({
  arShortCode,
  incompatible,
});

Example Implementation: Integrating AR Flow​

To seamlessly integrate the AR flow into your web application, follow these steps using the provided example:

  1. HTML Setup:

    • Include the mmq-embed custom element within your HTML document.
    • Assign it an id attribute for easy access in JavaScript.
    • Set the short-code and template attributes with the desired values.

  2. JavaScript Function:

    • Define a JavaScript function to handle the mimeeq-app-loaded event, which signifies that the mmq app has loaded.
    • Within this function:
      • Extract the arShortCode and incompatible flag from the URL parameters using URLSearchParams.
      • Retrieve the mmq-embed element by its ID.
      • Check if the element exists:
        • If it does, trigger the showAR method with the extracted arShortCode and incompatible flag.
        • If not, log a warning indicating that the element was not found.

  3. Event Listener:

    • Add an event listener to listen for the mimeeq-app-loaded event.
    • Upon the event being fired, execute the JavaScript function defined earlier.

Full Example:​

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>AR Flow Integration</title>
  </head>
  <body>
    <!-- mmq-embed custom element with parameters -->
    <mmq-embed id="mmqEmbed" short-code="YOUR_EMBED_SHORTCODE" template="YOUR_TEMPLATE"></mmq-embed>

    <script>
      // Function to handle mimeeq-app-loaded event
      function handleMmqAppLoaded() {
        // Extract arShortCode and incompatible flag from URL parameters
        const urlParams = new URLSearchParams(window.location.search);
        const arShortCode = urlParams.get('arShortCode');
        const incompatible = urlParams.has('incompatible');

        // Find mmq-embed element by ID
        const mmqEmbedElement = document.getElementById('mmqEmbed');

        // Check if mmq-embed element exists
        if (mmqEmbedElement) {
          // If arShortCode exists, call showAR method with arShortCode and incompatible flag
          if (arShortCode) {
            mmqEmbedElement.showAR({
              arShortCode,
              incompatible,
            });
          } else {
            // Warning: No arShortCode found in URL
            console.warn('No arShortCode found in URL.');
          }
        } else {
          // Warning: mmq-embed element not found
          console.warn('mmq-embed element not found.');
        }
      }

      // Add event listener for mimeeq-app-loaded event
      document.addEventListener('mimeeq-app-loaded', handleMmqAppLoaded);
    </script>
  </body>
</html>

This example provides a structured approach to integrating the AR flow into your web application, ensuring smooth handling of the arShortCode and compatibility flags. Developers can customize this example to fit their specific requirements.

Custom AR Flow using your own components​

Introduction​

This guide explains how to create a custom AR flow using your own components instead of the built-in Mimeeq components. You will use methods from the mimeeqApi.actions interface to handle AR model generation, retrieval, and display.

Mimeeq API Methods for AR Integration​

Generate AR Model​

To trigger the generation of an AR model and obtain its shortcode, use the generateAR method. For more details, refer to the Generate AR section of the Mimeeq API documentation.

const generateAR: GenerateAR = async () => {
  const arShortCode = await window.mimeeqApp.actions.generateAR();
  return arShortCode;
};

Regenerate AR Model​

If the generation of the AR model fails, you can use the regenerateAR method to attempt re-generation. For more details, refer to the Regenerate AR section of the Mimeeq API documentation.

const regenerateAR: RegenerateAR = async (arData: ARShortcodeData) => {
  const arShortCode = await window.mimeeqApp.actions.regenerateAR(arData);
  return arShortCode;
};

Get AR Short Code Data​

To retrieve data for a given AR short code, use the getARShortCodeData method. For more details, refer to the Get AR Short Code Data section of the Mimeeq API documentation.

const getARShortCodeData: GetARShortCodeData = async (
  arShortCode: string,
  withSubscription?: boolean,
) => {
  const arData = await window.mimeeqApp.actions.getARShortCodeData(arShortCode, withSubscription);
  return arData;
};

Example Usage​

Step 1: Generate AR Shortcode​

First, generate the AR shortcode for the current product configuration:

async function generateARShortcode() {
  try {
    const arShortCode = await window.mimeeqApp.actions.generateAR();
    return arShortCode;
  } catch (error) {
    console.error('Error generating AR shortcode:', error);
  }
}

Step 2: Process Based on Device​

Depending on whether the user is on a mobile or desktop device, you may want to progress in different ways. For example, you may want to show a modal that allows the user to seamlessly move to a mobile device when on desktop.

async function handleARFlow() {
  const arShortCode = await generateARShortcode();
  if (!arShortCode) return;

  const isMobile = /Mobi|Android/i.test(navigator.userAgent);
  const arUrl = `${window.location.origin}/ar-viewer?shortcode=${arShortCode}`;

  if (isMobile) {
    window.location.href = arUrl;
  } else {
    // Display a modal with a QR code
    showModalWithQRCode(arUrl);
  }
}

Step 3: Retrieve AR Data on Landing Page​

On your landing page, retrieve the AR data using the shortcode:

async function getARData(arShortCode) {
  try {
    const arData = await window.mimeeqApp.actions.getARShortCodeData(arShortCode, true);
    return arData;
  } catch (error) {
    console.error('Error retrieving AR data:', error);
  }
}

Step 4: Validate and Display AR Data​

Check if the AR files exist and are valid, then prepare the URLs for the 3D models:

async function validateAndDisplayAR(arShortCode) {
  let arData = await getARData(arShortCode);
  if (!arData) {
    console.log('No AR data found for provided shortcode');
    return;
  }

  const isAndroid = /Android/i.test(navigator.userAgent);
  let fileUrlExists = !!(isAndroid ? arData.glbPath : arData.usdzPath);

  if (!fileUrlExists && arData.completeSubscription) {
    // If files don't exist yet and we have a completion subscription, wait for it to resolve
    try {
      // Since AR generation shouldn't take more than 1-2 minutes, add a timeout
      const timeout = window.setTimeout(() => {
        throw new Error('AR Generation Timeout');
      }, 120 * 1000);

      const appSyncResult = await arData.completeSubscription;
      clearTimeout(timeout);
      // If the result and conversion status is completed, fill out model paths
      if (appSyncResult && appSyncResult.conversionStatus === 'COMPLETED') {
        arData = {
          ...arData,
          glbPath: appSyncResult.glbPath,
          usdzPath: appSyncResult.usdzPath,
          conversionStatus: appSyncResult.conversionStatus,
        };
      }
    } catch (e) {
      console.error(e);
    }
  }

  // Check again if the file URL exists
  fileUrlExists = !!(isAndroid ? arData.glbPath : arData.usdzPath);

  if (!fileUrlExists) {
    console.log('AR files do not exist');
    return;
  }

  const glbLink = prepareGlbLink(arData);
  const usdzLink = prepareUsdzLink(arData);

  // Display AR links or QR codes
  displayARLinks(glbLink, usdzLink);
}

function prepareGlbLink(arData) {
  const allowScaling = true;
  const glbFile = `${CDNPath}/${arData.glbPath}`;
  return `intent://arvr.google.com/scene-viewer/1.0?file=${glbFile}&mode=ar_preferred&resizable=${allowScaling ? 'true' : 'false'}&title=${encodeURIComponent(arData.productName)}&link=${arData.url}#Intent;scheme=https;package=com.google.ar.core;action=android.intent.action.VIEW;end;`;
}

function prepareUsdzLink(arData) {
  const allowScaling = false;
  const usdzFile = `${CDNPath}/${arData.usdzPath}#allowsContentScaling=${allowScaling ? '1' : '0'}`;
  return usdzFile;
}

Conclusion​

By following the steps outlined above, you can create a fully customized AR flow using the Mimeeq API. This allows you to generate AR models, retrieve their data, and present them to users in a way that fits your specific requirements.

Further Considerations and Good to Know​

Custom AR Button Integration​

If you prefer to use your own AR button instead of Mimeeq's default AR button, you can do so by directly triggering the mimeeqApp.actions.showAR() method. This method will handle both the desktop and mobile flows appropriately based on the device.

  • Using Custom AR Button: Implement your custom AR button and attach an event listener to it.
  • Triggering AR Flow: Within the event listener, call mimeeqApp.actions.showAR() to start the AR experience.

Example​

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Custom AR Button</title>
  </head>
  <body>
    <!-- Custom AR Button -->
    <button id="customARButton">View in AR</button>

    <!-- mmq-embed custom element -->
    <mmq-embed id="mmqEmbed" short-code="YOUR_EMBED_SHORTCODE" template="YOUR_TEMPLATE"></mmq-embed>

    <script>
      // Function to handle AR button click
      function handleARButtonClick() {
        mimeeqApp.actions.showAR();
      }

      // Add event listener to the custom AR button
      document.getElementById('customARButton').addEventListener('click', handleARButtonClick);
    </script>
  </body>
</html>