Augmented Reality Integration

Introduction

Augmented Reality (AR) creates a powerful way for customers to visualize products in their actual environment, dramatically enhancing the buying experience. This guide explains how to integrate Mimeeq's AR capabilities into your application, covering both standard and custom implementations.

Business Value of AR Integration

• Increased Customer Confidence - Allows customers to see exactly how products will fit and look in their space before purchasing
• Reduced Returns - By setting accurate expectations about product dimensions and appearance
• Higher Conversion Rates - Studies show AR experiences can increase conversion by 30-40%
• Competitive Advantage - Provides an immersive experience that differentiates your product offerings
• Cross-Device Experience - Seamlessly transitions customers from desktop browsing to mobile AR interaction
• Enhanced Product Storytelling - Creates memorable interactions that build stronger connections with your brand

AR Experience Flow Overview

Mimeeq's AR functionality provides a seamless experience across different devices:

Mobile Experience

On mobile devices (iOS and Android), the AR experience activates directly:

1. User taps the AR button while viewing a configured product
2. If supported, device directly launches the native AR viewer with the product model
3. User can place and view the product in their real environment
4. Special features like scaling can be enabled if needed

Desktop to Mobile Transition

Since AR requires device cameras and motion sensors, desktop users need a seamless way to switch to a mobile device:

1. User clicks the AR button on desktop
2. Modal appears with a QR code and URL containing the AR short code
3. User scans the QR code or copies the URL to their mobile device
4. Mobile device opens the AR experience directly with the same product configuration

Implementation Options

You can integrate AR capability using two main approaches:

1. Built-in Experience (Easiest)

Use Mimeeq's pre-built AR component for a complete, ready-to-use experience:

• Simple Integration - Just a few lines of code to add full AR capabilities
• Automatic Device Detection - Properly handles desktop, mobile, and device transitions
• Error Handling - Built-in handling of incompatible devices and generation failures
• QR Code Generation - Automatic generation of codes for cross-device experience

2. Custom Implementation (Most Flexible)

Build your own AR experience using the Mimeeq API for complete control:

• Custom UI - Design your own AR buttons, modals, and landing pages
• Specialized Workflows - Create unique AR journeys tailored to your customers
• Brand Integration - Seamlessly incorporate your design language and brand elements
• Advanced Features - Implement custom behaviors beyond the standard AR experience

Built-in AR Implementation

Basic Integration

The simplest way to add AR capability is through the mmq-embed web component:

<mmq-embed 
    id="productConfigurator" 
    short-code="YOUR_EMBED_SHORTCODE" 
    template="YOUR_TEMPLATE">
</mmq-embed>

With this integration, the AR functionality is automatically available through the standard AR button in the interface. No additional code is required!

Programmatically Triggering AR

If you prefer to use your own custom AR button:

<button id="customARButton">View in Your Space</button>

<script>
  document.getElementById('customARButton').addEventListener('click', () => {
    // Find the mmq-embed element
    const configurator = document.querySelector('mmq-embed');
    
    // Call the showAR method to start the AR experience
    if (configurator) {
      configurator.showAR();
    }
  });
</script>

Handling AR Shortcodes from URLs

When a user navigates from desktop to mobile using a URL with an AR shortcode:

<script>
  // Function to handle the mimeeq-app-loaded event
  function handleMimeeqAppLoaded() {
    // Extract AR parameters from URL
    const urlParams = new URLSearchParams(window.location.search);
    const arShortCode = urlParams.get('arShortCode');
    const incompatible = urlParams.has('incompatible');
    
    // Find the mmq-embed element
    const configurator = document.getElementById('productConfigurator');
    
    // If AR shortcode exists, start the AR experience
    if (configurator && arShortCode) {
      configurator.showAR({
        arShortCode,
        incompatible
      });
    }
  }
  
  // Listen for the mimeeq-app-loaded event
  document.addEventListener('mimeeq-app-loaded', handleMimeeqAppLoaded);
</script>

Custom AR Implementation

For complete control over the AR experience, you can build a custom implementation using the Mimeeq API. This approach is ideal when you need to integrate AR into a specialized workflow or create a unique brand experience.

Key API Methods

The Mimeeq API provides several methods for working with AR models:

1. Generate AR Model

Creates an AR-ready 3D model from the current product configuration:

async function generateARShortcode() {
  try {
    // This creates the 3D model optimized for AR viewing
    const arShortCode = await window.mimeeqApp.actions.generateAR();
    return arShortCode;
  } catch (error) {
    console.error('Error generating AR model:', error);
    return null;
  }
}

2. Retrieve AR Model Data

Fetches all information about a previously generated AR model:

async function getARModelData(arShortCode) {
  try {
    // The second parameter (true) includes a subscription for model processing status
    const arData = await window.mimeeqApp.actions.getARShortCodeData(arShortCode, true);
    return arData;
  } catch (error) {
    console.error('Error retrieving AR model data:', error);
    return null;
  }
}

3. Regenerate AR Model (When Needed)

Attempts to recreate an AR model if the initial generation fails:

async function attemptModelRegeneration(arData) {
  try {
    const arShortCode = await window.mimeeqApp.actions.regenerateAR(arData);
    return arShortCode;
  } catch (error) {
    console.error('Error regenerating AR model:', error);
    return null;
  }
}

Building a Complete Custom AR Flow

Here's a comprehensive example of creating a custom AR experience:

// 1. Handle AR button click
document.getElementById('customARButton').addEventListener('click', handleARButtonClick);

