Augmented Reality (AR)

Upload USDZ File (iOS)

Upload a .usdz file for native iOS AR Quick Look support. Without a USDZ file, iOS devices may fall back to a less reliable GLB-based AR experience.

curl -X POST \
  ".../projects/PROJECT_ID/usdz" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

# Response:
{
  "success": true,
  "usdzId": "uuid",
  "usdzPath": "userId/project-usdz/...",
  "fileName": "model.usdz"
}

Tip: Convert GLB to USDZ using Apple's Reality Converter (macOS), Blender's USDZ export, or online tools like glb-to-usdz.com.

Delete USDZ File

Track AR Analytics Event

Record AR interaction events. This endpoint is public (no auth) and used via sendBeacon from the viewer. Fire-and-forget.

{
  "event": "ar_launch_ios",
  "projectId": "PROJECT_ID",
  "shareToken": "optional",
  "meta": { "source": "qr_code" }
}

// Valid event types:
// ar_dialog_open, ar_qr_copy, ar_qr_open_tab,
// ar_launch_ios, ar_launch_android,
// ar_auto_launch, ar_page_view

Get AR Analytics Summary

Fetch aggregated AR analytics for a project (requires auth).

// Response:
{
  "projectId": "...",
  "totalEvents": 142,
  "byEvent": {
    "ar_dialog_open": 58,
    "ar_launch_ios": 41,
    "ar_launch_android": 29,
    "ar_qr_copy": 14
  },
  "lastUpdated": "2026-03-17T...",
  "recentEvents": [...]
}

Public USDZ URL (Share Viewer)

Get a signed URL for a shared project's USDZ file. Used by the share viewer to launch iOS AR Quick Look with the USDZ file.

AR Project Settings

AR behavior is controlled via Project Settings fields. Set these when saving a project:

{
  "enableAR": true,           // Master toggle
  "arUsdzFileName": "...",    // iOS USDZ file name
  "arUsdzModelPath": "...",   // Storage path (set by upload)
  "arUsdzModelId": "...",     // Storage ID (set by upload)
  "arAutoLaunch": true,       // Auto-launch AR on ?ar=1
  "arAnalyticsEnabled": true  // Track AR events
}