What's New?

WebAR SDK v2.0.9

Key New Features

1. Seamless Surface/Marker ➡️ Gyro Transition

This release introduces the ability to seamlessly transition from Surface or Marker Tracking to Gyro Tracking using the new EnableGyroMode() API. This ensures experiences can continue using device orientation when specific tracking is no longer required.

• Manual Handover: Developers can programmatically trigger the transition to Gyro tracking using WEBARSDK.EnableGyroMode().

• Flexible Control: Ideal for scenarios where the user moves away from the marker or surface after initial content placement.

2. Front Camera Marker Tracking

Developers can now enable marker tracking using the front-facing camera, unlocking new selfie-style marker experiences.

• Usage: Add the enable-front-camera-for-marker-tracking attribute to your configuration.

3. Advanced Cursor API & Customization

A new globally accessible Cursor API provides full control over the Surface & World Tracking cursor, allowing for deep customization and state management.

• Access Point: WEBARSDK.GetCursorAPI()

• State Introspection:

  • isTapReady(): Checks if the surface is locked and ready for placement.

  • isVisible(): Returns current visibility state.

  • isCustomCursor(): Checks if a custom cursor is in use.

  • getOpacity(): Returns current opacity level.

• Control:

  • setVisible(visible): Toggle cursor visibility.

  • setOpacity(opacity): Adjust cursor transparency.

• Event Handling:

  • onTapReady(callback): Triggered when a valid surface is detected.

  • onTapNotReady(callback): Triggered when tracking is lost or searching.

• Material Customization (Default Cursor):

  • materials.setRingColor(color) / materials.setDotColor(color): Customize specific elements.

  • materials.setColors(ringColor, dotColor): Set both colors simultaneously.

• Custom Cursor Entity:

  • New customCursor property in webar-ux-control allows using any A-Frame entity as the cursor.

• Direct Access:

  • entity: Direct reference to the A-Frame cursor entity for low-level manipulation.

  • debug(): Logs internal state and configuration to the console.

4. Privacy Enhancements (IP Anonymization)

To better align with privacy regulations and user preferences, we have added an option to anonymize IP addresses in analytics.

• Usage: Add anonymize-ip-addresses="true" to your SDK script tag.

5. Manual Gyro Mode Control

A new API allows developers to manually switch the experience to Gyro mode, effectively disabling SLAM tracking and relying solely on device orientation. This applies to both Surface Tracking and Marker Tracking.

• Usage: WEBARSDK.EnableGyroMode()

• Example:

// Give a callback when the WebAR Marker <a-entity webar-marker> is ready to track the marker image
WEBARSDK.SetMarkerDetectedCallback((markerId) => {
  console.info('Marker is detected for marker id: ', markerId);
  // Switch to gyro mode after 7 seconds
  setTimeout(() => {
    WEBARSDK.EnableGyroMode();
  }, 7000);
});

Performance & Stability

• 60 FPS Support: WebAR experiences can now run smoothly at up to 60 FPS on supported devices.

• Instant Tracking: AR content appears instantly when the camera is opened.

• Gyro-Fusion & Pose Smoothing: Significant reduction in jitter and elimination of the AR "leaning" effect for improved orientation accuracy.

• Pure Gyro Rotation: Replaces SLAM-based rotation with pure gyro data for cleaner camera movement.

• Dynamic Ground Plane Alignment: Prevents AR content from floating above or below the real-world surface.

Developer Experience & UX Improvements

• Enhanced Error Dialogs: A completely redesigned error dialog experience featuring a "Copy Link" button, improved readability, and better visual hierarchy for troubleshooting.

• Mirroring Control: New disable-mirroring attribute to turn off video mirroring for Face and Marker tracking modes.

• Camera Orientation: New disable-ar-facing-camera attribute allows opt-out of the default behavior where content always faces the user.

• Windows Surface Support: Added hardware compatibility for Windows Surface tablets.

• Viewport Meta Tag: Recommended for optimal layout and AR stability on mobile devices (see Best Practices below).

Bug Fixes & Compatibility

• Safari iOS 26+ Liquid Glass Fix: Resolved an issue where the address bar caused viewport shrinking and transparency on newer iOS versions.

• SLAM Camera Hierarchy: Entities placed under <a-camera> now correctly follow camera movement in SLAM mode, matching ECS behavior.

• Cross-Browser Text Rendering: Fixed text wrapping and consistency issues across different browsers.

• Android Surface Tracking: Fixed an issue where the 3D cursor failed to appear on page reloads.

• Marker Tracking Stability: Enhanced detection reliability and stability.

---

Best Practices & Examples

Recommended Viewport Meta Tag: For optimal layout, AR stability, and to prevent accidental zooming, we recommend the following viewport configuration:

<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,shrink-to-fit=no,user-scalable=no,viewport-fit=cover">

Enabling IP Anonymization:

<script src="webar-sdk-v2.0.9.min.js" anonymize-ip-addresses="true"></script>

Using the Cursor API:

WEBARSDK.SetStageReadyCallback(() => {
  const cursor = WEBARSDK.GetCursorAPI();
  
  if (cursor) {
    // Debug current state
    cursor.debug();

    // Customize appearance
    cursor.setOpacity(0.8);
    if (!cursor.isCustomCursor()) {
        cursor.materials.setColors('#00ff00', '#ff00ff'); // Ring green, Dot magenta
    }

    // Handle events
    cursor.onTapReady(() => console.log('✅ Surface locked – tap to place!'));
    cursor.onTapNotReady(() => console.log('❌ Move device to find a surface'));
  }
});