> For the complete documentation index, see [llms.txt](https://docs.blippar.com/webar-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blippar.com/webar-sdk/v2.0.9/whats-new.md).

# What's New?

### 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:**

```javascript
// 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:

```html
<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:**

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

**Using the Cursor API:**

```javascript
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'));
  }
});
```