Augmented Reality (AR) SDK

Configure AR from the SDK, track AR analytics, and launch AR programmatically — including the AR handoff link that carries a shopper's exact configuration to their phone.

Upload USDZ File

The pre-uploaded USDZ is the iOS fallback — share views bake a configured USDZ from the live scene automatically. There is no SDK helper for the upload; use the REST endpoint directly, then update settings with the SDK.

// Upload a fallback USDZ for iOS AR Quick Look (REST — no SDK helper)
const usdzFile = document.querySelector('input[type="file"]').files[0];
const form = new FormData();
form.append('file', usdzFile);

const res = await fetch(
  'https://YOUR_PROJECT.supabase.co/functions/v1/make-server-0532dd87' +
    '/projects/PROJECT_ID/usdz',
  {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + accessToken },
    body: form,
  }
);
const result = await res.json();
console.log(result.usdzId, result.usdzPath);

// Then update project settings with the SDK:
await client.updateProjectSettings('PROJECT_ID', {
  enableAR: true,
  arUsdzFileName: result.fileName,
  arUsdzModelPath: result.usdzPath,
  arUsdzModelId: result.usdzId,
  arMobileCta: true,   // "View in your space" button (default true)
  arAutoLaunch: true,  // mobile AR prompt banner
  arAnalyticsEnabled: true,
});

Track AR Events

import { trackAREvent } from './lib/ar-analytics';

// Track an AR event (fire-and-forget, non-blocking)
trackAREvent({
  event: 'ar_launch_ios',
  projectId: 'PROJECT_ID',
  meta: { source: 'floating_tools' },
});

// Available event types:
// 'ar_dialog_open'      — Desktop QR dialog opened
// 'ar_qr_copy'          — AR link copied
// 'ar_qr_open_tab'      — AR link opened in new tab
// 'ar_launch_ios'       — iOS AR Quick Look launched
// 'ar_launch_android'   — Android Scene Viewer launched
// 'ar_launch_wearable'  — Wearable try-on viewer opened
// 'ar_auto_launch'      — Auto-launched via ?ar=1
// 'ar_page_view'        — Share page loaded with AR
// 'ar_session_created'  — AR handoff session created (desktop QR)
// 'ar_session_restored' — Phone restored a session via ?ars=
// 'ar_launch_failed'    — Native AR launch could not start
// 'ar_prompt_shown'     — Mobile AR prompt banner displayed
// 'ar_prompt_accepted'  — Mobile AR prompt banner accepted

Fetch AR Analytics

import { fetchARAnalytics } from './lib/ar-analytics';

const analytics = await fetchARAnalytics('PROJECT_ID', accessToken);
console.log(analytics.totalEvents);     // 142
console.log(analytics.byEvent);          // { ar_launch_ios: 41, ... }
console.log(analytics.recentEvents);     // last 50 events

Programmatic AR Launch

// Generate an AR share URL — the share viewer's own QR uses an
// AR handoff session so the link carries the exact configuration:
const shareUrl = `https://yourapp.com/share/${projectId}/${token}`;
const arUrl = `${shareUrl}?ar=1&ars=${sessionId}`;
// sessionId comes from POST /share/:projectId/:token/ar-session
// (see API docs → Augmented Reality). A plain ?ar=1 link still
// works but opens the default configuration.

// On iOS — AR Quick Look renders USDZ only
const link = document.createElement('a');
link.setAttribute('rel', 'ar');
link.href = usdzUrl; // configured USDZ from the session, or
                     // /share/:projectId/usdz as the fallback
const img = document.createElement('img');
img.style.display = 'none';
link.appendChild(img);
document.body.appendChild(link);
link.click();

// On Android — Scene Viewer intent (HTTPS GLB, never blob:)
const intent = `intent://arvr.google.com/scene-viewer/1.0
  ?file=${encodeURIComponent(glbUrl)}
  &mode=ar_preferred#Intent;...;end;`;
window.location.href = intent;

Continue reading