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 acceptedFetch 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 eventsProgrammatic 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
TypeScriptBuilt-in TypeScript types and error classes (AuthenticationError, ValidationError, NotFoundError, ConflictError).ExamplesEnd-to-end recipes — headless embeds, binding external UI to SDK events, and more.ChangelogVersion history and notable changes to the Simplio3D SDK.IntroductionOverview of the @simplio3d/sdk headless TypeScript client — what it does and how it talks to the Simplio3D platform.
