AR SDKQuick StartAPI Reference

AR SDK Integration Guide

This guide covers how to integrate and use the AR SDK in your web application. The AR SDK provides a Unity-based augmented reality experience that communicates with your web application through a bi-directional bridge.

Overview

The AR SDK uses a communication bridge between your Webview and the Unity-based AR SDK:

  • Outbound (Web to SDK): Send commands using Unity.call(JSON.stringify({type: string, data: object}))
  • Inbound (SDK to Web): Receive events via a global onUnityMessage(message) function where message is a JSON string

Getting Started

Initialization Flow

Follow this sequence when initializing the AR SDK:

  1. Get screen size - Always run getScreenSize() and send windowSize on load
  2. Set environment - Configure the backend environment
  3. Set tour info - Load the specific 3D model/tour
  4. Start localization - Begin the visual positioning process

Example Initialization 

// Get screen dimensions
const screenSize = getScreenSize();

// Initialize the SDK
Unity.call(JSON.stringify({
  type: 'windowSize',
  data: { width: screenSize.width, height: screenSize.height }
}));

// Set environment
Unity.call(JSON.stringify({
  type: 'setEnvironment',
  data: { environment: 'Production' } // or 'Stage'
}));

// Load tour
Unity.call(JSON.stringify({
  type: 'setTourInfo',
  data: { 
    slug: 'your-tour-slug',
    matterId: 'your-matter-id'
  }
}));

// Start localization
Unity.call(JSON.stringify({
  type: 'startLocalization',
  data: {}
}));

Outbound Commands

Commands are sent from your web application to the AR SDK using Unity.call().

Command Reference

Command Data Payload Description
setEnvironment { environment: "Production" | "Stage" } Configures the backend environment
setTourInfo { slug: string, matterId: string } Loads the specific 3D model/tour
windowSize { width: number, height: number } Calibrates SDK viewport dimensions
startLocalization {} Begins the visual positioning process
manualRelocalize {} Resets tracking and starts localization over
startNavigation { toSweepId: string, destinationName: string } Generates a 3D path to the destination
stopNavigation {} Clears current navigation path
teleportConfirm {} Acknowledges transition (e.g., entered an elevator)
teleportEnd {} Resumes normal navigation after transition
showARObject { id: string, type: string } Sets an AR element to visible
hideARObject { id: string, type: string } Sets an AR element to hidden
clickCoords { x: number, y: number } Sends touch coordinates for 3D interaction

Command Examples

Navigation 

// Start navigation to a destination
Unity.call(JSON.stringify({
  type: 'startNavigation',
  data: {
    toSweepId: 'sweep-123',
    destinationName: 'Conference Room A'
  }
}));

// Stop navigation
Unity.call(JSON.stringify({
  type: 'stopNavigation',
  data: {}
}));

AR Object Visibility 

// Show an AR object
Unity.call(JSON.stringify({
  type: 'showARObject',
  data: {
    id: 'object-123',
    type: 'TAG'
  }
}));

// Hide an AR object
Unity.call(JSON.stringify({
  type: 'hideARObject',
  data: {
    id: 'object-123',
    type: 'TAG'
  }
}));

Teleport Handling 

// Confirm teleport (e.g., user entered elevator)
Unity.call(JSON.stringify({
  type: 'teleportConfirm',
  data: {}
}));

// End teleport (resume normal navigation)
Unity.call(JSON.stringify({
  type: 'teleportEnd',
  data: {}
}));

Inbound Events

The SDK sends events to your web application through the onUnityMessage function. Each message is a JSON string containing a type and data field.

Event Listener Setup 

function onUnityMessage(message) {
  const event = JSON.parse(message);
  
  switch (event.type) {
    case 'localization_status':
      handleLocalizationStatus(event.data);
      break;
    case 'warning':
      showWarning(event.data);
      break;
    case 'info':
      showInfo(event.data);
      break;
    case 'onNavigationComplete':
      handleNavigationComplete(event.data);
      break;
    case 'onNavigationTeleport':
      handleNavigationTeleport(event.data);
      break;
    case 'onARObjectClick':
      handleARObjectClick(event.data);
      break;
  }
}

Event Types

Status & Feedback Events

localization_status

  • Updates on the tracking state
  • Common values: "Success", "Searching"
  • Use this to provide user feedback about localization progress

warning

  • Environmental warnings
  • Examples: "Low Light", "Point at floor"
  • Display these warnings to guide the user