async function handleARButtonClick() {
  // Show loading indicator
  showLoadingSpinner();
  
  try {
    // 2. Generate the AR model
    const arShortCode = await generateARShortcode();
    if (!arShortCode) {
      showErrorMessage("Couldn't create AR model. Please try again.");
      hideLoadingSpinner();
      return;
    }
    
    // 3. Create the AR URL
    const arUrl = `${window.location.origin}/ar-viewer?shortcode=${arShortCode}`;
    
    // 4. Detect device type and handle accordingly
    const isMobile = /Mobi|Android/i.test(navigator.userAgent);
    
    if (isMobile) {
      // On mobile: Redirect to AR viewer
      window.location.href = arUrl;
    } else {
      // On desktop: Show QR code modal
      hideLoadingSpinner();
      showQRCodeModal({
        arShortCode,
        arUrl,
        productName: getCurrentProductName()
      });
    }
  } catch (error) {
    console.error('AR process failed:', error);
    hideLoadingSpinner();
    showErrorMessage("Something went wrong with AR. Please try again.");
  }
}

// Function to generate QR code content
function showQRCodeModal(data) {
  const modal = document.getElementById('arQRCodeModal');
  const qrCodeElement = document.getElementById('arQRCode');
  const urlElement = document.getElementById('arUrl');
  
  // Generate QR code for the URL
  generateQRCode(qrCodeElement, data.arUrl);
  
  // Display the URL for copying
  urlElement.textContent = data.arUrl;
  urlElement.href = data.arUrl;
  
  // Show product information
  document.getElementById('arProductName').textContent = data.productName;
  
  // Display the modal
  modal.style.display = 'flex';
}

AR Viewer Landing Page

For a custom AR landing page that handles the transition from desktop to mobile:

// Code for your AR landing page
document.addEventListener('DOMContentLoaded', async () => {
  // Extract shortcode from URL
  const urlParams = new URLSearchParams(window.location.search);
  const arShortCode = urlParams.get('shortcode');
  
  if (!arShortCode) {
    showErrorState("No AR model information found");
    return;
  }
  
  // Show loading state
  showLoadingState("Preparing your AR experience...");
  
  // Get AR model data
  const arData = await getARModelData(arShortCode);
  
  if (!arData) {
    showErrorState("Could not load AR model");
    return;
  }
  
  // Check if model processing is complete
  if (needsProcessing(arData)) {
    showProcessingState("Optimizing your 3D model for AR viewing...");
    
    try {
      // Wait for model processing to complete (with timeout)
      const processingResult = await waitForProcessingWithTimeout(arData, 120000);
      
      if (processingResult.success) {
        // Model is ready - proceed to AR display
        launchARExperience(processingResult.data);
      } else {
        // Processing failed or timed out
        showErrorState("AR model preparation failed. Please try again.");
      }
    } catch (error) {
      showErrorState("Something went wrong. Please try again.");
    }
  } else if (modelFilesExist(arData)) {
    // Model is already processed and files exist
    launchARExperience(arData);
  } else {
    // Model processing completed but files don't exist
    showErrorState("AR model files not found. Please try again.");
  }
});

// Function to launch the actual AR experience
function launchARExperience(arData) {
  const isAndroid = /Android/i.test(navigator.userAgent);
  const isiOS = /iPhone|iPad|iPod/i.test(navigator.userAgent);
  
  if (isAndroid && arData.glbPath) {
    // Launch Android AR experience
    const glbFile = `${CDNPath}/${arData.glbPath}`;
    const arLink = `intent://arvr.google.com/scene-viewer/1.0?file=${glbFile}&mode=ar_preferred&resizable=${arData.allowScaling ? 'true' : 'false'}&title=${encodeURIComponent(arData.productName)}&link=${arData.url}#Intent;scheme=https;package=com.google.ar.core;action=android.intent.action.VIEW;end;`;
    
    window.location.href = arLink;
  } else if (isiOS && arData.usdzPath) {
    // Launch iOS AR experience
    const usdzFile = `${CDNPath}/${arData.usdzPath}#allowsContentScaling=${arData.allowScaling ? '1' : '0'}`;
    
    window.location.href = usdzFile;
  } else {
    // Device not supported
    showIncompatibleState("Your device doesn't support AR for this product");
  }
}

Best Practices & Considerations

User Experience

• Clear Instructions - Provide guidance on how to use AR effectively
• Fast Loading Indicators - Show progress during model generation and loading
• Fallback Options - Offer alternatives when AR isn't available or doesn't work
• Context Preservation - Maintain product configuration when switching devices

Technical Considerations

• Model Size Optimization - Balance detail and file size for faster loading
• Mobile Detection - Accurately detect mobile devices to provide the right experience
• Error Handling - Implement comprehensive error handling for various failure scenarios
• Network Conditions - Consider variable network speeds when downloading AR models

Business Strategy

• Start Simple - Begin with built-in implementation before customizing
• Measure Impact - Track engagement and conversion metrics specifically for AR users
• Progressive Enhancement - Offer AR as an additional option, not a requirement
• Customer Education - Create tutorials or guides to help customers use AR effectively

ARShortcodeData Structure

When working with AR models, the getARShortCodeData method returns an ARShortcodeData object with these key properties:

Property	Type	Description
glbPath	string	Path to the GLB model file (for Android)
usdzPath	string	Path to the USDZ model file (for iOS)
productName	string	Display name of the product
allowScaling	boolean	Whether model scaling is enabled in AR
conversionStatus	string	Processing status (e.g., "PENDING", "COMPLETED")
completeSubscription	Promise	Optional subscription to completion event

This data structure provides everything needed to launch the appropriate AR experience based on device type and handle the model processing lifecycle.

Conclusion

AR integration offers a significant enhancement to the product configuration experience, allowing customers to visualize products in their actual environment. Whether you choose the simple built-in implementation or a fully customized approach, Mimeeq's AR capabilities can help increase customer confidence and drive conversions.

For additional support or advanced customization options, please contact the Mimeeq support team or refer to the API documentation.