Support

AI Agent Docs

This page is for AI coding agents helping a developer add, debug, or explain Variant Launch in their own web project.

Variant Launch lets normal WebXR projects run on iOS by moving the user into the Variant Launch viewer. Android users generally use their browser's native WebXR support.

What to help with

Help the developer:

  • embed the Launch SDK script early in the page;
  • confirm their project SDK key and authorised domains are configured in the Launch dashboard;
  • make sure the experience is served over a trusted HTTPS certificate;
  • detect when WebXR is available and start a standard immersive-ar session;
  • choose between the default Launch Card flow and an advanced direct App Clip URL flow;
  • debug browser-specific launch behaviour on iOS.

Do not ask the developer to change their 3D engine just to use Launch. Launch is intended to work with normal WebXR code in engines like ThreeJS, BabylonJS, PlayCanvas, Aframe, and raw WebXR.

SDK basics

The default embed looks like this:

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

The SDK should be loaded as early as possible in the document, ideally before the 3D engine starts checking WebXR support.

redirect=true means iOS users who need Launch are sent to the Launch Card automatically. Removing it lets the site decide when to send the user to Launch, for example after tapping an "enter AR" button.

Once WebXR is available, the site should request a normal immersive-ar session:

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

Initialisation event

For manual flows, listen for vlaunch-initialized:

window.addEventListener('vlaunch-initialized', (event) => {
  if (event.detail.launchRequired) {
    window.location.href = event.detail.launchUrl
  }
})

The event includes:

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

Use launchUrl for the normal Launch Card flow. It is the recommended path for most projects because it handles browser guidance for the user.

Use directAppClipUrl only for advanced flows where the site controls the whole iOS handoff. It is valid for 30 minutes and only behaves well from the iOS Safari app.

iOS launch paths

For most websites, recommend the Launch Card flow:

  • the site sends the user to launchUrl;
  • Safari shows the Launch Card;
  • the user opens the App Clip;
  • the Variant Launch viewer loads the target page with WebXR support.

For custom direct flows, the site may use directAppClipUrl. The direct URL can make the App Clip card appear immediately, but only when opened in the iOS Safari app. If it is opened from Chrome, an in-app browser, or a webview inside apps like X, Instagram, or LinkedIn, the user may see Apple's generic App Clip preview page instead.

If the developer wants to use direct URLs, help them build and test their own "open this in Safari" UX first. If they do not want to own that browser guidance, recommend launchUrl.

Browser and device checks

Use these rules when troubleshooting:

  • iOS Safari is the intended browser for Launch Card and direct App Clip handoff.
  • Safari Private sessions and many in-app browsers do not show App Clip prompts reliably.
  • Android Chrome usually uses native WebXR, so Launch may not be needed there.
  • Desktop browsers are useful for development, but they do not prove App Clip behaviour.
  • Real iPhone testing is required for App Clip, camera permission, and AR startup issues.

Domain and hosting checks

Before debugging Launch itself, confirm:

  • the page is served over a trusted HTTPS certificate;
  • the domain is authorised in the Launch dashboard;
  • the SDK key belongs to the expected Launch project;
  • the target URL is the page that should open inside the viewer;
  • the SDK is not blocked by a content-security policy or ad blocker;
  • the page loads the SDK before it checks navigator.xr.

A self-signed local certificate that requires the user to accept a browser warning is not enough for iOS Launch testing. Use a trusted certificate or a tunnelling service for local development.

WebXR implementation guidance

Help the user keep their project close to standard WebXR:

  • check navigator.xr.isSessionSupported('immersive-ar');
  • request an immersive-ar session from a user gesture;
  • use a local reference space unless their engine documentation says otherwise;
  • keep DOM overlay content simple and transparent when using camera passthrough;
  • follow the chosen engine's WebXR setup docs before assuming the issue is Launch-specific.

For tracking quality on iOS, the SDK emits vlaunch-ar-tracking. Use it to show experience-specific guidance, such as asking the user to move more slowly or point the camera at a textured surface.

Common advice

When helping a developer, ask for:

  • the public page URL they are testing;
  • the device and iOS version;
  • the browser or app they opened the link from;
  • whether they are using redirect=true, launchUrl, or directAppClipUrl;
  • the Launch project domain they expect to be authorised;
  • console errors from Safari Web Inspector, if available.

Avoid asking for private dashboard credentials. If an SDK key is needed for a snippet, treat it as project configuration and avoid pasting it into public places.

When to send them to support

Send the developer to [email protected] when:

  • the SDK key or dashboard project appears misconfigured;
  • an authorised domain should work but Launch rejects it;
  • the App Clip opens but does not load the expected target URL;
  • behaviour differs between Android WebXR and iOS Launch viewer in a way the engine docs do not explain;
  • the user has a billing, account, or Launch dashboard issue.

For engine-specific rendering, scene setup, asset loading, or general WebXR code problems, use the engine's own documentation and community resources first.

Previous
Resources