info

  • General system status updates
  • Use for informational messages

Navigation Events

onNavigationComplete

  • Fired when the destination is reached
  • No data payload

onNavigationTeleport

  • Fired when the path requires a manual transition move
  • User should call teleportConfirm and teleportEnd to handle the transition

Interaction Events

onARObjectClick

  • Fired when a 3D object is tapped
  • Returns { id: string, type: string } of the tapped object

Event Handling Examples 

// Handle localization status updates
function handleLocalizationStatus(data) {
  if (data === 'Success') {
    showToast('Localization successful!');
  } else if (data === 'Searching') {
    showToast('Searching for position...');
  }
}

// Handle warnings
function showWarning(data) {
  showToast(`Warning: ${data}`, 'warning');
}

// Handle AR object clicks
function handleARObjectClick(data) {
  console.log('AR Object clicked:', data.id, data.type);
  // Handle the click event, e.g., show details, navigate, etc.
}

// Handle navigation completion
function handleNavigationComplete() {
  showToast('You have reached your destination!');
}

Supported AR Object Types

The following types are valid for showARObject, hideARObject, and onARObjectClick events:

  • TAG
  • VS_IMAGE
  • VS_VIDEO
  • VS_OBJECT
  • VS_HTML
  • POLYGON
  • THREAD

UI Integration Best Practices

User Feedback

Your UI should listen for localization_status and warning event types to provide user feedback:

function onUnityMessage(message) {
  const event = JSON.parse(message);
  
  // Show toast notifications for status updates
  if (event.type === 'localization_status') {
    showToast(`Localization: ${event.data}`);
  }
  
  // Show warnings prominently
  if (event.type === 'warning') {
    showWarningToast(event.data);
  }
  
  // Show info messages
  if (event.type === 'info') {
    showInfoToast(event.data);
  }
}

Error Handling

Always wrap SDK calls in try-catch blocks and handle potential errors:

function sendSDKCommand(type, data) {
  try {
    Unity.call(JSON.stringify({ type, data }));
  } catch (error) {
    console.error('Failed to send SDK command:', error);
    showError('Failed to communicate with AR SDK');
  }
}

Complete Integration Example

Here's a complete example of integrating the AR SDK:

// Initialize SDK
function initializeARSDK(environment, slug, matterId) {
  // Get and set window size
  const size = getScreenSize();
  Unity.call(JSON.stringify({
    type: 'windowSize',
    data: { width: size.width, height: size.height }
  }));
  
  // Set environment
  Unity.call(JSON.stringify({
    type: 'setEnvironment',
    data: { environment }
  }));
  
  // Load tour
  Unity.call(JSON.stringify({
    type: 'setTourInfo',
    data: { slug, matterId }
  }));
  
  // Start localization
  Unity.call(JSON.stringify({
    type: 'startLocalization',
    data: {}
  }));
}

// Handle SDK messages
function onUnityMessage(message) {
  const event = JSON.parse(message);
  
  switch (event.type) {
    case 'localization_status':
      updateLocalizationUI(event.data);
      break;
    case 'warning':
      showWarning(event.data);
      break;
    case 'info':
      showInfo(event.data);
      break;
    case 'onNavigationComplete':
      onDestinationReached();
      break;
    case 'onNavigationTeleport':
      promptTeleport();
      break;
    case 'onARObjectClick':
      handleObjectInteraction(event.data);
      break;
  }
}

// Start navigation
function navigateToDestination(sweepId, destinationName) {
  Unity.call(JSON.stringify({
    type: 'startNavigation',
    data: { toSweepId: sweepId, destinationName }
  }));
}

// Handle teleport
function confirmTeleport() {
  Unity.call(JSON.stringify({ type: 'teleportConfirm', data: {} }));
  // After transition completes
  Unity.call(JSON.stringify({ type: 'teleportEnd', data: {} }));
}

Troubleshooting

Common Issues

SDK not responding

  • Ensure Unity.call is available in your environment
  • Check that the Unity WebGL build is properly loaded
  • Verify JSON stringification is working correctly

Localization not starting

  • Ensure you've called setEnvironment and setTourInfo before startLocalization
  • Check that windowSize has been set
  • Verify the tour slug and matterId are correct

Events not received

  • Ensure onUnityMessage is defined as a global function
  • Check browser console for errors
  • Verify the Unity build is sending messages correctly