Launching AR experiences

SDK Guide

Use the SDK to smoothly transition your users into Variant Launch as needed.


Embed the SDK

Add this script tag as the first item, or as early as possible in your <head>. It should run before your 3D engine code if you want WebXR support available when your other code runs.

<script src="https://launchar.app/sdk/v1?key=YOUR_SDK_KEY&redirect=true"></script>

The redirect=true means that iOS users will be instantly redirected to the Launch Card for the current page (where they will then open the Launch Viewer and be returned to the page with WebXR support).

You can remove &redirect=true if you want to handle the timing of redirecting iOS users to the Launch card yourself (e.g. if you want to use an explicit 'enter AR' button, or have users view some content on the page before Launching).

Starting a WebXR AR Session

Once you know WebXR is available you can simply use a immersive-ar WebXR session as you normally would in your engine of choice, specifying a local reference space:

navigator.xr.requestSession('immersive-ar', {
  requiredFeatures: ['local', 'anchors', 'dom-overlay', 'hit-test'],
})

Creating a Launch URL manually

  getLaunchUrl(targetURL): string

If you want to control exactly what page the user will see upon entering the Variant Launch viewer, you can manually create a Launch URL once the SDK has initialized.

For example, you might want to hide the transfer to the viewer behind a 'launch AR' button on your site. Upon tapping the button you redirect the user to the launch URL, and when they tap 'Open' on the appclip, the target URL is loaded in the viewer and starts the WebXR experience immediately without any user input.

var launchUrl = VLaunch.getLaunchUrl('https://yoursite.com/?instantWebxr=true')
window.location.href = launchUrl

Tracking Quality Changes

Listen for the event vlaunch-ar-tracking on the pages document to receive updates about the quality of the ARKit tracking. The states match those in the ARKit Documentation, and can be used to prompt the user on how to resolve the issue, or simply pause/restart the experience.

We recommend you use these events to show UI prompts specific to your experience (e.g. "Point your device at the floor and move side-to-side").

document.addEventlistener('vlaunch-ar-tracking', handleTrackingChanged)

const handleTrackingChanged = (event) => {
  switch (event.detail.state) {
    case 'normal':
      // the tracking is working normally
      break
    case 'not-available':
      // tracking is not running
      break
    case 'limited-excessive-motion':
      // the device is currently moving too fast to track
      break
    case 'limited-initializing':
      // the tracking is still being initialized
      break
    case 'limited-insufficient-features':
      // the tracking is not able to track enough features in the user's environment
      break
    case 'limited-relocalizing':
      // the tracking is currently relocalizing
      break
  }
}

Initialisation Event

If you want additional information and control, you can listen for the vlaunch-initialized event:

window.addEventListener('vlaunch-initialized', (event) => {
  if (event.detail.launchRequired) {
    //We need to use launch to get WebXR as we're on iOS
    window.location.href = event.detail.launchUrl
  }
})

Here is the full payload sent with the 'vlaunch-initialized' event as event.detail:

{
  launchRequired: boolean
  webXRStatus: 'unsupported' | 'launch-required' | 'supported'
  launchUrl: string
}

launchRequired will be true if the user is on an iOS device where visiting the launch URL will enable WebXR. This value is false if the user is already in the Launch viewer.

webXRStatus reports the WebXR availability on the device. If the result is 'supported' you can immediately launch a standard webXR session without using the launch SDK.

launchUrl contains the Launch URL for iOS users that will open the current page in the Variant Launch viewer. If you wish to open a different URL (e.g. to have the user drop right into WebXR) use getLaunchUrl()

Previous
Example projects