Introduction

8th Wall enables developers to create, collaborate and publish Web AR experiences that run directly in a web browser.

Built entirely using standards-compliant JavaScript and WebGL, 8th Wall Web is a complete implementation of 8th Wall's Simultaneous Localization and Mapping (SLAM) engine, hyper-optimized for real-time Web AR on browsers. Features include World Tracking, Image Targets, and Face Effects.

The 8th Wall Cloud Editor allows you to develop fully featured Web AR projects and collaborate with team members in real time. Built-In Hosting allows you to publish projects to multiple deployment states hosted on 8th Wall's reliable and secure global network, including a password-protected staging environment. Self-Hosting is also available for certain plans.

8th Wall is easily integrated into 3D JavaScript frameworks such as:

• A-Frame (https://aframe.io/)
• three.js (https://threejs.org/)
• PlayCanvas (https://www.playcanvas.com)
• Babylon.js (https://www.babylonjs.com/)

Quick Start Guide API Reference Need Help?

Tutorial:

What's New

8th Wall Release 20 is now available! This release provides a number of updates and enhancements:

Release 20: (2022-September-21, v20.1.19.684 / 2022-September-21, v20.1.17.684)

• New Features:

  • Introducing Lightship VPS for Web - create location-based WebAR experiences by connecting AR content to real-world locations.

    • Added new Geospatial Browser to the 8th Wall Developer Portal.

      • Find, create and manage VPS-activated locations (Wayspots).
      • Generate and download 3D meshes for use as occluders, physics objects, or as a reference for creating location-aware animations.
    • Added enableVps parameter to XR8.XrController.configure() and xrweb.
    • Added events when a Wayspot is ready for scanning, found, or lost.
    • Added ability to find and access Wayspot raw mesh geometry.
    • Added XR8.Vps.WayspotWatcher, an API for querying nearby WaySpots.
    • Added Lightship VPS Coaching Overlay module to guide users through a flow to localize at real-world locations.
    • Added XR8.Platform API for unlocking new 8th Wall platform features like Lightship VPS and Niantic Lightship Maps.

  • Niantic Lightship Map module

    • Add the lightship-maps module to your project on 8thwall.com to make it easy to create a variety of location-based experiences.

• Fixes and Enhancements:

  • Improved error handling for VPS network requests (20.1.19.684)

Click Here for to see a full list of changes.

Requirements

Web Browser Requirements

Mobile browsers require the following functionality to support 8th Wall Web experiences:

• WebGL (canvas.getContext('webgl') || canvas.getContext('webgl2'))
• getUserMedia (navigator.mediaDevices.getUserMedia)
• deviceorientation (window.DeviceOrientationEvent - only needed if SLAM is enabled)
• Web-Assembly/WASM (window.WebAssembly)

NOTE: 8th Wall Web experiences must be viewed via https. This is required by browsers for camera access.

This translates to the following compatibility for iOS and Android devices:

• iOS:

  • Safari (iOS 11+)

  • Apps that use SFSafariViewController web views (iOS 13+)

    • Apple added getUserMedia() support to SFSafariViewController in iOS 13. 8th Wall works within iOS 13 apps that use SFSafariViewController web views.
    • Examples: Twitter, Slack, Discord, Gmail, Hangouts, and more.

  • Apps/Browsers that use WKWebView web views (iOS 14.3+)

    • Examples:

      • Chrome
      • Firefox
      • Microsoft Edge
      • Facebook
      • Facebook Messenger
      • Instagram
      • and more...

• Android:

  • Browsers known to natively support the features required for WebAR:

    • Chrome
    • Firefox
    • Samsung Internet
    • Microsoft Edge

  • Apps using Web Views known to support the features required for WebAR:

    • Twitter, WhatsApp, Slack, Gmail, Hangouts, Reddit, LinkedIn, and more.

Link-out support

For apps that don’t natively support the features required for WebAR, our XRExtras library provides flows to direct users to the right place, maximizing accessibility of your WebAR projects from these apps.

Examples: TikTok

Screenshots:

Launch Browser from Menu (iOS)	Launch Browser from Button (Android)	Copy Link to Clipboard

Supported Frameworks

8th Wall Web is easily integrated into 3D JavaScript frameworks such as:

• A-Frame (https://aframe.io/)
• three.js (https://threejs.org/)
• Babylon.js (https://www.babylonjs.com/)
• PlayCanvas (https://www.playcanvas.com)

Supported Features

Platform	Lighting	AR Background	Camera Motion	Horizontal Surfaces	Vertical Surfaces	Image Detection & Tracking	World Points	Hit Tests	Face Effects
8th Wall Web	Yes	Yes	6 DoF	Yes, single surface	No	Yes	Yes	Yes	Yes

Quick Start Guide

This guide provides all of the steps required to get you up and running with the 8th Wall Cloud Editor and Built-in Hosting platform.

Create an 8th Wall Account

Creating an 8th Wall Account gives you the ability to:

• Create rich Web AR experiences that run directly in a mobile web browser.
• Collaborate with team members and store code in source control.
• Instantly preview projects as you develop.
• Wirelessly debug your code in real time with live console logs from multiple devices.
• Publish projects hosted on 8th Wall's global network.
• Manage subscriptions, billing information and licenses for commercial projects.
• Create a Public Profile and Feature Projects on 8thwall.com, allowing you to showcase your work, live demos, and/or code.

New Users: Sign up for a 14-day free trial at https://www.8thwall.com/try-free-trial

Existing Users: Login at https://www.8thwall.com/login using your email address and password.

Start Free Trial

The 8th Wall Cloud Editor and Built-in Hosting platform are available to workspaces with a paid subscription. 8th Wall offers a 14-day free trial so you can get access to the full power of 8th Wall and begin building WebAR experiences.

At the end of your 14-day free trial, your account will automatically upgrade to a paid plan. You must cancel your free trial before the end of the trial period to avoid charges. There are no refunds or credits for partial or unused months. To manage your subscription settings, please see https://www.8thwall.com/docs/web/#account-settings

1. Enter your email and click Start Free Trial

2. Create your account by entering your personal details into the form and set a password.

3. Confirm your email address. An email will be sent with a verification code. Enter the verification code and click Confirm.

4. Enter you name, email and select the plan you want to trial (Starter / Plus / Pro). NOTE: You will NOT be charged anything at this time. You can cancel at any time during the 14-day free trial period to avoid charges. After canceling, you will still have access to 8th Wall for the full duration of your trial period.

5. Click Next.

6. Review and confirm: Accept the 8th Wall Terms and Conditions, then click Start free trial to continue and activate your 14-day free trial.

IMPORTANT! At the end of the 14-day free trial period, your account will automatically upgrade to the selected paid plan. You must cancel the free trial before the end of the trial period to avoid charges. There are no refunds or credits for partial or unused months. To manage your subscription settings, please see https://www.8thwall.com/docs/web/#account-settings

Create your workspace

1. Enter a Workspace Name. This value is for display purposes only and doesn't impact any URLs associated with your workspace.

2. Enter a Workspace URL. Pick something relevant for your workspace name, such as the name of your company.

IMPORTANT: This value will be used as the default sub-domain for ALL 8th Wall hosted projects in your account (e.g. mycompany.8thwall.app/project-name). This value will also be used in your Public Profile page URL (e.g. www.8thwall.com/mycompany.

You cannot change this value later, so choose wisely!

Note: if you want to connect custom domains to your 8th Wall hosted projects to override the default URL, please see here.

Start a new project

1. From the Homepage (logged in) or Workspace Dashboard, click "Start a new Project"

2. Select Hosting Type (Pro/Enterprise plans only): Decide up front if the project will be hosted by 8th Wall and developed using the 8th Wall Cloud Editor, or if you'll be self-hosting. This setting cannot be changed later. Self-hosting is only avilable to paid Pro/Enterprise workspaces. Self-hosting is not available to workspaces on Starter or Plus plans, or workspaces on the Pro plan during the free trial period.

3. Select a Project Name: The project name is used both in th default project URL (e.g. mycompany.8thwall.app/project-name) as well as the Featured Project page URL (e.g. www.8thwall.com/mycompany/project-name). It cannot be changed later.

4. Select a License Type (Pro/Enterprise only)

License Types:

• Commercial: Commercial projects are intended for commercial use. When you’re ready to launch a commercial project publicly, you will need to purchase a monthly Commercial License which varies based on views. NOTE: Commercial projects cannot be purchased during a free trial. If you need to purchase a commercial license, you can end your free trial early and begin your paid subscription.

• Non-Commercial: Your paid subscription allows you to develop and publish unlimited non-commercial projects. A "Non-Commercial" label will appear on the loading screen. If you decide to commercialize your project at any point, switch to "Commercial" in the Project Dashboard.

• Demo Use: You may create unlimited demo projects which are publicly viewable and strictly intended for pitching prospective work. A "Demo Use Only" label will appear on the loading screen. If you decide to commercialize your project at any point, switch to "Commercial" in the Project Dashboard.

• Educational Use: Educational projects are intended for educational purposes only, such as a classroom setting. You can develop and publish unlimited educational projects. An "Educational Use" label will appear on the loading screen. If your project is intended for commercial use, you must select "Commercial". If you are an educational institution please contact 8th Wall for information on a custom Education plan.

• Web App: You may create unlimited first-party projects under this license. Web app projects require the splash screen to remain on and will be publicly viewable on 8thwall.com as soon as you publish. This license does not permit projects created for work-for-hire as they require a Commercial license.

Clone template project

1. After creating a project, select a template to clone. In this guide, select "A-Frame: Tap to Place Ground". This interactive example allows the user to spawn 3D models on the surface in front of you by tapping. This showcases raycasting, instantiating objects, importing 3D models and the animation system.

2. On the following screen, a project README will be displayed. [Optional] To test out the template before cloning, click the Launch button and scan the QR code with your phone.

3. Click the Clone Project button to proceed. The sample project will be cloned into your workspace, and the Cloud Editor will be opened.

Live Preview

1. At the top of the Cloud Editor window, click the Preview button.

2. Scan the QR code with your mobile device to open a web browser and look at a live preview of the WebAR project.

3. When the page loads, you'll be prompted for access to motion and orientation sensors (on some devices) and the camera (all devices). Click Allow for all permission prompts. You will be taken to the private development URL for this project.

Note: The "Preview" QR code displayed within the Cloud Editor is a temporary, one-time use QR code only meant for use by the developer while actively working in the Cloud Editor. This QR code takes you to a private, development URL, and isn't accessible by others. To share your work with others, please see the section below on Publishing your project.

4. When the WebAR preview loads, tap on the surface in front of you to spawn 3D models.

5. Result:

Save, Build and Land

At this point, you have a fully operational Web AR project and have previewed it on a mobile device. Next, make a very small code change to illustrate how to update the project, preview the new code, and land the changes into source control.

1. Within body.html of the Cloud Editor project, make a small text change to the promptText. For example, simply change the text from Tap To Place Model to Tap To Begin.

2. Click Save + Build to save your work and initiate a new cloud build of your project.

3. If your mobile browser is still open from scanning the Preview QR code in Step 2, your phone will automatically reload once the build completes. If the mobile browser page is no longer open, scan the Preview QR code again to preview your updates to the project.

4. Once satisfied with your changes, land the updated code into the Cloud Editor's integrated source control. At the top-right of the Cloud Editor window, click Land. The button will be green, indicating that there are changes in the project that have not yet been landed into source control:

5. In the Message field enter a brief message describing the changes made, then click Land:

Publish your project

The final step is to publish your updated and landed project code using 8th Wall's Built-in Hosting. This allows the project to be viewed publicly by anyone on the internet.

Note: Commercial projects require additional commercial licenses when launched. See https://www.8thwall.com/pricing for more info.

1. At the top right of the Cloud Editor window, click Publish

2. In the Publish Project modal, you will see a list of commits (one for each version of code you have landed into source control) as well as the Development, Staging and Public URLs for the project. Select top radio button in the Public column to deploy the latest/newest version of code to the project's Public URL, then click Publish:

3. Complete the publish process by giving your project a title, description and cover image. This info will appear on your Featured Project Page and as a preview when you share on social platforms and messaging apps.

View the public project

1. Go back to the Project Dashboard in the left nagivation. In the QR 8.code section, the Public project URL will be displayed along with both an 8th.io shortlink and associated QR code.

2. Scan the QR code with your mobile device to view the Public Web AR experience.

Sample Projects

8th Wall has created a number of sample projects that you can clone and use as starting points to help you get started. Please check out:

• Cloud Editor & 8th Wall Hosted examples:

  • 8th Wall Project Library

• Self-Hosted examples:

  • GitHub
  • PlayCanvas

Overview

8th Wall enables developers to create, collaborate and publish Web AR experiences that run directly in a web browser.

Built entirely using standards-compliant JavaScript and WebGL, 8th Wall Web is a complete implementation of 8th Wall's Simultaneous Localization and Mapping (SLAM) engine, hyper-optimized for real-time Web AR on browsers. Features include World Tracking, Image Targets, and Face Effects.

The 8th Wall Cloud Editor allows you to develop fully featured Web AR projects and collaborate with team members in real time. Built-In Hosting allows you to publish projects to multiple deployment states hosted on 8th Wall's reliable and secure global network, including a password-protected staging environment. Self-Hosting is also available for certain plans.

Creating an 8th Wall Account gives you the ability to:

• Create rich Web AR experiences that run directly in a mobile web browser.
• Collaborate with team members and store code in source control.
• Instantly preview projects as you develop.
• Wirelessly debug your code in real time with live console logs from multiple devices.
• Publish projects hosted on 8th Wall's global network.
• Manage subscriptions, billing information and licenses for commercial projects.
• Create a Public Profile and Feature Projects on 8thwall.com, allowing you to showcase your work, live demos, and/or code.

New Users: Sign up for a 14-day free trial at https://www.8thwall.com/try-free-trial and please follow the Quick Start Guide to get started!

Existing Users: Login at https://www.8thwall.com/login using your email address and password.

Homepage

The 8th Wall homepage, when logged in, provides access to all of your workspaces and recent projects. Select a Workspace or Project to access its dashboard.

Homepage guide:

1. Start a new project
2. User Settings (Profile, Manage Workspaces, Logout)
3. Workspace Type
4. Workspace
5. Project
6. Workspace the project belongs to
7. Project Type
8. Project shortcuts

Workspaces

A Workspace is a logical grouping of Projects, Users, and Billing. Workspaces can contain one or more Users, each with different permissions. Users can belong to multiple Workspaces.

The Workspace dashboard allows you to:

• Create new Projects.
• Manage existing projects.
• Manage workspace team members and permissions.
• Manage subscriptions and commercial licenses.

Initial Workspace

When creating a new 8th Wall account directly from 8thwall.com, you will start with a workspace with a 14-day free trial.

If signing up via an invitation from another 8th Wall user, you will be added as a team member of their existing workspace.

Select Workspace

To select a workspace, perform one of the following:

1. Navigate to https://www.8thwall.com and login. The Home page will display a carousel of all the workspaces you are a member of. Click a workspace card to select.

2. Click on your name at the top-right of the page and select Workspaces

Create Workspace

1. Under your name at the top right, select "Manage Workspaces" (or navigate directly to https://www.8thwall.com/workspaces)
2. Click "Create a New Workspace"
3. Select Workspace Type
4. Click Create

Teams

Each Workspace has a team containing one or more Users, each with different permissions. Users can belong to multiple Workspace teams.

Add others to your team to allow them to access the Projects in your workspace. This allows you to collaboratively create, manage, test and publish Web AR projects as a team.

Invite Users

1. Select your workspace.

2. Click Team in the left navigation.

3. Enter the email address(es) for the users you want to invite. Enter multiple emails separated by commas.
4. Click Invite users

User Roles

Team members can have one of three roles:

• OWNER
• ADMIN
• DEV

Capabilities for each role:

Capability	OWNER	ADMIN	DEV
Projects - View	X	X	X
Projects - Create	X	X	X
Projects - Edit	X	X	X
Projects - Delete	X	X	X
Authorize Devices	X	X	X
Teams - View Users	X	X	X
Teams - Invite Users	X	X
Teams - Remove Users	X	X
Teams - Manage User Roles	X	X
Workspaces - Create	X	X	X
Workspaces - Edit	X
Workspaces - Manage Plans	X
Edit Profile	X	X	X

User Handles

Each user in your workspace has a handle. Workspace handles will be the same as the User Handle defined in a user's profile unless already taken or customized by a user.

Handles are used as part of the URL (in the format "handle-client-workspace.dev.8thwall.app") to preview new changes when developing with the 8th Wall Cloud Editor.

Example: tony-default-mycompany.dev.8thwall.app

Important

• Before changing your handle, make sure all work in the Cloud Editor is saved.
• Any of your unlanded changes to projects in the workspace will be abandonded.
• Any clients you created in projects in the workspace will be deleted.

Modify User Handle

1. Select your workspace.
2. Click Team in the left navigation
3. Enter a new Handle.
4. Click ✔ to save.
5. Confirm you

Public Profiles

This section describes how to activate your Public Profile and feature projects on your page.

Your Public Profile is your own page on 8thwall.com where you can showcase your work, demo your experience and even share your code if you so choose.

Activate Public Profile

All Pro and Enterprise workspaces are provided with a Public Profile on 8thwall.com but these pages need to be activated in order to be accessible. Only Owner and Admin user roles have permission to make changes and activate your Public Profile. You can deactivate your Public Profile at any time. Your Public Profile must be activated first in order to publish Featured Projects to your page.

To activate your Public Profile:

1. Expand your workspace in the left navigation.

2. Click Public Profiles

3. Complete all mandatory fields on the Page Info form including:

   • Logo (minimum 400x400px PNG or JPEG)
   • Name (3-30 characters)
   • Website URL (https://www.mycompany.com)
   • Primary location (City)
   • Bio (240 characters or less)
   • Contact email (e.g. contact@mycompany.com)

4. Click Save to save the information you have entered.

   • All of your mandatory information must be completed and saved in order to activate your profile.

5. Click Activate Public Profile when you are ready for your Public Profile page to be active.

   • Your Profile Page URL contain the shortname of your workspace. (e.g https://8thwall.com/{mycompany})
   • You cannot change the workspace shortname.

Deactivate Public Profile

You can deactivate your Public Profile at any time. Your Public Profile and any Featured Project pages will no longer be visible once this page is deactivated. This will not impact any WebAR experiences, only the public profile pages. Only Owner and Admin users have permission to deactivate your Public Profile.

To deactivate your Public Profile:

1. Expand your workspace in the left navigation.

2. Click Public Profiles

3. Click on the Deactivate Public Profile link at the bottom of the page.

4. Confirm you wish to deactivate the page by typing in the word "DEACTIVATE" in all caps and click Confirm.

5. You will receive a confirmation message confirming your Public Profile has been deactivated.

   • Once deactivated, the View Public Profile button at the top of page will no longer be active.
   • You can easily reactivate your Public Profile by clicking on the Activate Public Profile button at the top of the page.

Featuring a Project

Once your Public Profile is activated, you can publish Featured Projects pages to your Public Profile page. All 8th Wall projects can be featured on a public profile including non-commercial, demo, education and commercial projects (both with active and completed licenses). All workspaces users have permission to create, save and publish featured projects. Projects can be added or removed to a Public Profile at any time. Publishing a Featured Project does not impact the live published WebAR experience.

To publish a Featured Project on your Public Profile:

1. Select an existing project or create a new project in your workspace.

2. Click on Feature Project in the left navigation.

3. Fill out all of the mandatory sections on this page. This is required order to be able to publish your Featured Project page.

Basic Information

If Basic Information of your project is missing (Project Title, Project Description or Cover Image), you will be asked to update these details on the Project Settings page. Updating Basic Information will not impact your project code.

Project Details

• Overview: Enter information about the project you are featuring in the Overview area in the Project Details section. Describe your project, project goals, and details about its development and design.

  • Add Formatting with the rich media buttons:

    • Headers (H)
    • Bold font (B)
    • Italic font (I)
    • Bulleted and Numbered lists.
  • Preview your formatting using the Preview pane on the right.

• Tags: Enter or select up to five tags for your Featured Project. Your featured project must have at least one tag to be published. To add a tag, start typing. Use a comma or hit return to register them. Use the backspace to delete a tag. Click on suggested tags below to add them to your list of tags.

Media

• Youtube or Vimeo Link (Optional): Enter a YouTube or Vimeo link in the Video Link field. This video will be embedded on your Featured Project page and will be set to auto-play (muted) when a user visits the page.

• Image Gallery: Upload images and GIFs by either dragging and dropping the files into the Image Gallery area under the Media section or by clicking on this area to select files from your device. Note:

  • You can upload a maximum of 5 images or GIFs.
  • Projects must have at least 1 image or GIF to be published.
  • JPG, PNG, GIF formats are supported and must have a minimum dimension of 540x960.
  • Images can be cropped using the provided cropping tool.
  • GIFs must be uploaded using the required aspect ratio of 9:16. GIFs cannot be cropped.
  • The maximum file size for images and GIFs is 15MB.
  • Images and GIFs will appear on the published page in the order they are uploaded.

Publish

• Publish: Once you have completed all of the manatory fields and are ready to add this Featured Project page to your Public Profile, click the Publish button.

• Save Draft: If you aren't quite ready to publish the Featured Project page to your Public Profile, but want to save your progress so you can leave the page and come back later, click the Save Draft button.

8th Wall-Hosted Featured Projects

Projects built using the 8th Wall Cloud Editor and that have published a commit to the project's Public URL will have access to additional (and optional) 8th Wall-Hosted Features. For all other Featured Projects, this area will remain locked. These features are optional and are not required to publish a Featured Project page to your Public Profile.

Optional Featured Project Page settings for 8th Wall-Hosted projects include:

• Adding a "Launch" button to a Featured Project page, making it easy for visitors to demo your experience.
• Making your project code viewable and cloneable to other developers, if you so choose.

To enable either of this options:

1. Select an existing project or create a new project in your workspace.

2. Click on Feature Project in the left navigation.

3. Scroll down to the 8th Wall-Hosted Features area at the bottom of the Feature Project page:

Launch:

• The "Launch" button, if enabled:

  • Allows anyone to view what is published to your project's Public URL.
  • Links directly to the default 8thwall.app URL for your project. This cannot be modified.
  • Is enabled by default for 8th Wall hosted projects. You can disable this before publishing your featured project page, if desired.
  • Can be used for all project types including Commercial projects with both Active and Completed licenses. *
• Toggle "Launch" to Public (ON) if you wish to add it to your page. Toggle "Launch" to Hidden (OFF) if you do not want it displayed on your Featured Project page.

Cloneable Code:

• The Cloneable Code feature, if enabled:

  • Will make your published code viewable and cloneable to the public.
  • Your Featured Project page will show your published code in a new Code tab on the page.
  • A Clone button will be added to the Featured Project page to make it easy for users to clone your project into their 8th Wall workspace.
  • Your Featured Project page will also clearly state the license found in the LICENSE file in your project.
  • Is disabled by default for 8th Wall hosted projects. You can enable this before publishing your featured project page, if desired.
• Toggle the Cloneable Code button to Public (ON) if you wish to add it to your page. Toggle "Launch" to Hidden (OFF) if you do not want it displayed on your Featured Project page.

4. Click Publish or Save and Update.

   • You will receive a confirmation message when you publish your project or save and update changes to your featured project page confirming your choice.
   • If you have enabled Cloneable Code, this confirmation message will also confirm the license for your project using the LICENSE file in your published project. It is strongly recommended that you include a LICENSE file in your project when toggling Cloneable Code to Public.

5. Click Confirm to continue with your selection or click Cancel to undo your changes.

Unpublish Featured Project

You can unpublish any of the Featured Project pages in Public Profile at any time. Unpublishing a Featured Project page will remove it from your Public Profile and it will no longer be publicly visible.

Note: This only unpublishes the Featured Project page. The WebAR experience itself is not taken down or imacted in any way.

To unpublish a Featured Project page from your Public Profile:

1. Select a project which is featured on your Public Profile

2. Click on Feature Project in the left navigation.

3. Click on the Unpublish Featured Project link at the bottom of the page.

4. Confirm you wish to unpublish this Featured Project by typing in the word "UNPUBLISH" in all caps and then click Confirm.

5. You will receive a confirmation message confirming your Featured Project has been unpublished. You will no longer see the Featured Project on your Public Profile.

   • Once unpublished, the View Featured Project button at the top of page will no longer be active
   • You can easily republish your Featured Project to your Public Profile by clicking on the “Publish” button.

Account Settings

The Account page allows you to:

• Upgrade to a Pro Plan.
• Cancel Free Trial if you are still within your 14-day free trial period.
• Cancel Plan if you have an active, paid Pro plan subscription.
• Manage commercial licenses
• Manage payment methods
• Manage invoices (View, Pay and Download)
• Update billing information

Upgrade Plan

Please refer to https://www.8thwall.com/pricing for detailed information on plans and pricing.

For licensing inquiries, please contact the 8th Wall team by filling out the form at https://www.8thwall.com/licensing

To Upgrade to an paid plan:

1. Select your workspace.
2. Click Account in the left navigation
3. Click the Upgrade button of the desired plan
4. Completely fill out the form.
5. Click Complete Purchase to activate your Pro plan subscription. Monthly plan subscription fees will be charged to this payment method unless otherwise specified.

As part of the upgrade process, if you haven't already, you may be asked to select a Workspace Name and Workspace URL:

• Workspace Name: A descriptive name for your workspace (e.g. "Acme Inc.")

• Workspace URL: This value is used as part of the URL to access your 8th Wall workspace and related resources. It is also used as the subdomain in default URLs to 8th Wall hosted projects. This value is automatically generated from the Workspace Name, but can be customized. This cannot be changed later

  • Workspace URL example: www.8thwall.com/acme/
  • Hosted Project URL example: acme.8thwall.app/my-web-app

Cancel Free Trial

NOTE: At the end of the 14-day free trial period, your account will automatically upgrade to a paid plan. You must cancel online before the end of the trial period to avoid being charged for the monthly subscription.

There are no credits or refunds for partial or unused months if you forget to cancel your free trial before it ends.

To cancel Free Trial:

1. Expand your workspace, if not already open.

2. Click Account in the left navigation.

3. The Account page will display your current plan.
4. Click Cancel my free trial

5. Complete the wizard to cancel your free trial. You will continue to have access to the 8th Wall platform until the end of the 14-day trial period.

Cancel Plan

To cancel an existing plan:

1. Expand your workspace, if not already open.

2. Click Account in the left navigation.

3. The Account page will display your current plan.
4. Click Cancel subscription to disable auto-renew for your subscription. Your subscription will be cancelled at the end of the current billing period and you may continue to use 8th Wall for the remainder of your current billing period.

Note: You cannot cancel your Pro scription if the workspace has any actice commercial apps. You first need to cancel your commercial licenses (which will take the projects offline) and then you can cancel your Pro subscription.

Manage Commercial Licenses

Commercial licenses and their payment methods can be managed from the Account page of your workspace. This widget will only be displayed if you have active commercial licenses. It allows you to modify the payment method of a commercial license, or cancel it immediately.

1. Expand your workspace, if not already open.

2. Click Account in the left navigation.

View commercial licenses

The Commercial License widget will display information about all commercial licenses within your workspace:

• Project Name
• Commercial Agreement (Contract)
• Payment Method
• Next Payment (Both amount and date of the next charge)
• Status (Active or Ended)

Cancel an active commercial license

IMPORTANT: Cancelling the license for an active commercial project will disable it and the WebAR project can no longer be viewed. This action cannot be undone! If you would prefer to schedule a future end to the license, please adjust the Project Duration settings for your project instead.

1. Click the down arrow icon in the Status column for the desired project.
2. Select End project now
3. A warning dialog will be displayed.
4. Type 'END' to confirm you want to immediately cancel the license (and take the project offline) and click "OK".

Change payment method for an active commercial license

1. Click the down arrow icon in the Payment Method column for the desired project.
2. A list of available payment methods will be displayed. Select a new payment method.

Manage Payment Methods

The Payment Methods widget allows you to:

• Add a new payment methods.
• Set payment method as default (to be used for future charges)
• Remove payment methods.

To add, remove or set a new default payment method:

1. Expand your workspace, if not already open.

2. Click Account in the left navigation.

On this page, you can manage your payment methods as well as the billing information you'd like to appear on your invoices.

Click "Add payment method" to add a new credit card to your account. If you would like this newly added credit card to be used for future bills, make sure to click "Make Default"

Invoices

The Invoices widget on the Account page allows you to view and download invoices, and make payments for any outstanding invoices.

To access the invoices associated with your account:

1. Expand your workspace, if not already open.

2. Click Account in the left navigation.

The following information is displayed:

• Invoice Number (click to download PDF invoice)
• Date
• Invoice Total
• Amount Paid
• Balance Due
• Link to view receipt
• Invoice Status

Update Billing Information

The "Billing Information" section of the Account page allows you to specify contact information you'd like to appear on future invoices and the email address you would like invoices/receipts sent to.

To update account billing information:

1. Expand your workspace, if not already open.

2. Click Account in the left navigation.

3. Click Edit to modify your billing information.

4. Click Update to save your changes.

Note: Updated payment methods and invoice details will be used in future invoices.

Projects

This section decribes how to create, manage and publish WebAR projects.

Create Project

1. From the Homepage (logged in) or Workspace Dashboard, click "Start a new Project"

2. Select the workspace for this project.

3. Enter Basic info for the project: Please provide: Title, URL, Description (optional) and Cover Image (optional). All of these fields, except URL, can be edited later in the Project Settings page.

4. Select a Project Type:

• Commercial: Commercial projects are intended for commercial use. You can develop unlimited commercial projects with your plan at no additional charge. When you’re ready to launch a commercial project so that the world can see it, you will need to purchase a monthly Commercial License which varies based on views. NOTE: Commercial projects cannot be purchased during a free trial. If you need to purchase a commercial license, you can end your free trial early and begin your paid subscription.

• Non-Commercial: Your paid subscription allows you to develop and publish unlimited non-commercial projects. A "Non-Commercial" label will appear on the loading screen. If you decide to commercialize your project at any point, switch to "Commercial" in the Project Dashboard.

• Demo Use: You may create unlimited demo projects which are publicly viewable and strictly intended for pitching prospective work. A "Demo Use Only" label will appear on the loading screen. If you decide to commercialize your project at any point, switch to "Commercial" in the Project Dashboard.

• Educational Use: Educational projects are intended for educational purposes only, such as a classroom setting. You can develop and publish unlimited educational projects. An "Educational Use" label will appear on the loading screen. If your project is intended for commercial use, you must select "Commercial". If you are an educational institution please contact 8th Wall for information on a custom Education plan.

Project Dashboard

The project dashboard is your hub for managing 8th Wall projects. From the project dashboard page you can manage project settings, access the 8th Wall Cloud Editor, purchase commercial licenses, manage image targets, setup custom domains, and more.

The direct URL to your Project Dashboard is in the format: www.8thwall.com/workspacename/projectname

Project Dashboard Overview

1. Project Dashboard
2. Device Authorization
3. Open Editor
4. Code Editor
5. Project History
6. Image Targets
7. Project Settings
8. Project Type
9. Image Targets
10. Setup Domains (8th Wall Hosted or Self-Hosted)
11. Campaign Duration
12. Campaign Redirect URL
13. QR Code and Embeds
14. Usage and Recent Trends

Project Type

8th Wall Projects fall into one of the following categories:

• Commercial: Commercial projects are intended for commercial use. You can develop unlimited commercial projects with your plan at no additional charge. When you’re ready to launch a commercial project so that the world can see it, you will need to purchase a monthly Commercial License which varies based on views. NOTE: Commercial projects cannot be purchased during a free trial. If you need to purchase a commercial license, you can end your free trial early and begin your paid subscription.

• Non-Commercial: Your paid subscription allows you to develop and publish unlimited non-commercial projects. A "Non-Commercial" label will appear on the loading screen. If you decide to commercialize your project at any point, switch to "Commercial" in the Project Dashboard.

• Demo Use: You may create unlimited demo projects which are publicly viewable and strictly intended for pitching prospective work. A "Demo Use Only" label will appear on the loading screen. If you decide to commercialize your project at any point, switch to "Commercial" in the Project Dashboard.

• Educational Use: Educational projects are intended for educational purposes only, such as a classroom setting. You can develop and publish unlimited educational projects. An "Educational Use" label will appear on the loading screen. If your project is intended for commercial use, you must select "Commercial". If you are an educational institution please contact 8th Wall for information on a custom Education plan.

If you selected the wrong project type during initial creation, please use the Project Dashboard to change the project type as appropriate.

Change Project Type

1. Go to the Project Dashboard page
2. Click "Change project type"
3. Select an appropriate project type
4. Click "Save"

Purchase Commercial License

1. Go to the project Dashboard page
2. Change project type to "Commercial" if it isn't already.
3. Click "Purchase License"

Follow the wizard and purchase the desired commercial license:

1. Select Commercial Use Agreement (and accept commercial license, if required)
2. Select commercial license
3. Select payment method
4. Review "Total due today" and understand when the following charge will take place.
5. Click "Complete purchase"

Managing Image Targets

To manage image targets for a given Project, click either the Image Target icon in the left navigation, or the "Manage Image Targets" link on the Project Dashboard.

For detailed information on Image Targets, please refer to the Image Target documentation.

Managing Lightship VPS Wayspots

To manage LightshipVPS Wayspots for a given project, click the map icon in the left navigation.

For detailed information on Lightship VPS for Web, please refer to the Lightship VPS for Web documentation.

Connected Domains

When using the 8th Wall Cloud Editor to develop, the Web AR experience created is published to 8th Wall's hosting infrastructure. By default, the URL of your published Web AR experience will be in the fomat of:

"workspace-name.8thwall.app/project-name"

If you own a custom domain and want to use it with an 8th Wall hosted project instead of the default URL, you can connect the domain to your 8th Wall project with a few simple DNS configurations. To do so you'll need access to create/edit DNS records for your domain.

NOTE: Connecting custom domains to 8th Wall Hosted projects requires a paid Plus, Pro or Enterprise subscription. This feature is not available during the Free Trial period.

WARNING: It is strongly recommended that you connect a subdomain ("ar.mydomain.com") instead of the root domain ("mydomain.com" without anything in front) as not all DNS providers support CNAME/ALIAS/ANAME records for the root domain. Please contact your DNS provider to see if they support CNAME or ALIAS records for the root domain before proceeding.

1. From the Project Dashboard page, select "Setup domains"

2. Expand "Setup your domain to point to this 8th Wall-hosted project"

3. In Step 1 of the connected domain wizard, enter your custom domain (e.g. www.mydomain.com), in the Primary connected domain field.

4. [Optional] If you want to connect additional sub-domains, click the Add additional sub domain button and add any additional domains you want connected. Note: If you connect additional sub-domains, these will redirect back to the primary connected domain. They must share the same root as the primary connected domain.

5. Click Connect. At this point 8th Wall will generate an SSL certificate for the custom domain(s) being connected. This operation can take a few minutes, so please be patient. Click the "Refresh status" button if needed.

6. Next, Verify ownership of your domain. In order to verify that you are the owner of the custom domain, you must login to your DNS provider's website and add one or more verification CNAME records. Use the Copy button to ensure you properly collect the complete Host and Value records.

These DNS records can take up to 24 hours to be verified, but in most cases happens in a matter of minutes. Please be patient and click the "Refresh verification status" button periodically if needed.

When verification has completed, you'll see a green checkmark next to the verification DNS record:

7. Finally, Step 3 will display one or more CNAME (if connecting a sub-domain) or ANAME (if connecting a root-domain, see warning above) records that need to be added to your DNS server to finish the connected domain setup. These records map your custom domain to 8th Wall's hosting infrastructure.

Result: Connection Record Verified:

Additional notes:

• If you are connecting a root domain, Step 3 will display an ANAME record. Assuming your DNS provider actually supports these types of records, they will not show as "connected". Your connected domain will still work as long as you have created the appropriate DNS records.

• It's not possible to modify the connected domain settings once defined. If you need to make changes, you'll need to:

  1. Delete the connected domain from your 8th Wall project.
  2. Clean up and DNS records added from the previous setup.
  3. Start over with the new custom domain configuration.
• Do not use an A record for Step 3. 8th Wall hosted experiences are served using a global CDN with hundreds of locations around the globe. Users are automatically routed to the closest/fastest datacenter for maximum performance. You must connect your domain to the unique "xxxxx.cloudfront.net" URL displayed in Step 3 of the wizard.

Self Hosted Domains

If you are on a paid Pro or Enterprise plan, you can host Web AR experiences on your own web server (and view them without device authorization). In order to do so, you will need to specify a list of domains that are approved to host your project.

1. From the Project Dashboard page, select "Setup domains".

2. Expand "Setup this project for self-hosting or local development"

3. Enter the domain(s) or IP(s) of the web server where you will be self-hosting the project. A domain may not contain a wildcard, path, or port. Click the "+" to add multiple.

Note: Self-Hosted domains are subdomain specific - e.g. "mydomain.com" is NOT the same as "www.mydomain.com". If you will be hosting at both mydomain.com and www.mydomain.com, you must specify BOTH.

Campaign Duration

Commercial licenses, by default, will run indefinitely and automatically renew every month until you cancel. Ending a campaign will cancel the commercial license and the WebAR project will be disabled.

Campaign Duration settings can be managed from the Project Dashboard. The following options are available:

• Ongoing: The project will run indefinitely and your commercial license will automatically renew each month. The date/time of the next renewal will be displayed.
• End after current billing cycle: The campaign will run through the current billing period, and then end.
• Schedule an end date and time: Select a custom date and time for the campaign to end.

To modify campaign duration:

1. Go to the Project Dashboard of your project.
2. In the "Project Duration" box, Click "Edit":

3. Set the desired license end date and click "Update" to save your changes:

To cancel the campaign immediately, visit the workspace Account page and manage commercial licenses.

Campaign Redirect URL

When a launched project is cancelled or completed, the WebAR project can no longer be viewed. Users visiting the site will see an error message stating that the project is no longer available. It is a best practice to redirect users to another URL once your campaign is over.

Specify a Campaign Redirect URL to automatically redirect your users to a different site when your campaign has ended.

Campaign Redirect URLs are supported with both 8th Wall hosted and Self-hosted Projects.

From the Project Dashboard, click "Connect a URL" and enter the desired redirect URL

QR 8Code

As a convenience, 8th Wall branded QR codes (aka "8 Codes") can be generated for a Project, making it easy to scan from mobile device to access your WebAR project. You are always welcome to generate your own QR codes, or use third-party QR code generation websites or services.

The QR Code on the project dashboard points to a unique "8th.io" shortlink for your project. This shortlink then redirects a user to the URL of your Web AR experience.

Both the QR Code and "8th.io" code for a given project are static and will not change based on project type or license.

8th Wall Hosted Projects (NO connected domain)

If your project is using the default 8th Wall hosted URL (in the format of "workspace-name.8thwall.app/project-name"), the QR Code and 8th.io shortlink will always redirect to the default URL. It it not possible to modify the destination URL.

8th Wall Hosted Projects (WITH connected domain)

If you have configured a connected domain for your 8th Wall hosted project, you'll have the option to set the QR Code / Shortlink destination to either the default URL of the project, or the primary connected domain.

Use the radio button to set your QR Code / Shortlink destination:

Self Hosted Projects

To generate a QR code and shortlink, enter the full URL to your self-hosted project and click Save:

The generated QR code can be downloaded in either PNG or SVG format to be included on a website, physical media, or other locations to make it easy for users to scan with their smartphones to visit the self-hosted URL. Click the pencil icon to edit the shortlink destination should the self-hosted URL change in the future.

Example:

Usage and Recent Trends

8th Wall Projects provide basic usage analytics so that you can see how many times it has been viewed in the past 30 days. The usage graph is a rolling 30-day window and can display either total or daily usage during that time period.

Projects with usage based commercial licenses will also display view counts for the current billing period. Usage is measured in 100 view increments. Usage from previous months can be found in the Billing Summary of the Account page.

Feature Project

Once your Public Profile is activated, you can publish Featured Projects pages to your Public Profile page. All 8th Wall projects can be featured on a public profile including non-commercial, demo, education and commercial projects (both with active and completed licenses). All workspaces users have permission to create, save and publish featured projects. Projects can be added or removed to a Public Profile at any time. Publishing a Featured Project does not impact the live published WebAR experience.

Please see the following sections in the documentation for more information:

• Featuring a Project
• Unpublishing a Featured Project

Project Sharing

Project sharing, allows members of another trusted workspace to access a specific project in your workspace. There is no limit to the number of workspaces you can invite to access your project.

Members from an invited workspace can:

• Access the shared project from their own workspace.
• Edit and land code in the Cloud Editor.
• Manage Connected Domains (8th Wall hosted projects) and/or self-hosted domains (self hosted projects).
• Update Meta information (title, description, cover image, etc).
• Add/Edit image targets.

Members from an invited workspace cannot:

• See projects in your workspace that have not been shared with them.
• Purchase or manage Commercial Licenses.
• Edit/Delete the project.
• Manage sharing and permissions.

Note: Project Sharing is a feature only available to workspaces on paid Pro and Enterprise plans. Projects can be shared with workspaces on all paid plan types. (Enterprise, Pro, Plus, Starter)

Share project with another workspace:

1. Login as a user with OWNER or ADMIN permissions to a workspace on a paid Pro or Enterprise plan.
2. From the workspace page, click on the "..." menu of the desired project and click Share:

3. Enter the full workspace URL (e.g "https://www.8thwall.com/otherworkspace") or workspace shortname (e.g. "otherworkspace") and click Send Invite.

4. An email inviation will be sent to OWNER and ADMIN users from the invited workspace. The invitation must be accepted within seven days or it will expire.

Remove workspace access from a shared project:

1. Login as a user with OWNER or ADMIN permissions to a workspace on a paid Pro or Enterprise plan.
2. From the workspace page, click on the "..." menu of the desired project and click Share:

3. Click the Trashcan icon next to the workspace want to remove from accessing the project.

4. Click Remove to confirm.

Accessing a project shared by another workspace:

If you have accepted an invite to projects owned by other workspaces, they can be found under the External Projects tab of your Workspace:

Project Settings

The Project Settings page allows you to:

• Set developer preferences, such as Keybindings and Dark mode

• Edit Project information:

  • Title
  • Description
  • Enable/Disable default splash screen
  • Update cover image
• Manage staging passcode
• Access the Project's App Key string
• Set engine version
• Unpublish app
• Temporarily disable project
• Delete project

Code Editor Preferences

The following Code Editor preferences can be set:

• Dark Mode (On/Off)

  • Use a darker color palette in the Code Editor that uses darker background colors and lighter foreground colors.

• Keybindings

  • Enable keybindings from popular text editors. Select from:

    • Normal
    • Sublime
    • Vim
    • Emacs
    • VSCode

Basic Information

Project Settings allows you to edit the Basic Information for your Project

• Project Title

• Description

• Enable/Disable default splash screen

• Update cover image

Staging Passcode

When your app is staged to XXXXX.staging.8thwall.app (where XXXX represents your Workspace URL), it is passcode protected. In order to view the WebAR Project a user must first enter the passcode you provide. This is a great way to preview projects with clients or other stakeholders prior to launching publicly.

A passcode should be 5 or more characters and can include letters (A-Z, lower or upper case), numbers (0-9) and spaces.

App Key

If you are building a Self-hosted Project, you'll need to add your App Key to the project.

Click the Copy button and then paste it into your index.html

Example:

<script src="//apps.8thwall.com/xrweb?appKey=XXXXXXXXX"></script>

(Replace the XXX's with your App Key string)

Engine Version

NOTE: This is only available to workspaces on paid plans.

For each public Project, you can specify the version of the XR engine used when serving public web clients.

If you select a Channel (release or beta), public clients will always be served the most recent version of 8th Wall Web from that channel. If you freeze the version, you will need to manually unfreeze to receive the latest features and improvements of the engine.

In general, 8th Wall recommends using the official release channel for production web apps.

If you would like to test your web app against a pre-release version of 8th Wall Web, which may contain new features and/or bug fixes that haven't gone through full QA yet, you can switch to the beta channel:

To Freeze to a specific version, select the desired Channel (release or beta) and click the Freeze button

To Re-join a Channel and stay up-to-date, click the Unfreeze button. This will unfreeze the Engine Version associated with your Project and re-join a Channel (release or beta).

Unpublish App

Unpublishing your project will remove it from staging (XXXXX.staging.8thwall.app) or public (XXXXX.8thwall.app).

You can publish it again at any time from the Code Editor or Project History pages.

Click Unpublish Staging to take your Project down from XXXXX.staging.8thwall.app

Click Unpublish Public to take your Project down from XXXXX.8thwall.app

Temporarily Disable Project

If you disable your project, your app will not be viewable. Views will not be counted while disabled.

You will still be charged for any active commercial licenses on projects that are temporily disabled.

Toggle the slider to Disable / Enable your project.

Delete Project

A project with a commercial license cannot be deleted. Visit the Account page to cancel an active commercial project.

Deleting an Project will cause it to stop working. You cannot undo this operation.

Image Targets

Image Target Overview

Bring signage, magazines, boxes, bottles, cups, and cans to life with 8th Wall Image Targets. 8th Wall Web can detect and track flat, cylindrical and conical shaped image targets, allowing you to bring static content to life.

Not only can your designated image target trigger a web AR experience, but your content also has the ability to track directly to it.

Image targets can work in tandem with our World Tracking (SLAM), enabling experiences that combine image targets and markerless tracking.

You may track up to 5 image targets simultaneously with World Tracking enabled or up to 10 when it is disabled.

Up to 5 image targets per project can be "Autoloaded". An Autoloaded image target is enabled immediately as the page loads. This is useful for apps that use 5 or fewer image targets such as product packaging, a movie poster or business card.

The set of active image targets can be changed at any time by calling XR8.XrController.configure(). This lets you manage hundreds of image targets per project making possible use cases like geo-fenced image target hunts, AR books, guided art museum tours and much more. If your project utilizes SLAM most of the time but image targets some of the time, you can improve performance by only loading image targets when you need them. You can even read uploaded target names from URL parameters stored in different QR Codes, allowing you to have different targets initially load in the same web app depending on which QR Codes the user scans to enter the experience.

Image Target Types

Flat		Track 2D images like posters, signs, magazines, boxes, etc.
Cylindrical		Track images wrapped around cylindrical items like cans and bottles.
Conical		Track images wrapped around objects with different a top vs bottom circumference like coffee cups, etc.

Image Target Requirements

• File Types: .jpg, .jpeg or .png

• Dimensions:

  • Minimum: 480 x 640 pixels

  • Maximum length or width: 2048 pixels.

    • Note: If you upload something larger, the image is resized down to a max length/width of 2048, maintaining aspect ratio.)

Image Target Quantities

There is no limit to the number of image targets that can be associated with a project, however, there are limits to the number of image targets that can be active at any given time.

Up to 5 image targets can be active simultaneously while World Tracking (SLAM) is enabled. If World Tracking (SLAM) is disabled (by setting "disableWorldTracking: true") you may have up to 10 simultaneously active image targets.

• Active images per Project (World Tracking enabled): 5
• Active images per Project (World Tracking disabled): 10

Manage Image Targets

Click the Image Target icon in the left navigation or the "Manage Image Targets" link on the Project Dashboard to manage your image targets.

This screen allows you to create, edit, and delete the image targets associated with your project. Click on an existing image target to edit. Click the "+" icon for the desired image target type to create a new one.

Create Flat Image Target

1. Click the "+ Flat" icon to create a new flat image target.

2. Upload Flat Image Target: Drag your image (.jpg, .jpeg or .png) into the upload panel, or click within the dotted region and use your file browser to select your image.

3. Set Tracking Region (and Orientation): Use the slider to set the region of the image that will be used to detect and track your target within the WebAR experience. The rest of the image will be discarded, and the region which you specify will be tracked in your experience.

4. Edit Flat Image Target properties:

• (1) Give your image target a name by editing the field at the top left of the window.
• (2) IMPORTANT! Test your image target: The best way to determine if your uploaded image will make a good or bad image target (see Optimizing Image Target Tracking is to use the Simulator to assess tracking quality. Scan the QR code with your camera app to open the simulator link, then point your device at the screen or physical object.
• (3) Click Load automatically if you want the image target to be enabled automatically as the WebAR project loads. Up to 5 image targets can be loaded automatically without writing a single line of code. More targets can be loaded programnatically through the Javascript API.
• (4) Optional: If you would like to add metadata to your image, in either Text or JSON format, click the Metadata button at the bottom of the window.

5. Changes made on this screen are automatically saved. Click Close to return to your image target library.

Create Cylindrical Image Target

1. Click the "+ Cylindrical" icon to create a new flat image target.

2. Upload Flat Image Target: Drag your image (.jpg, .jpeg or .png) into the upload panel, or click within the dotted region and use your file browser to select your image.

3. Set Tracking Region (and Orientation): Use the slider to set the region of the image that will be used to detect and track your target within the WebAR experience. The rest of the image will be discarded, and the region which you specify will be tracked in your experience.

4. Edit Cylindrical Image Target properties:

• (1) Give your image target a name by editing the field at the top left of the window.
• (2) Drag the sliders until the shape of your label appears as expected in the simulator, or input the measurements directly.
• (3) IMPORTANT! Test your image target: The best way to determine if your uploaded image will make a good or bad image target (see Optimizing Image Target Tracking is to use the Simulator to assess tracking quality. Scan the QR code with your camera app to open the simulator link, then point your device at the screen or physical object.
• (4) Click Load automatically if you want the image target to be enabled automatically as the WebAR project loads. Up to 5 image targets can be loaded automatically without writing a single line of code. More targets can be loaded programnatically through the Javascript API.
• (5) Optional: If you would like to add metadata to your image, in either Text or JSON format, click the Metadata button at the bottom of the window.

5. Changes made on this screen are automatically saved. Click Close to return to your image target library.

Create Conical Image Target

1. Click the "+ Conical" icon to create a new flat image target.

2. Upload Conical Image Target: Drag your image (.jpg, .jpeg or .png) into the upload panel, or click within the dotted region and use your file browser to select your image. The uploaded image should be in "unwrapped", aka "rainbow" format, cropped like so:

3. Set Large Arc Alignment: Drag the slider until the red line overlays the uploaded image's large arc.

4. Set Small Arc Alignment: Do the same for the small arc. Drag the slider until the blue line overlays the uploaded image's small arc.

5. Set Tracking Region (and Orientation): Drag and zoom on the image to set the portion of the image that is detected and tracked. This should be the most feature rich area of your image.

6. Edit Conical Image Target properties:

• (1) Give your image target a name by editing the field at the top left of the window.
• (2) Drag the sliders until the shape of your label appears as expected in the simulator, or input the measurements directly.
• (3) IMPORTANT! Test your image target: The best way to determine if your uploaded image will make a good or bad image target (see Optimizing Image Target Tracking is to use the Simulator to assess tracking quality. Scan the QR code with your camera app to open the simulator link, then point your device at the screen or physical object.
• (4) Click Load automatically if you want the image target to be enabled automatically as the WebAR project loads. Up to 5 image targets can be loaded automatically without writing a single line of code. More targets can be loaded programnatically through the Javascript API.
• (5) Optional: If you would like to add metadata to your image, in either Text or JSON format, click the Metadata button at the bottom of the window.

7. Changes made on this screen are automatically saved. Click Close to return to your image target library.

Edit Image Targets

Click on any of the image targets under My Image Targets to view and/or modify their properties:

1. Image Target Name
2. Sliders / Measurements (Cylindrical/Conical image targets only)
3. Simulator QR Code
4. Delete Image Target
5. Load Automatically
6. Metadata
7. Orientation and Dimensions
8. Autosave status
9. Close

Type	Fields
Flat
Cylindrical
Conical

Changing Active Image Targets

The set of active image targets can be modified at runtime by calling XR8.XrController.configure()

Note: The set of currently active image targets will be replaced with the new set passwd to XR8.XrController.configure().

Example - Change active image target set

XR8.XrController.configure({imageTargets: ['image-target1', 'image-target2', 'image-target3']})

Optimizing Image Target Tracking

To ensure the highest quality image target tracking experience, be sure to follow these guidelines when selecting an image target.

DO have:

• a lot of varied detail
• high contrast

DON'T have:

• repetitive patterns
• excessive dead space
• low resolution images

Color: Image target detection cannot distinguish between colors, so don't rely on it as a key differentiator between targets.

For best results, use images on flat, cylindrical or conical surfaces for image target tracking.

Consider the reflectivity of your image target's physical material. Glossy surfaces and screen reflections can lower tracking quality. Use matte materials in diffuse lighting conditions for optimal tracking quality.

Note: Detection happens fastest in the center of the screen.

Good Markers	Bad Markers

Image Target Events

8th Wall Web emits Events / Observables for various events in the image target lifecycle (e.g. imageloading, imagescaning, imagefound, imageupdated, imagelost) Please see the API reference for instructions on handling these events in your Web Application:

• AFrame Events
• BabylonJS Observables
• PlayCanvas Events
• XrController Dispatched Events

Example Projects

https://github.com/8thwall/web/tree/master/examples/aframe/artgallery

https://github.com/8thwall/web/tree/master/examples/aframe/flyer

Lightship VPS

Lightship VPS Overview

With the Lightship Visual Positioning System (VPS) 8th Wall developers now have the power to determine a user's position and orientation with centimeter-level accuracy - in seconds. Using the 8th Wall platform, you can use Lightship VPS in your WebAR projects to create location-based web AR experiences that connect the real world with the digital one. WebAR content can be anchored to locations, enabling virtual objects to interact with the space they are in. This makes the augmented reality experience feel more personal, more meaningful, more real, and gives users new reasons to explore the world around them.

Managing Wayspots

The Geospatial Browser can be accessed from within your Project by selecting the map icon in the left hand menu (annotated as #1 in the image below). On this page you will find a map view (#2) which you can use to search to find VPS-activated Niantic Wayspots. Selecting a VPS-activated location will display the 3D mesh of the location (#3) so you can verify you have selected the correct location and add it to your project (#4).

When you add a VPS-activated Wayspot to your project you will see a Wayspot in the "Project Wayspots" table in the Geospatial Browser (annotated as #1 in the image below). Once you have a Wayspot in the “Project Wayspots” table you can use the "Download" button (#2) to download a GLB or OBJ (toggle shown as #3) version of the 3D mesh and open it in third-party 3D software applications, such as Blender, or import it directly into your 8th Wall project. When referencing Wayspots in your project code you will need to copy the "Name" field (#4) from the "Project Wayspots" table.

If the location you'd like to use in your project is not available as a Wayspot, you can submit Wayspot locations to Niantic by following the instructions in the Create New Wayspot section.

Create New Wayspot

1. Select a location on the map where you want to create a new Wayspot. (see Wayspot Requirements to learn more about choosing a good location to create a Wayspot).

2. Create Wayspot: Click the "Create Wayspot" button to start the process to create a new Wayspot.

3. Check for Duplicates: Before creating a new Wayspot, you are required to check that your Wayspot doesn't already exist. Compare your desired Wayspot's location to others already on the map to ensure that you are not creating a duplicate. If this is not a duplicate Wayspot, you must check the "My Wayspot is not a duplicate" box and click on the "Next" button to continue.

4. Add Wayspot Information: Wayspot metadata will be visible to developers using the Geospatial Browser and can be visible to end-users. Remember that Niantic's Trust & Safety team uses the information you provide to determine whether the Wayspot meets our criteria to be made publicly available. Once you have added the following information for the Wayspot you are tring to create, click on the “Submit” button:

• Title (125 characters)
• Description (250 characters)
• Category (1 or more)
• Image (if available)

5. Your Wayspot should immediately be added to your Wayspot Submissions tab in the Geospatial Browser with the type "Pending" and the status "Not Activated". You can continue to scan and activate this Wayspot while your request to make this Wayspot "Public" is being processed. You can learn more about Wayspot types and statuses in the Wayspot Types section of the documentation.

Scanning Wayspots

You can add scans to activate eligible Wayspots, as well as create private Wayspots (for use in development) by using the Niantic Wayfarer App. The Niantic Wayfarer App requires iOS 12 or later and an iPhone 8 or later.

To install the Niantic Wayfarer App, go to Testflight for Niantic Wayfarer on your iOS device.

Once you have installed the app, you can login with your 8th Wall credentials by pressing the "Login with 8th Wall button". If you have access to multiple Workspaces you can switch between your Workspaces by pressing the 8th Wall Workspace dropdown on the profile page within the app. Private scans will only be visible to the workspace you have selected on the profile page at the time of scanning & upload.

You can find more instructions on how to use the Wayfarer app, including how to add scans to a Wayspot using Wayfarer, here: Using the Niantic Wayfarer App.

Scanned VPS-activated locations should be no larger than a 10-meter diameter around the location. For example, a typical statue would work as a VPS-activated Wayspot. An entire building, however, would not. One face or doorway/entrance into a building might work. We recommend sticking with smaller areas for starters (e.g. a desk, statue, or mural).

Before scanning, be aware of your surroundings and ensure you have the right to access the location you are scanning.

How to scan a Wayspot for VPS?

1. Check the area to be scanned and the surroundings of the scanned object to determine if there are any obstacles and to select a scanning route. It is necessary to plan the route you intend to use for scanning before starting the procedure.
2. Make sure your camera is in focus. Camera shake can negatively affect 3D reconstruction. Keep your phone as close to your side as possible to avoid blurring. Walk around the object you are scanning instead of standing in one location and moving your phone.
3. Walk at a slow and natural stroll pace. Move slowly and smoothly during scanning. Sudden changes of direction are a definite no-no. Move slowly and smoothly with your feet on the ground. If you are scanning in a darker setting, it’s even more important to move slowly and smoothly. Move the phone with you while you are moving (think crab walk).
4. Wayspot should always be the focal point. In order for us to build the map, it's important to focus on the Wayspot and capture the full 360° orbit of it. If it is not safe or not possible to get 360° coverage, capture as much as you can.
5. Vary your distance/angles (0-10m or 0-35ft). In order for the 3D map to work well in different scenarios, it’s important that we capture the environment around the Wayspot and have a variety of different scans. It’s important to vary your distance and angles while scanning the Wayspot.

Video of recommended Wayspot scanning technique:

Things to avoid while scanning

1. Avoid scanning while the surroundings are not safe, e.g. in the middle of the road, or in a playground with children.
2. Avoid scanning while the Wayspot is too far away (>10m or 35ft) or too big to focus your camera on.
3. Avoid scanning while you are casually taking a walk or jogging. It is important to keep the Wayspot as your focal point at all times.
4. Avoid pointing your phone at very bright objects such as a fluorescent light or the sun.
5. Avoid not moving or moving too fast while scanning. Abrupt motions will cause offsets in the reconstruction.
6. Avoid scanning if your phone gets too hot. If the temperature of the device rises too high, the performance of the device will be greatly reduced, which will negatively affect the scan.
7. Avoid uploading any scans that look incomplete or not representative of what you're trying to scan.

Wayspot Types

In the Geospatial Browser, you will see four different types of Wayspots:

Type	Icon	Description
Public		"Public" Wayspots have been approved by Niantic's Trust & Safety team and have met the required criteria of safety and public accessibility. These Wayspots may be used in published projects.
Pending		"Pending" Wayspots are being reviewed by Niantic's Trust & Safety team to determine if they meet the required criteria of safety and public accessibility. If a Pending Wayspot is VPS-activated it may be added to your project while still under review.
Rejected		"Rejected" Wayspots may have failed Niantic's Trust & Safety review, be a duplicate of an existing or previously rejected Wayspot, or may not be allowed by Niantic for another reason. These Wayspots cannot be added to projects.
Private		"Private" Waystpots are only accessible to your Workspace by scanning the location using Niantic's Wayfarer app. Private Wayspots are intended for use during development and may not be included in a published project.

Wayspot Status

In the Geospatial Browser, you will see five different statuses for Wayspots:

Status	Icon	Description
Not Activated		Wayspots with a status of 'Not Activated' have not had any scans submitted for the location. A minimum of 10 viable scans must be submitted for the location before you will be able to request activation. After one scan is submitted the Wayspot status will change to 'Scanning'.
Scanning		Wayspots with a status of 'Scanning' have had at least one scan submitted for the location. A minimum of 10 viable scans must be submitted for the location before you will be able to request activation.
Processing		Wayspots with a status of 'Processing' have had an activation request submitted and will display the 'Processing' status until the activation process has completed.
Active		Wayspots with a status of 'Active' are available to be used in projects to create WebAR content using Lightship VPS for Web.
Failed		Wayspots with a status of 'Failed' encountered an issue during the activation process. This could be a result of a number of factors, such as poor suitability of the location for VPS, insufficient scans, or corrupt data. Unfortunately this means that this Wayspot cannot be used to create WebAR content using Lightship VPS. We encourage you to find a new Wayspot to use in your 8th Wall project.

For questions or issues related to creating Wayspots, or status of existing Wayspots, please contact support@lightship.dev

Wayspot Requirements

Wayspots will only be approved and made publicly available if they meet the following criteria:

• Are a permanent physical, tangible, and identifiable place or object, or object that placemarks an area.
• Are safe and publicly accessible by pedestrians (indoor or outdoor).
• Contain accurate information in the title, description, and photo.

Wayspots perform better on Lightship VPS, when they also meet the following criteria:

• Have a clear focal point that fits within a 10m diameter sphere.
• Have features that are distinct and consistent in appearance. (Ex. A sandy beach, or a crowded patio space with moveable furniture will not work well.)
• Have minimal features that are reflective or transparent.

Wayspot Quantities

There is no limit to the number of Wayspots that can be associated with an 8th Wall project. Wayspots are localized server side via the Lightship VPS service.

Enabling Lightship VPS in Your Project

To enable Lightshit VPS in your WebAR project, you'll need to set enableVPS to true.

For A-Frame projects, set enableVps: true on the xrweb component on the <a-scene>

For Non-AFrame projects, set enableVps: true in the call to XR8.XrController.configure() prior to engine start.

Example - AFrame

<a-scene
  coaching-overlay
  landing-page
  xrextras-loading
  xrextras-runtime-error
  ...
  xrweb="enableVps: true;">

Example - Non-AFrame

XR8.XrController.configure({enableVps: true})
// Then, start the 8th Wall engine

Wayspot Events

8th Wall emits events at various stages in the Project Wayspot lifecycle (e.g. scanning, found, updated, lost, etc). Please see the API reference for specific instructions on handling these events in your web application:

• AFrame Events
• PlayCanvas Events
• XrController Dispatched Events

Landing Pages

Landing Pages are an evolution of our popular "Almost There" pages.

Why Use Landing Pages?

We have transformed these pages to become powerful branding and marketing opportunities for you and your clients. All Landing Page templates are optimized for branding and education with various layouts, an improved QR code design and support for key media.

Landing Pages ensure that your users have a meaningful experience no matter what device they are on. - They appear on devices that are not allowed or capable of accessing the Web AR experience directly. They also continue our mission of making AR accessible by helping users get to the right destination to engage with AR.

We designed Landing Pages in a manner which makes it extremely easy for developers to customize the page. We want you to benefit from an optimized Landing Page while still enabling you to spend your time on building your WebAR experience.

Landing Pages Intelligently Adapt To Your Configuration:

Use Landing Pages in Your Project:

1. Open your Project
2. Add the following tag to head.html

<meta name="8thwall:package" content="@8thwall.landing-page">

Note: For Self-Hosted projects, you would add the following <script> tag to your page instead:

<script src='https://cdn.8thwall.com/web/landing-page/landing-page.js'></script>

3. Remove xrextras-almost-there from your A-Frame project, or XRExtras.AlmostThere.pipelineModule() from your Non-AFrame project. (Landing Pages include almost-there logic in addition to the updates to the QR code page.)

4. Optionally, customize the parameters of your landing-page component as defined below. For Non-AFrame projects, please refer to the LandingPage.configure() documentation.

A-Frame component parameters (All Optional)

Parameter	Type	Default	Description
logoSrc	String		Image source for brand logo image.
logoAlt	String	"Logo"	Alt text for brand logo image.
promptPrefix	String	"Scan or visit"	Sets the text string for call to action before the URL for the experience is displayed.
url	String	8th.io link if 8th Wall hosted, or current page	Sets the displayed URL and QR code.
promptSuffix	String	"to continue"	Sets the text string for call to action after the URL for the experience is displayed.
textColor	Hex Color	"#ffffff"	Color of all the text on the Landing Page.
font	String	"'Nunito', sans-serif"	Font of all text on the Landing Page. This parameter accepts valid CSS font-family arguments.
textShadow	Bool	false	Sets text-shadow property for all text on the Landing Page.
backgroundSrc	String		Image source for background image.
backgroundBlur	Number	0.0	Applies a blur effect to the backgroundSrc if one is specified. (Typically values are between 0.0 and 1.0)
backgroundColor	String	linear-gradient(#464766,#2D2E43)	Background color of the Landing Page. This parameter accepts valid CSS background-color arguments. Background color is not displayed if a background-src or sceneEnvMap is set.
mediaSrc	String	App’s cover image, if present	Media source (3D model, image, or video) for landing page hero content. Accepted media sources include a-asset-item id, or URL.
mediaAlt	String	"Preview"	Alt text for landing page image content.
mediaAutoplay	Bool	true	If the mediaSrc is a video, specifies if the video should be played on load with sound muted.
mediaAnimation	String	[First animation clip of model if present]	If the mediaSrc is a 3D model, specify whether to play a specific animation clip associated with the model, or "none".
mediaControls	String	"minimal"	If mediaSrc is a video, specify media controls displayed to to user. Choose from "none", "mininal" or "browser" (browser defaults)
sceneEnvMap	String	"field"	Image source pointing to an equirectangular image. Or one of the following preset environments: "field", "hill", "city", "pastel", or "space".
sceneOrbitIdle	String	"spin"	If the mediaSrc is a 3D model, specify whether the model should "spin", or "none".
sceneOrbitInteraction	String	"drag"	If the mediaSrc is a 3D model, specify whether the user can interact with the orbit controls, choose "drag", or "none".
sceneLightingIntensity	Number	1.0	If the mediaSrc is a 3D model, specify the strength of the light illuminating the mode.
vrPromptPrefix	String	"or visit"	Sets the text string for call to action before the URL for the experience is displayed on VR headsets.

Example - 3D Layout with user specified parameters

A-Frame Example (screenshot above)

<a-scene
  landing-page="
    mediaSrc: https://www.mydomain.com/bat.glb;
    sceneEnvMap: hill"
  xrextras-loading
  xrextras-gesture-detector
  ...
  xrweb>

Non-AFrame Example (screenshot above)

// Configured here
LandingPage.configure({
    mediaSrc: 'https://www.mydomain.com/bat.glb',
    sceneEnvMap: 'hill',
})
XR8.addCameraPipelineModules([
  XR8.GlTextureRenderer.pipelineModule(),
  XR8.Threejs.pipelineModule(),
  XR8.XrController.pipelineModule(),
  XRExtras.FullWindowCanvas.pipelineModule(),
  XRExtras.Loading.pipelineModule(),
  XRExtras.RuntimeError.pipelineModule(),
  // Added here
  LandingPage.pipelineModule(),
  ...
])

Absolute Scale Coaching Overlay

Why Use the Coaching Overlay?

The Coaching Overlay onboards users to absolute scale experiences ensuring that they collect the best possible data to determine scale. We designed the Coaching Overlay to make it easily customizable by developers, enabling you to focus your time on building your WebAR experience.

Use Coaching Overlay in Your Project:

1. Open your Project
2. Add the following tag to head.html

<meta name="8thwall:package" content="@8thwall.coaching-overlay">

Note: For Self-Hosted projects, you would add the following <script> tag to your page instead:

<script src='https://cdn.8thwall.com/web/coaching-overlay/coaching-overlay.js'></script>

3. Optionally, customize the parameters of your coaching-overlay component as defined below. For Non-AFrame projects, please refer to the CoachingOverlay.configure() documentation.

A-Frame component parameters (All Optional)

Parameter	Type	Default	Description
animationColor	String	"white"	Color of the coaching overlay animation. This parameter accepts valid CSS color arguments.
promptColor	String	"white"	Color of all the coaching overlay text. This parameter accepts valid CSS color arguments.
promptText	String	"Move device forward and back"	Sets the text string for the animation explainer text that informs users of the motion they need to make to generate scale.
disablePrompt	Boolean	false	Set to true to hide default coaching overlay in order to use coaching overlay events for a custom overlay.

Creating a custom Coaching Overlay for your project

Coaching Overlay can be added as a pipeline module and then hidden (using the disablePrompt parameter) so that you can easily use the coaching overlay events to trigger a custom overlay.

Coaching overlay events are only fired when scale is set to absolute. Emitted coaching overlay events include:

• coaching-overlay.show: event is triggered when the coaching overlay should be shown.
• coaching-overlay.hide: event is triggered when the coaching overlay should be hidden.

Example - Coaching Overlay with user specified parameters

A-Frame Example (screenshot above)

<a-scene
  coaching-overlay="
    animationColor: #E86FFF;
    promptText: To generate scale push your phone forward and then pull back;"
  xrextras-loading
  xrextras-gesture-detector
  ...
  xrweb="scale: absolute;">

Non-AFrame Example (screenshot above)

// Configured here
CoachingOverlay.configure({
    animationColor: '#E86FFF',
    promptText: 'To generate scale push your phone forward and then pull back',
})
XR8.addCameraPipelineModules([
  XR8.GlTextureRenderer.pipelineModule(),
  XR8.Threejs.pipelineModule(),
  XR8.XrController.pipelineModule(),
  XRExtras.FullWindowCanvas.pipelineModule(),
  XRExtras.Loading.pipelineModule(),
  XRExtras.RuntimeError.pipelineModule(),
  LandingPage.pipelineModule(),
  // Added here
  CoachingOverlay.pipelineModule(),
  ...
])

Lightship VPS Coaching Overlay

Why Use the Lightship VPS Coaching Overlay?

The Coaching Overlay onboards users to Lightship VPS experiences ensuring that they properly localize at real-world locations. We designed the Coaching Overlay to make it easily customizable by developers, enabling you to focus your time on building your WebAR experience.

Use Coaching Overlay in Your Project:

1. Open your Project
2. Add the following tag to head.html

<meta name="8thwall:package" content="@8thwall.coaching-overlay">

Note: For Self-Hosted projects, you would add the following <script> tag to your page instead:

<script src='https://cdn.8thwall.com/web/coaching-overlay/coaching-overlay.js'></script>

3. Optionally, customize the parameters of your coaching-overlay component as defined below. For Non-AFrame projects, please refer to the vpsCoachingOverlay.configure() documentation.

A-Frame component parameters (All Optional)

Parameter	Type	Default	Description
wayspot-name	String		The name of the Wayspot which the coaching overlay is guiding the user to localize at. If no Wayspot name is specified, it will use the nearest project Wayspot. If the project does not have any project Wayspots, then it will use the nearest wayspot.
hint-image	String		Image displayed to the user to guide them to the real-world location. If no hint-image is specified, it will use the default image for the Wayspot. If the Wayspot does not have a default image, no image will be shown.
animation-color	String	"#FFFFFF"	Color of the coaching overlay animation. This parameter accepts valid CSS color arguments.
animation-duration	Number	5000	Total time the hint image is displayed before shrinking (in milliseconds).
text-color	String	"#FFFFFF"	Color of all the coaching overlay text. This parameter accepts valid CSS color arguments.
prompt-prefix	String	"Point your camera at"	Sets the text string for advised user action above the name of the Wayspot.
prompt-suffix	String	"and move around"	Sets the text string for advised user action below the name of the Wayspot.
status-text	String	"Scanning..."	Sets the text string that is displayed below the hint-image when it is in the shrunken state.
disable-prompt	Boolean	false	Set to true to hide default coaching overlay in order to use coaching overlay events for a custom overlay.

Creating a custom Coaching Overlay for your project

Coaching Overlay can be added as a pipeline module and then hidden (using the disablePrompt parameter) so that you can easily use the coaching overlay events to trigger a custom overlay.

Lightship VPS Coaching Overlay events are only fired when enableVps is set to true. Emitted coaching overlay events include:

• vps-coaching-overlay.show: event is triggered when the coaching overlay should be shown.
• vps-coaching-overlay.hide: event is triggered when the coaching overlay should be hidden.

Example - Coaching Overlay with user specified parameters

A-Frame Example (screenshot above)

<a-scene
  vps-coaching-overlay="
    text-color: #0000FF;
    prompt-prefix: Go look for;"
  xrextras-loading
  xrextras-gesture-detector
  ...
  xrweb="vpsEnabled: true;">

Non-AFrame Example (screenshot above)

// Configured here
vpsCoachingOverlay.configure({
    textColor: '#0000FF',
    promptPrefix: 'Go look for',
})
XR8.addCameraPipelineModules([
  XR8.GlTextureRenderer.pipelineModule(),
  XR8.Threejs.pipelineModule(),
  XR8.XrController.pipelineModule(),
  XRExtras.FullWindowCanvas.pipelineModule(),
  XRExtras.Loading.pipelineModule(),
  XRExtras.RuntimeError.pipelineModule(),
  LandingPage.pipelineModule(),
  // Added here
  vpsCoachingOverlay.pipelineModule(),
  ...
])

Customizing the Load Screen

8th Wall's XRExtras library provides modules that handle the most common WebAR application needs, including the load screen, social link-out flows and error handling.

The Loading module displays a loading overlay and camera permissions prompt while libraries are loading, and while the camera is starting up. It's the first thing your users see when they enter your WebAR experience.

This section describes how to customize the loading screen by providing values that change the color, load spinner, and load animation to match the overall design of your experience.

ID's / Classes to override

Loading Screen	iOS (13+) Motion Sensor Prompt
#requestingCameraPermissions #requestingCameraIcon #loadBackground #loadImage	.prompt-box-8w .prompt-button-8w .button-primary-8w To customize the text, you can use a MutationObserver. Please refer to code example below.

A-Frame component parameters

If you are using XRExtras with an A-Frame project, the xrextras-loading module makes it easy to customize the load screen via the following parameters:

Parameter	Type	Description
cameraBackgroundColor	Hex Color	Background color of the loading screen's top section behind the camera icon and text (See above. Loading Screen #1)
loadBackgroundColor	Hex Color	Background color of the loading screen's lower section behind the loadImage (See above. Loading Screen #3)
loadImage	ID	The ID of an image. The image needs to be an <a-asset> (See above. Loading Screen #4)
loadAnimation	String	Animation style of loadImage. Choose from spin (default), pulse, scale, or none

A-Frame Component Example

<a-scene
  tap-place
  xrextras-almost-there
  xrextras-loading="
    loadBackgroundColor: #007AFF;
    cameraBackgroundColor: #5AC8FA;
    loadImage: #myCustomImage;
    loadAnimation: pulse"
  xrextras-runtime-error
  xrweb>

<a-assets>
  <img id="myCustomImage" src="assets/my-custom-image.png">
</a-assets>

Javascript/CSS method

const load = () => { 
  XRExtras.Loading.showLoading()
  console.log('customizing loading spinner')
  const loadImage = document.getElementById("loadImage")
  if (loadImage) {
    loadImage.src="img/my-custom-image.png"
  }
}
window.XRExtras ? load() : window.addEventListener('xrextrasloaded', load)

CSS example

#requestingCameraPermissions {
  color: black;
  background-color: white;
}
#requestingCameraIcon {
  /* This changes the image from white to black */
  filter: invert(1);
}

.prompt-box-8w {
  background-color: white;
  color: #00FF00;
}
.prompt-button-8w {
  background-color: #0000FF;
}

.button-primary-8w {
  background-color: #7611B7;
}

iOS (13+) Motion Sensor Prompt Text Customization

let inDom = false
const observer = new MutationObserver(() => {
  if (document.querySelector('.prompt-box-8w')) {
    if (!inDom) {
      document.querySelector('.prompt-box-8w p').innerHTML = '<strong>My new text goes here</strong><br/><br/>Press Approve to continue.'
      document.querySelector('.prompt-button-8w').innerHTML = 'Deny'
      document.querySelector('.button-primary-8w').innerHTML = 'Approve'
    }
    inDom = true
  } else if (inDom) {
    inDom = false
    observer.disconnect()
  }
})
observer.observe(document.body, {childList: true})

Customize Video Recording

8th Wall's XRExtras library provides modules that handle the most common WebAR application needs, including the load screen, social link-out flows and error handling.

The XRExtras MediaRecorder module makes it easy to customize the Video Recording user experience in your project.

This section describes how to customize recorded videos with things like capture button behavior (tap vs hold), add video watermarks, max video length, end card behavior and looks, etc.

A-Frame primitives

xrextras-capture-button : Adds a capture button to the scene.

Parameter	Type	Default	Description
capture-mode	string	"standard"	Sets the capture mode behavior. standard: tap to take photo, tap + hold to record video. fixed: tap to toggle video recording. photo: tap to take photo. One of [standard, fixed, photo]

xrextras-capture-config : Configures the captured media.

Parameter	Type	Default	Description
max-duration-ms	int	15000	Total video duration (in miliseconds) that the capture button allows. If the end card is disabled, this corresponds to max user record time. 15000 by default.
max-dimension	int	1280	Maximum dimension (width or height) of captured video. For photo configuration, please see XR8.CanvasScreenthot.configure()
enable-end-card	bool	true	Whether the end card is included in the recorded media.
cover-image-url	string		Image source for end card cover image. Uses project's cover image by default.
end-card-call-to-action	string	"Try it at: "	Sets the text string for call to action on end card.
short-link	string		Sets the text string for end card shortlink. Uses project shortlink by default.
footer-image-url	string	Powered by 8th Wall image	Image source for end card footer image.
watermark-image-url	string	null	Image source for watermark.
watermark-max-width	int	20	Max width (%) of watermark image.
watermark-max-height	int	20	Max height (%) of watermark image.
watermark-location	string	"bottomRight"	Location of watermark image. One of topLeft, topMiddle, topRight, bottomLeft, bottomMiddle, bottomRight
file-name-prefix	string	"my-capture-"	Sets the text string that prepends the unique timestamp on file name.
request-mic	string	"auto"	Determines if you want to set up the microphone during initialization ("auto") or during runtime ("manual")
include-scene-audio	bool	true	If true, the A-Frame sounds in the scene will be part of the recorded output.

xrextras-capture-preview : Adds a media preview prefab to the scene which allows for playback, downloading, and sharing.

Parameter	Type	Default	Description
action-button-share-text	string	"Share"	Sets the text string in action button when Web Share API 2 is available (Android, iOS 15 or higher). “Share” by default.
action-button-view-text	string	"View"	Sets the text string in action button when Web Share API 2 is not available in iOS (iOS 14 or below). “View” by default.

XRExtras.MediaRecorder Events

XRExtras.MediaRecorder emits the following events.

Events Emitted

Event Emitted	Description
mediarecorder-photocomplete	Emitted after a photo is taken.
mediarecorder-recordcomplete	Emitted after a video recording is complete.
mediarecorder-previewready	Emitted after a previewable video recording is complete. (Android/Desktop only)
mediarecorder-finalizeprogress	Emitted when the media recorder is making progress in the final export. (Android/Desktop only)
mediarecorder-previewopened	Emitted after recording preview is opened.
mediarecorder-previewclosed	Emitted after recording preview is closed.

Example

<xrextras-capture-button capture-mode="standard"></xrextras-capture-button>

<xrextras-capture-config
  max-duration-ms="15000"
  max-dimension="1280"
  enable-end-card="true"
  cover-image-url=""
  end-card-call-to-action="Try it at:"
  short-link=""
  footer-image-url="//cdn.8thwall.com/web/img/almostthere/v2/poweredby-horiz-white-2.svg"
  watermark-image-url="//cdn.8thwall.com/web/img/mediarecorder/8logo.png"
  watermark-max-width="100"
  watermark-max-height="10"
  watermark-location="bottomRight"
  file-name-prefix="my-capture-"
></xrextras-capture-config>

<xrextras-capture-preview
  action-button-share-text="Share"
  action-button-view-text="View"
  finalize-text="Exporting..."
></xrextras-capture-preview>

Example - Change Action Button CSS

#actionButton {
  /* change color of action button */
  background-color: #007aff !important;
}

Importing Modules into Cloud Editor

Modules enable you to add reusable components to your project, allowing you to focus on the development of your core experience. The 8th Wall Cloud Editor allows you to import modules published by 8th Wall directly into your projects.

To import a module into your WebAR project:

1. Within the Cloud Editor, press the "+" button next to Modules.

2. Select the module that you want to import from the list.

3. Press "Import" to add your module to your project. Take note of the module alias. If you already have a module in your project with the same alias, you may be prompted to rename the module prior to adding it to your project.

4. The module is now visible in your project listed under the "Modules" section.

5. If you select the imported module, you will be taken to the module config page. This page can be used to configure various module parameter.

Once you have added a module your project you may have to make changes to your code to fully integrate the module. Modules contain documentation that should be referenced to understand how to integrate the specific module into your project code

8th Wall Payments

8th Wall Payments gives developers the tools they need to add secure payments to their AR and VR web apps. Developers can use the Payments Module found in the Cloud Editor to easily add products for purchase to their project. All payments are facilitated by the 8th Wall Payments API which enables developers to collect and receive payments.

Why use 8th Wall Payments?

Easily monetize your WebAR or WebVR experiences with 8th Wall Payments with the Payments Module. Powered by Stripe, 8th Wall Payments provide a secure way for end users to pay for your product and for you to make money developing WebXR projects.

With the 8th Wall Payments module, you have a one-step import that allows you the opportunity to monetize your web AR or web VR project using extensible payment options. With the Payments Module, you can easily customize the payment options such as cost, and item you are selling, all leveraging our streamlined checkout flow optimized for use on mobile, desktop and VR. Access all current and future payment types in one module. Test the success of your payment integration with built in test mode.

Current Payment options available:

• Access Pass: Access pass allows you to add a one time payment to your product that expires after a minimum of 1 day to a maximum of 7 days. No user login necessary. Access pass is available on one device and is removed when browser cache is cleared.

Payment Processing

To provide this payment service, 8th Wall takes a small commission of each fee, which is split with our Stripe processor. End users must agree to 8th Wall’s Terms of Service in order to make a purchase.

Payment Processing Fee:

20% of each transaction

Payment Restrictions

• 8th Wall Payments is currently only accessible to US and Japanese Bank Accounts and Debit Cards. Only USD and JPY currencies are accepted.
• 8th Wall Payments is only accessible through projects using the Cloud Editor.
• You must be an Admin or Owner of your 8th Wall workspace in order to sign up for the 8th Wall Payment API.
• 8th Wall Payments are bound to the Stripe Restricted Businesses List.
• You can only use 8th Wall Payments as your Payments Processor for App functionality, digital content or digital goods created using 8th Wall.
• All end users must agrees to 8th Wall’s Terms of Service, (see “8th Wall Payments End User Terms and Conditions” in the ToS)

Payout Dates

Sign up for Payments API on your Accounts Page. Once your account receives funds, you will receive payments on the 15th of every month. Amounts that have not been paid out will show up as Pending Amounts on your Accounts page.

Payment Support and Refunds

All payments are non-refundable. If an end user has a question about their payment they can contact support.

Using 8th Wall Payments in your project

8th Wall Payments leverages Stripe Connect for secure payment processing. In order to start building web apps with paid content, you must sign-up for a Stripe Connect account through 8th Wall. This is required to take advantage of 8th Wall Payments in order to get paid out.

Sign Up for Payments API on your Accounts Page

1. Head to your Accounts Page
2. Under Payments API select the country for your bank or debit card. We currently only support the USA.
3. Click "Start Here"

4. You will be directed to Stripe Connect. Follow the prompts to fill in all required fields. You will need to provide:

   1. Email
   2. Phone Number

   3. Details for Individual or Business

      1. Individual - Your date of birth and Home Address, Social Security number
      2. Business Name
   4. Industry,Website or Product Description
   5. Bank Account or Debit Card information where you will collect payments

After you send in your complete information, it may take several days for Stripe to process and validate your information. You can check back the status of your account on the Accounts screen.

Once confirmed, you will see your bank account information on your Accounts page

Manage Payments API Stripe Connect Account

You can view your payment details for money earned across all of your workspace web apps on the Accounts page under the Payments API overview section.

Accounts page Payment API Overview

• Bank Account - the bank account or debit card where your payout will deposit
• Total Amount - the total amount of money you have collected from all of your web apps
• Payout Date - the day of the month when you will receive your Payout. View Payout Dates for schedule.
• Next Payout Amount - the total amount of money you will receive on the next Payout Date
• Pending Amount - the total amount that you have received and is on hold for processing. It is not yet ready to be sent out in the next payout

To view your Stripe Connect account click Go to Stripe.

To update your Stripe Account payment information, such as address or bank account information, click on Update Information.

To see individual payments from your web apps, click View History.

Payments Module

Once you have signed up for 8th Wall Payments, you will need to import the Payments Module into your project in order to access the Payments API.

To import the Payments Module:

1. Open a Cloud Editor project
2. Click the + sign next to the “Modules”' section in the left hand navigation of the Cloud Editor.
3. Search for “Payments” and import the module into your project.

You are now ready to add paid content into your project!

Configurations

The Payments Module allows you to easily customize what type of payment option you want, the cost, the product, and more. You can also turn on Test Mode so you can ensure your payments work as expected.

Test Mode

Test mode enables you to simulate purchases made on your web app prior to launching publicly. Turning on Test Mode allows you to integrate the Payments API in their apps, without having to make real purchases.

Configurations for Test Mode:

Configuration	Type	Default	Description
Test Mode Enabled	Boolean	False	If True - You are simulating purchases in your product, payments are not on the server but cached locally If False - Test Mode is off
Clear Test Purchases on Run	Boolean	False	If True - Test Mode purchases will be deleted so you can retest the purchase experience If False - Test purchase will remain on local storage until cleared. This is useful for testing existing purchase flows.

Access Pass

This payment type offers users paid access to AR or VR content for a limited period of time. Access passes are well suited to enable paid access to AR/VR events such as a 1-day ticket to a holographic concert or a virtual art exhibit or 7-day access to an AR-enabled scavenger hunt.

In the end user experience, the user will:

1. View the Access Pass Prompt or the prompt to purchase the product
2. Click CTA will open up checkout flow hosted on 8thwall.com
3. Allows users to purchase a product for a specific price
4. Save the purchase on local device storage until the preconfigured time period

Configurations for Access Pass Defaults

Configuration	Type	Default	Description
Access Duration Days	number	1	(Required) The number of days that this purchase is valid for. Minimum duration is 1 day, maximum duration is 7 days.
Amount	number	0.99	(Required) The amount, in dollars or yen, to request for payment for the specified Access Pass Amounts have a respective minimum and maximum as defined by the Currency. USD: $0.99 to $99.99 JPY: ¥99 to ¥9999
Access Pass Name	string	N/A	(Required) The name of the product. This will be used in the checkout form to describe to the user what they’re purchasing.
Currency	string	usd	(Required) The currency to charge the user. Can be 'usd' (US dollars) or 'jpy' (Japanese Yen).
Checkout Page Language	string	en-US	(Required) The language that appears to the end user on the secure checkout page. Can be 'en-US' (English - United States) or 'ja-JP' (Japanese).

Advanced Analytics

8th Wall projects provide basic usage analytics, allowing you to see how many "views" you have received in the past 30 days. If you are looking for more detailed and/or historical analytics, we recommend adding 3rd party web analytics to your WebAR experience.

The process for adding analytics to a WebAR experience is the same as adding them to any non-AR website. You are welcome to use any analytics solution you prefer.

In this example, we’ll explain how to add Google Analytics to your 8th Wall project using Google Tag Manager (GTM) - making it easy to collect custom analytics on how users are both viewing and interacting with your WebAR experience.

Using GTM’s web-based user interface, you can define tags and create triggers that cause your tag to fire when certain events occur. In your 8th Wall project, fire events (using a single line of Javascript) at desired places in your code.

Analytics Pre-requisites

You must already have Google Analytics and Google Tag Manager accounts and have a basic understanding of how they work.

For more information, please refer to the following Google documentation:

• Google Analytics

  • Getting Started: https://support.google.com/analytics/answer/1008015

• Google Tag Manager

  • Overview: https://support.google.com/tagmanager/answer/6102821
  • Setup and Install: https://support.google.com/tagmanager/answer/6103696

Add Google Tag Manager to your 8th Wall Project

1. On the Workspace page of your Tag Manager container, click your container ID (e.g. "GTM-XXXXXX") to open the "Install Google Tag Manager" box. This window contains the code that you’ll later need to add to your 8th Wall project.

2. Open the 8th Wall Cloud Editor and paste the top code block into head.html:

3. Click "+" next to Files, and create a new file called gtm.html, then paste the contents of the bottom code block into this file:

4. Add the following code towards the top of app.js:

import * as googleTagManagerHtml from './gtm.html'
document.body.insertAdjacentHTML('afterbegin', googleTagManagerHtml)

Configure Google Tag Manager

1. Create a Google Analytics settings variable and add your Google Analytics Tracking ID. See https://support.google.com/tagmanager/answer/9207621 for more information.

Example:

Tracking Page Views

At a minimum, create a Tag that will fire upon page load so that you can track information about visitors to your Web AR experience.

Create Tag

• Tag Type: Google Analytics: Universal Analytics
• Track Type: Page View
• Google Analytics Settings: (Select variable created in previous step)
• Triggering: All Pages

Tracking Custom Events

GTM also provides the ability to fire events when custom actions take place inside the WebAR experience. These events will be particular to your WebAR project, but some examples might be:

• 3D object placed
• Image Target found
• Screenshot taken
• etc…

In this example, we’ll create a Tag (with Trigger) and add it to the "AFrame: Place Ground" sample project that fires each time a 3D model is spawned.

Create Custom Event Trigger

• Trigger Type: Custom Event
• Event Name: placeModel
• This trigger fires on: All Custom Events

Create Tag

Next, create a tag that will fire when the "placeModel" trigger is fired in your code.

• Tag Type: Google Analytics: Universal Analytics
• Track Type: Event
• Google Analytics Settings: (Select variable created previously)
• Triggering: Select "placeModel" trigger created in the previous step.

IMPORTANT: Make sure to save all triggers/tags created and then Submit/Publish your settings inside the GTM interface so they are live. See https://support.google.com/tagmanager/answer/6107163

Fire Event Inside 8th Wall Project

In your 8th Wall project, add the following line of javascript to fire this trigger at the desired place in your code:

window.dataLayer.push({event: 'placeModel'})

Example - based on https://www.8thwall.com/8thwall/placeground-aframe/master/tap-place.js

export const tapPlaceComponent = {
  init: function() {
    const ground = document.getElementById('ground')
    ground.addEventListener('click', event => {
      // Create new entity for the new object
      const newElement = document.createElement('a-entity')

      // The raycaster gives a location of the touch in the scene
      const touchPoint = event.detail.intersection.point
      newElement.setAttribute('position', touchPoint)

      const randomYRotation = Math.random() * 360
      newElement.setAttribute('rotation', '0 ' + randomYRotation + ' 0')

      newElement.setAttribute('visible', 'false')
      newElement.setAttribute('scale', '0.0001 0.0001 0.0001')
      
      newElement.setAttribute('shadow', {
        receive: false,
      })
      
      newElement.setAttribute('class', 'cantap')
      newElement.setAttribute('hold-drag', '')

      newElement.setAttribute('gltf-model', '#treeModel')
      this.el.sceneEl.appendChild(newElement)

      newElement.addEventListener('model-loaded', () => {
        // Once the model is loaded, we are ready to show it popping in using an animation
        newElement.setAttribute('visible', 'true')
        newElement.setAttribute('animation', {
          property: 'scale',
          to: '7 7 7',
          easing: 'easeOutElastic',
          dur: 800,
        })
        
        // **************************************************
        // Fire Google Tag Manager event once model is loaded
        // **************************************************
        window.dataLayer.push({event: 'placeModel'})
      })
    })
  }
}

Asset Bundles

The Asset bundle feature of 8th Wall's Cloud Editor allows for the use of multi-file assets. These assets typically involve files that reference each other internally using relative paths. ".glTF", ".hcap", ".msdf" and cubemap assets are a few common examples.

In the case of .hcap files, you load the asset via the "main" file, e.g. "my-hologram.hcap". Inside this file are many references to other dependent resources, such as .mp4 and .bin files. These filenames are referenced and loaded by the main file as URLs with paths relative to the .hcap file.

Create Asset Bundle

1. Prepare your files

Use one of the following methods to prepare your files before upload:

• Multi-select the individual files from your local filesystem
• Create a ZIP file.
• Locate the directory containing all of the files needed by your asset (Note: Directory upload not supported on all browsers!)

2. Create New Asset Bundle

Option 1:

In the Cloud Editor, click the "+" to the right of ASSETS and select "New asset bundle". Next, select asset type. If you aren't uploading a glTF or HCAP asset, select "Other".

Option 2:

Alternatively, you can drag the assets or ZIP directly into the ASSETS pane at the bottom-right of the Cloud Editor.

3. Preview Asset Bundle

After the files have been uploaded, you'll be able to preview the assets before adding it to your project. Select individual files in the left pane to preview them on the right.

4. Select "main" file

If your asset type requires you reference a file, set this file as your "main file". If your asset type requires you reference a folder (cubemaps, etc), set "none" as your "main file".

Note: This step is not required for glTF or HCAP assets. The main file is set automatically for these asset types.

The main file cannot be changed later. If you select the wrong file, you'll have to re-upload the asset bundle.

5. Set Asset bundle name

Give the asset bundle a name. This is the filename by which you'll access the asset bundle within your project.

6. Click "Create Bundle"

The upload of your asset bundle will be completed and it will be added to your Cloud Editor project.

Preview Asset Bundle

Assets can be previewed directly within the Cloud Editor. Select an asset on the left to preview on the right. You can preview a specific asset inside the bundle by expanding the "Show contents" menu on the right and selecting an asset inside.

Rename Asset Bundle

To rename an asset, click the "down arrow" icon to the right of your asset and choose Rename. Edit the name of the asset and hit Enter to save. Important: if you rename an assset, you'll need to go through your project and make sure all references point to the updated asset name.

Delete Asset Bundle

To delete an asset, click the "down arrow" icon to the right of your asset and choose Delete.

Referencing Asset Bundle

To reference the asset bundle from an html file in your project (e.g. body.html), simply provide the appropriate path to the src= or gltf-model= parameter.

To reference the asset bundle from javascript, use require()

Example - html

<!-- Example 1 -->
<a-assets>
  <a-asset-item id="myModel" src="assets/sand-castle.gltf"></a-asset-item>
</a-assets>
<a-entity 
  id="model"
  gltf-model="#myModel"
  class="cantap"
  scale="3 3 3"
  shadow="receive: false">
</a-entity>


<!-- Example 2 -->
<holo-cap 
  id="holo" 
  src="./assets/my-hologram.hcap"
  holo-scale="6"
  holo-touch-target="1.65 0.35"
  xrextras-hold-drag
  xrextras-two-finger-rotate 
  xrextras-pinch-scale="scale: 6">
</holo-cap>

Example - javascript

const modelFile = require('./assets/my-model.gltf')

Debug Mode

Debug Mode is an advanced Cloud Editor feature that provides logging, performance information, and enhanced visualizations directly on your device.

Note: Debug mode is currently not displayed when previewing experiences on head mounted devices.

To activate Debug Mode:

1. At the top of the Cloud Editor window, click the Preview button.
2. Below the QR code, toggle Debug Mode on.
3. Scan the QR code to preview your WebAR project with debug information superimposed over the page:

If you already have a device connected in the Cloud Editor console you can enable/disable Debug Mode at any time by pressing the “Debug Mode” toggle when you have the device tab selected.

Debug Mode Stats:

Depending on the renderer your project is using Debug Mode will display some of the following information:

Stats Panel (tap to minimize)

• fps - frames per second, framerate.
• Tris - number of triangles rendered per frame.*
• Draw Calls - number of draw calls each frame. A draw call is a call to the graphics API to draw objects (e.g. draw a triangle).*
• Textures - number of textures in the scene.*
• Tex(max) - the maximum dimension of the largest texture in the scene.*
• Shaders - number of GLSL shaders in the scene.*
• Geometries - number of geometries in the scene.*
• Points - number of points in the scene. Only displayed when the scene has more than 0.*
• Entities - number of A-Frame entities in the scene.*
• ImgTargets - number of active 8th Wall image targets in the scene.
• Models - total size in MB of all <a-asset-items> (only preloaded 3D models) in <a-assets>.*

Version Panel

• Engine Version - version of the 8th Wall AR engine the experience is running.
• Renderer Version - version of renderer the experience is running.*

Tools Panel

• Console - displays live console logs.
• Actions - options to reset the XR camera (XR8.recenter()), show detected surface, and display A-Frame inspector.
• Camera - displays XR camera position and rotation.
• Minimize - minimizes the tools panel.

[*] available in Cloud Editor projects using A-Frame

Working with iframes

Starting with iOS 9.2, Safari blocked deviceorientation and devicemotion event access from cross-origin iframes.

This prevents 8th Wall Web (if running inside the iframe) from receiving necessary deviceorientation and devicemotion data required for proper tracking if SLAM is enabled. (See Web Browser Requirements. The result is that the orientation of your digital content will appear to be wrong, and the content will "jump" all over the place when you move the phone.

If you have access to the parent window, it's possible to add a script on the parent page that will send custom messages containing deviceorientation and devicemotion data to 8th Wall's AR Engine inside the iframe via JavaScript's postMessage() method. The postMessage() method safely enables cross-origin communication between Window objects; e.g., between a page and an iframe embedded within it. (See https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)

For maximum compatibility with iOS devices, we have created two scripts:

For the OUTER website

iframe.js must be included in the HEAD of the OUTER page via this script tag:

<script src="//cdn.8thwall.com/web/iframe/iframe.js"></script>

When starting AR, register the XRIFrame by iframe ID:

window.XRIFrame.registerXRIFrame(IFRAME_ID)

When stoppping AR, deregister the XRIFrame:

window.XRIFrame.deregisterXRIFrame()

For the INNER website

iframe-inner.js must be included in the HEAD of your INNER AR website with this script tag:

<script src="//cdn.8thwall.com/web/iframe/iframe-inner.js"></script>

By allowing the inner and outer windows to communicate, deviceorientation/devicemotion data can be shared.

See sample project at https://www.8thwall.com/8thwall/inline-ar

Examples

Outer Page

<!-- Send deviceorientation/devicemotion to the INNER iframe -->
<script src="//cdn.8thwall.com/web/iframe/iframe.js"></script>

...
const IFRAME_ID = 'my-iframe' // Iframe containing AR content.
const onLoad = () => {
  window.XRIFrame.registerXRIFrame(IFRAME_ID)
}
// Add event listenters and callbacks for the body DOM.
window.addEventListener('load', onLoad, false)

...

<body>
  <iframe
    id="my-iframe"
    style="border: 0; width: 100%; height: 100%"
    allow="camera;microphone;gyroscope;accelerometer;"
    src="https://www.other-domain.com/my-web-ar/">
  </iframe>
</body>

Inner Page: AFrame projects

<head>
  <!-- Recieve deviceorientation/devicemotion from the OUTER window -->
  <script src="//cdn.8thwall.com/web/iframe/iframe-inner.js"></script>
</head>

...

<body>
  <!-- For A-FRAME -->
  <!-- NOTE: The iframe-inner script must load after A-FRAME, and iframe-inner component must appear before xrweb. -->
  <a-scene iframe-inner xrweb>
    ...
  </a-scene>

Inner Page: Non-AFrame projects

<head>
  <!-- Recieve deviceorientation/devicemotion from the OUTER window -->
  <script src="//cdn.8thwall.com/web/iframe/iframe-inner.js"></script>
</head>

...

<!-- For non-AFrame projects, add iframeInnerPipelineModule to the custom pipeline module section,
typically located in "onxrloaded" like so: -->
XR8.addCameraPipelineModules([
  // Custom pipeline modules
  iframeInnerPipelineModule,
])

Progressive Web Apps

Progressive Web Apps (PWAs) use modern web capabilities to offer users an experience that's similar to a native application. The 8th Wall Cloud Editor allows you to create a PWA version of your project so that users can add it to their home screen. Users must be connected to the internet in order to access it.

NOTE: Progressive Web Apps are only availalbe to accounts with a paid plan.

To enable PWA support for your WebAR project:

1. Visit your project settings page, and expand the “Progressive Web App” pane. (Only visible to paid workspaces)
2. Toggle the slider to Enable PWA support.
3. Customize your PWA name, icon, and colors.
4. Click "Save"

Note: For Cloud Editor projects, you may be prompted to build & re-publish your project if it was previously published. If you decide not to republish, PWA support will be included the next time your project is built.

PWA API Reference

8th Wall's XRExtras library provides an API to automatically display an install prompt in your web app.

Please refer to the PwaInstaller API reference at https://github.com/8thwall/web/tree/master/xrextras/src/pwainstallermodule

PWA Icon Requirements

• File Types: .png
• Aspect Ratio: 1:1

• Dimensions:

  • Minimum: 512 x 512 pixels

    • Note: If you upload an image larger than 512x512, it will be cropped to a 1:1 aspect ratio and resized down to 512x512.

PWA Install Prompt Customization

The PwaInstaller module from XRExtras displays an install prompt asking your user to add your web app to their home screen.

To customize the look of your install prompt, you can provide custom string values through the XRExtras.PwaInstaller.configure() API.

For a completely custom install prompt, configure the installer with displayInstallPrompt and hideInstallPrompt methods.

Self-Hosted PWA Usage

For Self-Hosted apps, we aren’t able to automatically inject details of the PWA into the HTML, requiring use of the configure API with the name and icon they’d like to appear in the install prompt.

Add the following <meta> tags to the <head> of your html:

<meta name="8thwall:pwa_name" content="My PWA Name">

<meta name="8thwall:pwa_icon" content="//cdn.mydomain.com/my_icon.png">

PWA Code Examples

Basic Example (AFrame)

<a-scene
  xrextras-almost-there
  xrextras-loading
  xrextras-runtime-error
  xrextras-pwa-installer
  xrweb>

Basic Example (Non-AFrame)

XR8.addCameraPipelineModules([
  XR8.GlTextureRenderer.pipelineModule(),
  XR8.Threejs.pipelineModule(),
  XR8.XrController.pipelineModule(),
  XRExtras.AlmostThere.pipelineModule(),
  XRExtras.FullWindowCanvas.pipelineModule(),
  XRExtras.Loading.pipelineModule(),
  XRExtras.RuntimeError.pipelineModule(),

  XRExtras.PwaInstaller.pipelineModule(), // Added here

  // Custom pipeline modules.
  myCustomPipelineModule(),
])

Customized Look Example (AFrame)

<a-scene
  xrextras-gesture-detector
  xrextras-almost-there
  xrextras-loading
  xrextras-runtime-error
  xrextras-pwa-installer="name: My Cool PWA;
    iconSrc: '//cdn.8thwall.com/my_custom_icon';
    installTitle: 'My CustomTitle';
    installSubtitle: 'My Custom Subtitle';
    installButtonText: 'Custom Install';
    iosInstallText: 'Custom iOS Install'"
  xrweb>

Customized Look Example (Non-AFrame)

XRExtras.PwaInstaller.configure({
  displayConfig: {
    name: 'My Custom PWA Name',
    iconSrc: '//cdn.8thwall.com/my_custom_icon',
    installTitle: ' My Custom Title',
    installSubtitle: 'My Custom Subtitle',
    installButtonText: 'Custom Install',
    iosInstallText: 'Custom iOS Install',
  }
})

Customized Display Time Example (AFrame)

<a-scene
  xrweb="disableWorldTracking: true"
  xrextras-gesture-detector
  xrextras-almost-there
  xrextras-loading
  xrextras-runtime-error
  xrextras-pwa-installer="minNumVisits: 5;
    displayAfterDismissalMillis: 86400000;"
>

Customized Display Time Example (Non-AFrame)

XRExtras.PwaInstaller.configure({
  promptConfig: {
    minNumVisits: 5, // Users must visit web app 5 times before prompt
    displayAfterDismissalMillis: 86400000 // One day
  }
})

Converting Models to GLB format

If you are using 8th Wall Web with A-Frame, three.js or Babylon.js, we recommend using 3D models in GLB (glTF 2.0 binary) format in your Web AR experiences. We believe GLB is currently the best format for Web AR with its small file size, great performance and versatile feature support (PBR, animations, etc).

For more information about 3d model best practices and links to a number of GLB converters, please visit:

https://www.8thwall.com/glb

Please also view this Blog article titled "5 Tips for Developers to Make Any 8th Wall WebAR Project More Realistic":

https://www.8thwall.com/blog/post/41447089034/5-tips-for-developers-to-make-any-8th-wall-webar-project-more-realistic

Device Authorization

If you are on an paid plan, you gain the ability to self-host WebAR experiences. If you are self-hosting on a webserver that hasn't been whitelisted (see Connected Domains section of the documentation), you will need to authorize your device in order to view.

Authorizing a device installs a Developer Token (cookie) into its web browser, allowing it to view any app key within the current workspace.

There is no limit to the number of devices that can be authorized, but each device needs to be authorized individually. Views of your web application from an authorized device count toward your monthly usage total.

IMPORTANT: If you have followed the steps below on an iOS device, and are still having issues, please see the Troubleshooting section for steps to fix. Safari has a feature called Intelligent Tracking Prevention that can block third party cookies (what we use to authorize your device while you're developing). When they get blocked, we can't verify your device.

How to authorize a device:

1. Login to 8thwall.com and select a Project.

2. Click Device Authorization to expand the device authorization pane.

3. Select 8th Wall Engine version to use during development. To use the latest stable version of 8th Wall, select release. To test against a pre-release version, select beta.

4. Authorize your device:

From Desktop: If you are logged into the console on your laptop/desktop, Scan the QR code from the device you wish to authorize. This installs an authorization cookie on the device.

Note: A QR code can only be scanned once. After scanning, you will receive confirmation that your device has been authorized. The console will then generate a new QR code that can be scanned to authorize another device.

Before:

After:

Confirmation (Console)	Confirmation (On Device)

From Mobile: If you are logged into 8thwall.com directly on the mobile device you wish to authorize, simply click Authorize browser. Doing so installs an authorization cookie into your mobile browser, authorizing it to view any project within the current workspace.

Before:

After:

Local Hosting

If you are on a paid plan, you gain the ability to host WebAR projects on your own web servers.

Serving web app locally from your computer can be tricky as browsers require HTTPS certificates to access the camera on your phone through a browser. As a convenience, 8th Wall has created a public GitHub repo (https://github.com/8thwall/web) where you can find a "serve" script that will run a local https webserver on your development computer. You can also download sample 8th Wall Web projects to help you get started with self-hosted configurations.

Locally From Mac

1. Install Node.js and npm

If you don't already have Node.js and npm installed, get it here: https://www.npmjs.com/get-npm

2. Open a terminal window (Terminal.app, iTerm2, etc):

# cd <directory_where_you_saved_sample_project_files>
# cd serve
# npm install
# cd ..
# ./serve/bin/serve -d <sample_project_location>

Example:

./serve/bin/serve -n -d gettingstarted/xraframe/ -p 7777

IMPORTANT: To connect to this local webserver, make sure to copy the entire "Listening" URL into your browser, including both the "https://" at the beginning and port number at the end.

NOTE: If the serve script states it's listening on 127.0.0.1:<port> (which is the loopback device aka "localhost") your mobile phone won't be able to connect to that IP address directly. Please re-run the serve script with the -i flag to specify the network interface the serve script should listen on.

Example - specify network interface:

./serve/bin/serve -d gettingstarted/xraframe/ -p 7777 -i en0

If you have issues connecting to the local webserver running on your computer, please refer to the troubleshooting section

Locally From Windows

Serving web app locally from your computer can be tricky as browsers require HTTPS certificates to access the camera on your phone through a browser. As a convenience, 8th Wall has created a public GitHub repo (https://github.com/8thwall/web) where you can find a "serve" script that will run a local https webserver on your development computer. You can also download sample 8th Wall Web projects to help you get started.

1. Install Node.js and npm

If you don't already have Node.js and npm installed, get it here: https://www.npmjs.com/get-npm

2. Open a Command Prompt (cmd.exe)

Note: Run the following command using a standard Command Prompt window (cmd.exe). The script will generate errors if run from PowerShell.

# cd <directory_where_you_saved_sample_project_files>
# cd serve
# npm install
# cd ..
# serve\bin\serve.bat -d <sample_project_location>

Example:

serve\bin\serve.bat -n -d gettingstarted\xraframe -p 7777

IMPORTANT: To connect to this local webserver, make sure to copy the entire "Listening" URL into your browser, including both the "https://" at the beginning and port number at the end.

NOTE: If the serve script states it's listening on 127.0.0.1:<port> (which is the loopback device aka "localhost") your mobile phone won't be able to connect to that IP address directly. Please re-run the serve script with the -i flag to specify the network interface the serve script should listen on.

Example - specify network interface:

serve\bin\serve.bat -d gettingstarted\xraframe -p 7777 -i WiFi

If you have issues connecting to the local webserver running on your computer, please refer to the troubleshooting section

View Project on iOS Safari

1. The “serve” command run in the previous step will display the IP and Port to connect to
2. Open Safari on iOS 11+, and connect to the “Listening” URL. Note: Safari will complain about the SSL certificates, but you can safely proceed.

IMPORTANT: Make sure to copy the entire "Listening" URL into your browser, including both the "https://" at the beginning and port number at the end.

Example: https://192.168.1.50:8080

3. Click "visit this website":
4. Click "Show Details":
5. Click "Visit Website":
6. Finally, click "Allow" to grant camera permissions and start viewing the sample AR experience:

View Project on Android

1. The “serve” command run in the previous step will display the IP and Port to connect to
2. Open Chrome, a Chrome-variant (e.g. Samsung browser) or Firefox

IMPORTANT: Make sure to copy the entire "Listening" URL into your browser, including both the "https://" at the beginning and port number at the end.

Example: https://192.168.1.50:8080

3. Chrome Example: The browser will complain that the cert is invalid, simply click "Advanced" to proceed:
4. Click "PROCEED TO ... (UNSAFE)":

Importing XRExtras into Cloud Editor

This section of the documentation is intended for advanced users who are using the 8th Wall Cloud Editor and need to create a completely customized version of XRExtras. This process involves:

• Cloning the XRExtras code from GitHub
• Importing files into your Cloud Editor project
• Going through all of the .js files and adjusting the exports
• Updating your code to use your local, custom copy of XRExtras instead of pulling our default from CDN (via meta tag)

If you only need to make basic customizations of the XRExtras loading screen, please refer to this section instead.

Note: By importing a copy of XRExtras into your Cloud Editor project, you will no longer receive the latest XRExtras updates and functionality available in from CDN. Make sure to always pull the latest version of XRExtras code from GitHub as you start new projects.

Instructions:

1. Create a myxrextras folder within your Cloud Editor project
2. Clone https://github.com/8thwall/web
3. Add contents of the xrextras/src/ directory (​https://github.com/8thwall/web/tree/master/xrextras/src​) to your project, with the exception of index.js
4. Your project contents will look something like this:

5. In head.html, remove or comment out the tag for @8thwall.xrextras so it’s no longer pulled in from our CDN:

6. In app.js, import your local xrextras library:

7. Go through all of the *.js files underneath myxrextras/ and replace all of the module.exports with export:

Examples:

myxrextras/aframe/aframe.js:

myxrextras/aframe/aframe.js:

Changing/Adding image assets

First, drag & drop new images into assets/ to upload them to your project:

In ​html files​ with src params, refer to the image asset using a relative path:

<img src="​../../assets/​my-logo.png" id="loadImage" class="spin" />

In javascript files​, use a relative path and ​require()​ to reference assets:

img.src = ​require​('​../../assets/​my-logo.png')

Changelog

Release 20: (2022-September-21, v20.1.19.684 / 2022-September-21, v20.1.17.684)

• New Features:

  • Introducing Lightship VPS for Web - create location-based WebAR experiences by connecting AR content to real-world locations.

    • Added new Geospatial Browser to the 8th Wall Developer Portal.

      • Find, create and manage VPS-activated locations (Wayspots).
      • Generate and download 3D meshes for use as occluders, physics objects, or as a reference for creating location-aware animations.
    • Added enableVps parameter to XR8.XrController.configure() and xrweb.
    • Added events when a Wayspot is ready for scanning, found, or lost.
    • Added ability to find and access Wayspot raw mesh geometry.
    • Added XR8.Vps.WayspotWatcher, an API for querying nearby WaySpots.
    • Added Lightship VPS Coaching Overlay module to guide users through a flow to localize at real-world locations.
    • Added XR8.Platform API for unlocking new 8th Wall platform features like Lightship VPS and Niantic Lightship Maps.

  • Niantic Lightship Map module

    • Add the lightship-maps module to your project on 8thwall.com to make it easy to create a variety of location-based experiences.

• Fixes and Enhancements:

  • Improved error handling for VPS network requests (20.1.19.684)

Release 19.1: (2022-August-26, v19.1.6.390 / 2022-August-10, v19.1.2.390)

• Fixes and Enhancements:

  • Fixed issues with 8th Wall experiences within WeChat on iOS.
  • Improved initial SLAM tracking for some Android devices (19.1.6.390)

Release 19: (2022-May-5, v19.0.16.390 / 2022-April-13, v19.0.14.390 / 2022-March-24, v19.0.8.390)

• New Features:

  • Introducing Absolute Scale — a major update to 8th Wall SLAM to enable real-world scale in World Effects:

    • Added ability to enable Absolute Scale in World Effects projects.
    • Added scale parameter to XR8.XrController.configure().
    • Added Coaching Overlay module to guide users through a flow to generate appropriate data for scale estimation.
  • Updated 8Frame to support A-Frame 1.3.0. (19.0.16.390)

• Fixes and Enhancements:

  • Improved performance on various devices.
  • Improved experience for some Android devices with multiple cameras.
  • Improved performance of Absolute Scale on some iOS devices. (19.0.14.390)
  • Fixed Huawei browser user messaging on Huawei devices. (19.0.14.390)

Release 18.2: (2022-March-09, v18.2.4.554 / 2022-January-14, v18.2.3.554 / 2022-January-13, v18.2.2.554)

• Fixes and Enhancements:

  • Fixed an issue where devices running iOS 13 could reload after starting an XR8 session.
  • Fixed an issue where the WebGL context could be lost after many XR8 sessions.
  • Improved experience for some Android devices with multiple cameras.
  • Fixed issue where additive blending could interefere with the camera feed.
  • Fixed an issue with transparent materials. (18.2.3.554)
  • Fixed a three.js rendering issue on devices running iOS 15.4 (18.2.4.554)

Release 18.1: (2021-December-02, v18.1.3.554)

• Fixes and Enhancements:

  • Fixed a loading issue on some iOS devices when accessing Inline AR projects.
  • Fixed an issue with denying browser prompts on some iOS devices.
  • Fixed an issue rotating device orientation between landscape and portrait within SFSafariViewController.
  • Improved compatibility with some Android devices that have atypical camera feed aspect ratios.

Release 18: (2021-November-08, v18.0.6.554)

• New Features:

  • Introducing the completely rebuilt 8th Wall Engine featuring Metaversal Deployment:

    • Added pipeline module API for session managers.
    • Added Web3D session manager.
    • Added headset session managers for Three.JS and A-Frame.
    • Updated allowedDevices to include mobile-and-headset.
    • Added additional session configuration parameters in XR8.run().

• Fixes and Enhancements:

  • Improved frame capture with a variety of Pixel devices.
  • Updated iOS WKWebView flow to support experiences accessed via LinkedIn.

• XRextras:

  • Added xrextras-opaque-background A-Frame component and XRExtras.Lifecycle.attachListener.

Release 17.2: (2021-October-26, v17.2.4.476)

• Fixes and Enhancements:

  • Enhanced SLAM map building quality.
  • Optimized tracking quality of SLAM experiences.
  • Improved PlayCanvas integration to support drawing on the same canvas that the camera feed is rendered on.

Release 17.1: (2021-September-21, v17.1.3.476)

• New Features:

  • Added new APIs

    • API to query the engine initialization state.
    • Three.js camera feed is available as a THREE.Texture.
    • Lifecycle method for pipeline module removal.

• Fixes and Enhancements:

  • Enhanced SLAM map building quality.
  • Improved tracking quality on a wide range of devices.
  • Improved frame rate of World Effects, Face Effects, & Image Target experiences on Chromium-based and Firefox browsers.
  • Improved MediaRecorder video quality on Android devices.

• XRExtras Enhancements:

  • Enhanced MediaRecorder share flow when Web Share API Level 2 is enabled.
  • Improved startup time of Loading module.
  • Improved lifecycle handling for Runtime Error, Almost There and Loading modules.
  • Updated the Almost There module to improve the success of QR Code scans.
  • Improved Full Window Canvas logic on iPad split screen views.

Release 17: (2021-July-20, v17.0.5.476)

• Fixes and Enhancements:

  • Enhanced above-horizon tracking boosts map quality improving the performance of WebAR experiences that ask users to point their phones up to fully explore AR content.
  • Optimized SLAM relocalization snaps AR content back to the proper position in world space after an interruption.
  • Improved tracking quality of SLAM experiences when users make extreme yaw movements.

• XRExtras Enhancements:

  • Updated MediaRecorder to return to the media preview when users press the “view” button on the iOS dialog box after choosing to download media.

Release 16.1: (2021-June-02, v16.1.4.1227)

• Fixes and Enhancements:

  • Improved recovery of world tracking after an interruption.
  • Improved lifecycle management of event listeners in A-Frame projects.
  • Fixed an issue with WebGL 1 errors on some Android devices.
  • Fixed an issue where MediaRecorder would occasionally not render a recording preview.
  • Fixed an issue where swapping the camera multiple times could result in crashing.
  • Improved compatibility using canvases with pre-defined WebGL 2 contexts.

Release 16: (2021-May-21, v16.0.8.1227 / 2021-April-27, v16.0.6.1227 / 2021-April-22, v16.0.5.1227)

• New Features:

  • Introducing the all-new 8th Wall MediaRecorder:

    • Uses W3C web standards compliant recording when available.
    • Optimizes performance to improve frame rate during recording.
    • Enhancements to image quality and frame rate of recording.

• Fixes and Enhancements:

  • Improved tracking quality and frame rate of SLAM experiences.
  • Improved tracking quality and frame rate of Image Target experiences.
  • Improved experience for some Android devices with multiple cameras.
  • Fixed raycasting issues with PlayCanvas.
  • Fixed SLAM tracking issue (v16.0.8.1227)

• XRExtras Enhancements:

  • Updated MediaRecorder to provide a progress bar while transcoding recordings on relevant devices.

Release 15.3: (2021-March-2, v15.3.3.487)

• New Features:

  • Updated 8Frame to support A-Frame 1.2.0.

• Fixes and Enhancements:

  • Fixed an issue with resuming the camera feed in Safari after navigating back to an 8th Wall app.
  • Fixed an issue with resuming the camera feed after re-opening a WKWebView
  • Improved compatibility with different rendering engine versions.
  • Optimized iOS WKWebView flows for some native apps.

Release 15.2: (2020-December-14, v15.2.4.487)

• New Features:

  • Added support for WKWebView on devices running iOS 14.3 or later.
  • Made a compute context accessible to Pipeline Modules to accelerate offscreen GPU computer vision.
  • Updated 8Frame to support A-Frame 1.1.0.

• Fixes and Enhancements:

  • Improved compatibility with rendering engines.
  • Added the ability to load and unload image targets while tracking other image targets.
  • Fixed an issue with MediaRecorder related to audio context switching.
  • Improved experience for some Android devices with multiple cameras.
  • Fixed an issue where WebGL errors would sometimes be hidden.
  • Fixed an issue with simultaneously tracking flat and curved image targets.
  • Fixed an issue with switching between WebGL and WebGL2 pipelines.

• XRExtras Enhancements:

  • Improved flows for iOS WKWebView on devices running iOS 14.3 or later.
  • Fixed an issue with Stats module pipeline detach.

Release 15.1: (2020-October-27, v15.1.4.487)

• New Features:

  • Added support for Curved Image Targets to be used simultaneously with SLAM.
  • Added support for A-Frame 1.1.0-beta, THREE 120, and MRCS HoloVideoObject 1.2.5.

• Fixes and Enhancements:

  • Improved quality of tracking Flat Image Targets simultaneously with SLAM.
  • Improved framerate for devices with iOS 14 or greater.
  • Improved experience for some Android devices with multiple cameras. (v15.0.9.487)
  • Optimized performance of some GPU processing.
  • Enhanced PlayCanvas integration with support for switching between XR and FaceController cameras.
  • Fixed an issue with MediaRecorder microphone access where onPause events were not closing the microphone input.
  • Fixed an issue with MediaRecorder occasionally producing files incompatible with some video players.
  • Fixed a raycasting issue with AFrame 1.0.x. (v15.0.9.487)

• XRExtras Enhancements:

  • XRExtras.PauseOnHidden() module pauses the camera feed when your browser tab is hidden.

Release 15: (2020-October-09, v15.0.9.487 / 2020-September-22, v15.0.8.487)

• New Features:

  • 8th Wall Curved Image Targets:

    • Added support for cylindrical image targets such as those wrapped around bottles, cans and more.
    • Added support for conical image targets such as those wrapped around coffee cups, party hats, lampshades and more.

• Fixes and Enhancements:

  • Improved tracking quality for SLAM and Image Targets.
  • Fixed an issue with MRCS Holograms and device routing on iOS 14.
  • Fixed an issue with Face Effects and Image Targets where updates to mirroredDisplay were not reflected during runtime.
  • Improved experience for some Android devices with multiple cameras. (v15.0.9.487)
  • Fixed a raycasting issue with AFrame 1.0.x (v15.0.9.487)

• XRExtras Enhancements:

  • New AFrame components for easy Curved Image Target development:

    • 3D container prefab component that forms a portal-like container that 3D content can be placed inside.
    • Video playback prefab component for easily enabling video on curved image targets.
  • Improved detection of Web Share API Level 2 support.

Release 14.2: (2020-July-30, v14.2.4.949)

• New Features:

  • Updated MediaRecorder.configure() to provide more control over audio output and mixing:

    • Pass in your own audioContext.
    • Request mic permissions during setup or runtime.
    • Optionally disable microphone recording.
    • Add your own audio nodes to the audio graph.
    • Incorporate scene audio into recording playback.

• Fixes and Enhancements:

  • Fixed an issue where clip planes were not set from PlayCanvas in some cases.
  • Added support for switching between world tracking, image target tracking, and face effects at runtime.
  • Fixed an issue where vertex buffers could be rebound after vertex arrays were deleted.
  • Improved experience for some Android devices with multiple cameras.

Release 14.1: (2020-July-06, v14.1.4.949)

• New Features:

  • Introducing 8th Wall Video Recording:

    • Add in-browser video recording to any 8th Wall project with the new XR8.MediaRecorder API.
    • Add dynamic overlays and end cards with custom images and call to action.
    • Configure maximum video duration and resolution.
  • Added microphone as a configurable module permission.

• Fixes and Enhancements:

  • Enhanced CanvasScreenshot functionality with improved overlay support.
  • Fixed an issue with Face Effects that could cause visual glitches on device orientation change.
  • Improved Face Effects right-handed coordinate compatibility with Bablyon.js.
  • Improved graphics pipeline compatibility with Babylon.js.

• XRExtras Enhancements:

  • Record button prefab component for capturing video and photos:

    • Select between standard, fixed, and photo capture modes.
  • Preview prefab component for easily previewing, downloading, and sharing captures

  • Use XRExtras to easily customize the Video Recording user experience in your project:

    • Configure maximum video length and resolution.
    • Add optional watermark to each frame of the video.
    • Add optional end card to add branding and a call to action at the end of the video.

Release 14: (2020-May-26)

• New Features:

  • Introducing 8th Wall Face Effects: Attach 3D objects to face attachment points and paint your face with custom materials, shaders or videos.
  • Selfie Mode: Use the front camera with a mirrored display to get the perfect selfie shot.
  • Desktop Browsers: Enable your image target and face effect experiences to run in desktop browsers utilizing the webcam.

• Fixes and Enhancements:

  • Enhanced capture field of view on Pixel 4/4XL phones.
  • Enhanced camera profiles for certain phone models.
  • Fixed an issue with changing device orientation during startup.
  • Fixed an issue with swapping the camera direction on the same a-scene.
  • Fixed an issue with AFrame look-controls not being removed on scene restart.
  • Improved experience for some Android phones with multiple cameras.
  • Other fixes and enhancements.

• XRExtras Enhancements:

  • Enhanced almost there flows for experiences that can be viewed on desktop.
  • PauseOnBlur module stops the camera when your tab is not active.
  • New AFrame components for easy face effects and desktop experience development.
  • New ThreeExtras for rendering PBR materials, basic materials, and videos to faces.

Release 13.2: (2020-Feb-13)

• New Features:

  • Release camera stream on XR8.pause() and reopen on XR8.resume().
  • Added API to access shader program and modify uniforms used by GlTextureRenderer.
  • Added API to configure WebGL context on run.

• Fixes and Enhancements:

  • Fix black video issue on iOS when a user long-presses on an image.
  • Improved iOS screenshot capture speed and reliability.
  • Fixed alpha channel rendering when taking a screenshot.
  • Improved experience for some Android phones with multiple cameras.
  • Improved detection of social network web views.

• XRExtras Enhancements:

  • Improved QR codes with better compatibility with native cameras.
  • Improved link out flows for social networks.
  • Improved CSS customization.

Release 13.1:

• New Features:

  • Improved framerate on high resolution Android phones.
  • Camera pipeline can be stopped and restarted.
  • Camera pipeline modules can be removed at runtime or when stopped.
  • New lifecycle callbacks for attaching and detaching.

• Fixes and Enhancements:

  • Improved experience for some Android phones with multiple cameras.
  • Fixed iOS phone calibration on iOS 12.2 and above.

Release 13:

• New Features:

  • Adds support for cloud-based creation, collaboration, publishing, and hosting of WebAR content.

Release 12.1:

• Fixes and Enhancements:

  • Increased camera resolution on newer iOS devices.
  • Increased AFrame fps on high-res Android devices.
  • Fixed three.js r103+ raycasting issues.
  • Added support for iPadOS.
  • Fixed memory issue when loading many image targets repeatedly.
  • Minor performance enhances and bug fixes.

Release 12:

• New Features:

  • Increased image target upload limit to 1000 image targets per app.
  • New API for selecting active image targets at runtime.
  • Apps can now scan for up to 10 image targets simultaneously.
  • Front facing camera is supported in camera framework and image targets.
  • Engine support for PlayCanvas.

• Fixes:

  • Improved experience for some Android phones with multiple cameras.

• XRExtras:

  • Improved visual quality on Android Phones.
  • Support for iOS 13 device orientation permissions.
  • Better error handling for missing web assembly on some older versions of iOS.
  • Support for PlayCanvas.

Release 11.2:

• New Features:

  • iOS 13 motion support.

Release 11.1:

• Fixes and Enhancements:

  • Reduced memory usage.
  • Improved tracking performance.
  • Enhanced detection of browser capabilities.

Release 11:

• New Features:

  • Added support for Image Targets.
  • Added support for BabylonJS.
  • Reduced JS binary size to 1MB.
  • Added support running 8th Wall Web inside a cross-origin iframe.
  • Minor API additions.

Release 10.1:

• New Features:

  • Added support for A-Frame 0.9.0.

• Fixes:

  • Fixed error when providing includedTypes to XrController.hitTest().
  • Reduced memory usage when tracking over extended distances.

Release 10:

Release 10 adds a revamped web developer console with streamlined developer-mode, access to allowed origins and QR codes. It adds 8th Wall Web support for XRExtras, an open-source package for error handling, loading visualizations, "almost there" flows, and more.

• New Features:

  • Revamped web developer console.

  • XR Extras provides a convenient solution for:

    • Load screens and requesting camera permissions.
    • Redirecting users from unsupported devices or browsers ("almost there").
    • Runtime error handling.
    • Drawing a full screen camera feed in low-level frameworks like threejs.
  • Added public lighting, hit test interfaces to XrController.
  • Other minor API additions.

• Fixes:

  • Improved app startup speed.
  • Fixed a framework issue where errors were not propagated on startup.
  • Fixed an issue that could occur with WebGL during initialization.
  • Use window.screen interface for device orientation if available.
  • Fixed a threejs issue that could occur when the canvas is resized.

Release 9.3:

• New Features:

  • Minor API additions: XR.addCameraPipelineModules() and XR.FullWindowCanvas.pipelineModule()

Release 9.2:

• New Features:

  • Public documentation released: https://docs.8thwall.com/web

Release 9.1:

• New Features:

  • Added support for Amazon Sumerian in 8th Wall Web
  • Improved tracking stability and eliminated jitter

Release 9:

• Initial release of 8th Wall Web!

Known Issues & Workarounds

• Device Not Authorized
• Invalid App Key error message
• Loading Screen Infinite Spinner
• 6DoF Camera Motion Not Working
• Object Not Tracking Surface Properly
• Can't connect to "serve" script

Device Not Authorized

Issue: When trying to view my Web App, I receive a "Device Not Authorized" error message.

Safari specific:

The situation:

• While viewing your project, you see 'Device not Authorized' alerts, but
• apps.8thwall.com/token shows the correct authorization.

Why does this happen?

Safari has a feature called Intelligent Tracking Prevention that can block third party cookies (what we use to authorize your device while you're developing). When they get blocked, we can't verify your device.

Steps to fix:

1. Close Safari
2. Turn off Intelligent Tracking Prevention at Settings>Safari>Prevent Cross-Site Tracking
3. Clear 8th Wall cookies at Settings>Safari>Advanced>Website Data>8thwall.com
4. Reauthorize from console
5. Check your project
6. If not fixed: Clear all cookies at Settings>Safari>Clear History and Website Data
7. Reauthorize from console

Otherwise

See Invalid App Key steps from #5 onwards for more troubleshooting.

Domain Not Authorized

Issue: When trying to view a self-hosted Web AR experience, I receive a "Domain Not Authorized" error message.

Solutions:

1. Make sure you have white-listed the domain(s) of your web server. Self-Hosted domains are subdomain specific - e.g. "mydomain.com" is NOT the same as "www.mydomain.com". If you will be hosting at both mydomain.com and www.mydomain.com, you must specify BOTH. Please refer to the Connected Domains (see Self Hosted Projects) section of the docs for more info.

2. If Domain='' (empty), check the RefererPolicy settings on your web server.

In the screenshot above, the Domain= value is empty. It should be set to the domain of your self-hosted WebAR experience. In this situation, the Referer Policy of your web server is too restrictive. The Referer http header is used to verify that your app key is being used from an approved/whitelisted server.

To verify the configuration, open the Chrome/Safari debugger and look at Network tab. The xrweb Request Headers should include a Referer value, and this needs to match the domain(s) you have whitelisted in your project settings.

Incorrect - In this screenshot the Referrer Policy is set to "same-origin". This means a referrer will only be sent for same-site origins, but cross-origin requests will not send referrer information:

Correct - The xrweb Request Headers includes a Referer value.

The default value of "strict-origin-when-cross-origin" is recommended. Please refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy for configuration options.

Invalid App Key

Issue: When trying to view my Web App, I receive an "Invalid App Key" or "Domain Not Authorized" error message.

Troubleshooting steps:

1. Verify your app key was pasted properly into source code.
2. Verify you are connecting to your web app via https. This is required by mobile browsers for camera access.
3. Verify you are using a supported browser, see Web Browser Requirements
4. Verify your device has been properly authorized. On your phone, visit https://apps.8thwall.com/token to view device authorization status.
5. If you are a member of multiple Web Developer workspaces, make sure that the App Key and Dev Token are from the same workspace.
6. If your web browser is in Private Browsing or Incognito mode, please exit Private/Incognito mode, re-authorize your device, and try again.
7. Clear website data & cookies from your web browser, re-authorize your device, and try again.
8. If you are on a paid plan and are trying to access your WebAR experience publicly, make sure that Connected Domains are configured properly.

Black textures on iOS devices

Issue: When using high resolution and/or a large number of textures on certain versions of iOS, Safari can run out of GPU memory. The textures may render black or cause the page to crash.

Workarounds:

1. Reduce the size/resolution of the textures used in your scene (3D models, images, videos, etc).

This can be done using your favorite image editing and/or 3d modeling program, however, if you already have an existing .glb model, a quick and easy way to resize the textures within the 3d model is to use https://gltf.report/

• Drag your 3d model onto the page.
• In the left column, set the maximum desired texture size (1). Note: For best results, we suggest using textures 1024x1024 or smaller.
• Click play (2) to run the script. The Console (lower left) will display status of the operation.
• Download your modified GLB model by clicking Export (3)

2. Disable image bitmaps on iOS devices:

There are existing bugs in iOS 14 and iOS 15 related to image bitmaps that can cause texture issues. Disable image bitmaps to help prevent black textures and crashes. See example below:

Example: Disable iOS Bitmaps (add to the top of app.js):

// Bitmaps can cause texture issues on iOS. This workaround can help prevent black textures and crashes.
const IS_IOS =
  /^(iPad|iPhone|iPod)/.test(window.navigator.platform) ||
  (/^Mac/.test(window.navigator.platform) && window.navigator.maxTouchPoints > 1)
if (IS_IOS) {
  window.createImageBitmap = undefined
}

Loading Screen Infinite Spinner

Issue

When accessing a WebAR experience, the page is stuck on the Loading screen with an "infinite spinner".

Why does this happen?

If you are using the XRExtras loading module (which is included with all 8th Wall projects and examples by default), the loading screen is displayed while the scene and assets are loading, and while the browser is waiting for browser permissions to be accepted. If the scene takes a long time to load, or if something prevents the scene from fully initializing, it can appears to be "stuck" on this screen forever.

Potential Causes

1. Large Assets and/or Slow Internet Connection

If you are in a location with slow wifi and/or cellular service while attempting to load a Web AR page with large assets, the scene may not really be "stuck", but rather just taking a long time to load. Use the browser's Network inspector to see if your page is simply in process of downloading assets.

Additionally, try to optimize scene assets as much as possible. This can include techniques such as compressing textures, reducing texture and/or video resolution, and reducing the polygon count of 3D models.

2. Camera locked to a background tab

Some devices/browsers may not let you open the camera if it's already in use by another tab. Try closing any other tabs that may be using the camera, then re-load the page.

3. iOS Safari specific: CSS elements push the video element "off the screen"

If you have added custom HTML/CSS elements to your Web AR experience, make sure that they are properly overlaid on top of the scene. If the video element on the page is pushed off-screen, iOS Safari won't render the video feed. This in turn triggers a series of events that make it appear as if 8th Wall is "stuck". In reality, here is what is going on:

Video feed doesn't render -> AFrame scene doesn't fully initialize -> AFrame scene never emits the "loaded" event -> XRExtras Loading module never disappears (as it it's listening for the scen's "loading" event which never fires!)

To resolve this, we recommend using the Safari inspector's "Layout" view to visualize the positioning of your DOM content. Often times, you'll see something similar to the image below where the video element is pushed "off the screen" / "below the fold".

To resolve, adjust the CSS positioning of your elements so they do not push the video feed off the screen. Using absolute positioning is one way to do this.

6DoF Camera Motion Not Working

Issue: As I move my phone, the camera position does not update.

Resolution: Check the position of the camera in your scene. The camera should NOT be at a height (Y) of zero. Set it to Non-Zero value. The Y position of the camera at start effectively determines the scale of virtual content on a surface (e.g. smaller y, bigger content)

Object Not Tracking Surface Properly

Issue: Content in my scene doesn't appear to be "sticking" to a surface properly

Resolution:

To place an object on a surface, the base of the object needs to be at a height of Y=0

Note: Setting the position at a height of Y=0 isn't necesarily sufficient.

For example, if the transform your model is at the center of the object, placing it at Y=0 will result in part of the object living below the surface. In this case you'll need to adjust the vertical position of the object so that the bottom of the object sits at Y=0.

It's often helpful to visualize object positioning relative to the surface by placing a semi-transparent plane at Y=0.

A-Frame example:

<a-plane position="0 0 0" rotation="-90 0 0" width="4" height="4" material="side: double; color: #FFFF00; transparent: true; opacity: 0.5" shadow></a-plane>

Three.js example:

  // Create a 1x1 Plane with a transparent yellow material
  var geometry = new THREE.PlaneGeometry( 1, 1, 1, 1 );   // THREE.PlaneGeometry (width, height, widthSegments, heightSegments)
  var material = new THREE.MeshBasicMaterial( {color: 0xffff00, transparent:true, opacity:0.5, side: THREE.DoubleSide} );
  var plane = new THREE.Mesh( geometry, material );
  // Rotate 90 degrees (in radians) along X so plane is parallel to ground 
  plane.rotateX(1.5708)
  plane.position.set(0, 0, 0)
  scene.add( plane );

Can't connect to "serve" script

Issue:

I'm using the "serve" script (from 8th Wall Web's public GitHub repo: https://github.com/8thwall/web) to run a local webserver on my laptop and it says it's listening on 127.0.0.1. My phone is unable to connect to the laptop using that IP address.

"127.0.0.1" is the loopback address of your laptop (aka "localhost"), so other devices such as your phone won't be able to connect directly to that IP address. For some reason, the serve script has decided to listen on the loopback interface.

Resolution:

Please re-run the serve script with the -i flag and specify the network interface you wish to use.

Example (Mac):

./serve/bin/serve -d gettingstarted/xraframe/ -p 7777 -i en0

Example (Windows):

Note: Run the following command using a standard Command Prompt window (cmd.exe). The script will generate errors if run from PowerShell.

serve\bin\serve.bat -d gettingstarted\xraframe -p 7777 -i WiFi

If you are still unable to connect, please check the following:

• Make sure that your computer and mobile device are both connected to the same WiFi network.
• Disable the local firewall running on your computer.
• To connect, either scan the QR code or make sure to copy the entire "Listening" URL into your browser, including both the "https://" at the beginning and port number at the end.

Help & Support

Need some help? 8th Wall is here to help you succeed. Contact us directly, or reach out to the community to get answers.

Ways to get help:

Slack	Email Support
Join our public Slack channel to discuss and ask questions with members of the 8th Wall community.	Email support@8thwall.com to get help directly from our support team.

[1] Intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for 8th Wall’s products remain at the sole discretion of 8th Wall, Inc.

API Overview

This section of the documentation contains details of 8th Wall Web's Javascript API.

XR8

Description

Entry point for 8th Wall's Javascript API

Functions

Function	Description
addCameraPipelineModule	Adds a module to the camera pipeline that will receive event callbacks for each stage in the camera pipeline.
addCameraPipelineModules	Add multiple camera pipeline modules. This is a convenience method that calls addCameraPipelineModule in order on each element of the input array.
clearCameraPipelineModules	Remove all camera pipeline modules from the camera loop.
initialize	Returns a promise that is fulfilled when the AR Engine's WebAssembly is initialized.
isInitialized	Indicates whether or not the AR Engine's WebAssembly is initialized.
isPaused	Indicates whether or not the XR session is paused.
pause	Pause the current XR session. While paused, the camera feed is stopped and device motion is not tracked.
resume	Resume the current XR session.
removeCameraPipelineModule	Removes a module from the camera pipeline.
removeCameraPipelineModules	Remove multiple camera pipeline modules. This is a convenience method that calls removeCameraPipelineModule in order on each element of the input array.
requiredPermissions	Return a list of permissions required by the application.
run	Open the camera and start running the camera run loop.
runPreRender	Executes all lifecycle updates that should happen before rendering.
runPostRender	Executes all lifecycle updates that should happen after rendering.
stop	Stop the current XR session. While stopped, the camera feed is closed and device motion is not tracked.
version	Get the 8th Wall Web engine version.

Events

Event Emitted	Description
xrloaded	This event is emitted once XR8 has loaded.

Modules

Module	Description
AFrame	Entry point for A-Frame integration with 8th Wall Web.
Babylonjs	Entry point for Babylon.js integration with 8th Wall Web.
CameraPixelArray	Provides a camera pipeline module that gives access to camera data as a grayscale or color uint8 array.
CanvasScreenshot	Provides a camera pipeline module that can generate screenshots of the current scene.
FaceController	Provides face detection and meshing, and interfaces for configuring tracking.
GlTextureRenderer	Provides a camera pipeline module that draws the camera feed to a canvas as well as extra utilities for GL drawing operations.
MediaRecorder	Provides a camera pipeline module that allows you to record a video in MP4 format.
PlayCanvas	Entry point for PlayCanvas integration with 8th Wall Web.
Sumerian	Entry point for Sumerian integration with 8th Wall Web.
Threejs	Provides a camera pipeline module that drives three.js camera to do virtual overlays.
XrConfig	Specifying class of devices and cameras that pipeline modules should run on.
XrController	XrController provides 6DoF camera tracking and interfaces for configuring tracking.
XrDevice	Provides information about device compatibility and characteristics.
XrPermissions	Utilities for specifying permissions required by a pipeline module.

XR8.addCameraPipelineModule()

XR8.addCameraPipelineModule()

Description

8th Wall camera applications are built using a camera pipeline module framework. For a full description on camera pipeline modules, see CameraPipelineModule.

Applications install modules which then control the behavior of the application at runtime. A module object must have a .name string which is unique within the application, and then should provide one or more of the camera lifecycle methods which will be executed at the appropriate point in the run loop.

During the main runtime of an application, each camera frame goes through the following cycle:

onBeforeRun -> onCameraStatusChange (requesting -> hasStream -> hasVideo | failed) -> onStart -> onAttach -> onProcessGpu -> onProcessCpu -> onUpdate -> onRender

Camera modules should implement one or more of the following camera lifecycle methods:

Function	Description
onAppResourcesLoaded	Called when we have received the resources attached to an app from the server.
onAttach	Called before the first time a module receives frame updates. It is called on modules that were added either before or after the pipeline is running.
onBeforeRun	Called immediately after XR8.run(). If any promises are returned, XR will wait on all promises before continuing.
onCameraStatusChange	Called when a change occurs during the camera permissions request.
onCanvasSizeChange	Called when the canvas changes size.
onDetach	is called after the last time a module receives frame updates. This is either after the engine is stopped or the module is manually removed from the pipeline, whichever comes first.
onDeviceOrientationChange	Called when the device changes landscape/portrait orientation.
onException	Called when an error occurs in XR. Called with the error object.
onPaused	Called when XR8.pause() is called.
onProcessCpu	Called to read results of GPU processing and return usable data.
onProcessGpu	Called to start GPU processing.
onRemove	is called when a module is removed from the pipeline.
onRender	Called after onUpdate. This is the time for the rendering engine to issue any WebGL drawing commands. If an application is providing its own run loop and is relying on XR8.runPreRender() and XR8.runPostRender(), this method is not called and all rendering must be coordinated by the external run loop.
onResume	Called when XR8.resume() is called.
onStart	Called when XR starts. First callback after XR8.run() is called.
onUpdate	Called to update the scene before render. Data returned by modules in onProcessGpu and onProcessCpu will be present as processGpu.modulename and processCpu.modulename where the name is given by module.name = "modulename".
onVideoSizeChange	Called when the canvas changes size.
requiredPermissions	Modules can indicate what browser capabilities they require that may need permissions requests. These can be used by the framework to request appropriate permissions if absent, or to create components that request the appropriate permissions before running XR.

Note: Camera modules that implement onProcessGpu or onProcessCpu can provide data to subsequent stages of the pipeline. This is done by the module's name.

Example1 - A camera pipeline module for managing camera permissions:

XR8.addCameraPipelineModule({
  name = 'camerastartupmodule',
  onCameraStatusChange = ({status}) {
    if (status == 'requesting') {
      myApplication.showCameraPermissionsPrompt()
    } else if (status == 'hasStream') {
      myApplication.dismissCameraPermissionsPrompt()
    } else if (status == 'hasVideo') {
      myApplication.startMainApplictation()
    } else if (status == 'failed') {
      myApplication.promptUserToChangeBrowserSettings()
    }
  },
})

Example2 - a QR code scanning application could be built like this:

// Install a module which gets the camera feed as a UInt8Array.
XR8.addCameraPipelineModule(
  XR8.CameraPixelArray.pipelineModule({luminance: true, width: 240, height: 320}))

// Install a module that draws the camera feed to the canvas.
XR8.addCameraPipelineModule(XR8.GlTextureRenderer.pipelineModule())

// Create our custom application logic for scanning and displaying QR codes.
XR8.addCameraPipelineModule({
  name = 'qrscan',
  onProcessCpu = ({onProcessGpuResult}) => {
    // CameraPixelArray.pipelineModule() returned these in onProcessGpu.
    const { pixels, rows, cols, rowBytes } = onProcesGpuResult.camerapixelarray
    const { wasFound, url, corners } = findQrCode(pixels, rows, cols, rowBytes)
    return { wasFound, url, corners }
  },
  onUpdate = ({onProcessCpuResult}) => {
    // These were returned by this module ('qrscan') in onProcessCpu
    const {wasFound, url, corners } = onProcessCpuResult.qrscan
    if (wasFound) {
      showUrlAndCorners(url, corners)
    }
  },
})

XR8.addCameraPipelineModules()

XR8.addCameraPipelineModules([ modules ])

Description

Add multiple camera pipeline modules. This is a convenience method that calls addCameraPipelineModule in order on each element of the input array.

Parameters

Parameter	Description
modules	An array of camera pipeline modules.

Example

const onxrloaded = () => {
  XR8.addCameraPipelineModules([  // Add camera pipeline modules.
    // Existing pipeline modules.
    XR8.GlTextureRenderer.pipelineModule(),  // Draws the camera feed.
  ])

  // Request camera permissions and run the camera.
  XR8.run({canvas: document.getElementById('camerafeed')})
}

// Wait until the XR javascript has loaded before making XR calls.
window.XR8 ? onxrloaded() : window.addEventListener('xrloaded', onxrloaded)

XR8.clearCameraPipelineModules()

XR8.clearCameraPipelineModules()

Description

Remove all camera pipeline modules from the camera loop.

Parameters

None

Example

XR8.clearCameraPipelineModules()

XR8.initialize()

XR8.initialize()

Parameters

None

Description

Returns a promise that is fulfilled when the AR Engine's WebAssembly is initialized.

Example

XR8.initialize().then(() => console.log(XR8.version())

XR8.isInitialized()

bool XR8.isInitialized()

Parameters

None

Description

Indicates whether or not the AR Engine's WebAssembly is initialized.

Example

if (XR8.isInitialized()) {
  console.log(XR8.version())
}

XR8.isPaused()

bool XR8.isPaused()

Parameters

None

Description

Indicates whether or not the XR session is paused.

Example

// Call XR8.pause() / XR8.resume() when the button is pressed.
document.getElementById('pause').addEventListener(
  'click',
  () => {
    if (!XR8.isPaused()) {
      XR8.pause()
    } else {
      XR8.resume()
    }
  },
  true)

XR8.pause()

XR8.pause()

Parameters

None

Description

Pause the current XR session. While paused, device motion is not tracked.

Example

// Call XR8.pause() / XR8.resume() when the button is pressed.
document.getElementById('pause').addEventListener(
  'click',
  () => {
    if (!XR8.isPaused()) {
      XR8.pause()
    } else {
      XR8.resume()
    }
  },
  true)

XR8.removeCameraPipelineModule()

XR8.removeCameraPipelineModule(moduleName)

Description

Removes a module from the camera pipeline.

Parameters

Parameter	Description
moduleName	The string name string of a module.

Example

XR8.removeCameraPipelineModule('reality')

XR8.removeCameraPipelineModules()

XR8.removeCameraPipelineModules([ moduleNames ])

Description

Remove multiple camera pipeline modules. This is a convenience method that calls removeCameraPipelineModule in order on each element of the input array.

Parameters

Parameter	Description
moduleNames	An array of objects with a name property, or a name strings of modules.

Example

XR8.removeCameraPipelineModules(['threejsrenderer', 'reality'])

XR8.requiredPermissions()

XR8.requiredPermissions()

Parameters

None

Description

Return a list of permissions required by the application.

Example

if (XR8.XrPermissions) {
  const permissions = XR8.XrPermissions.permissions()
  const requiredPermissions = XR8.requiredPermissions()
  if (!requiredPermissions.has(permissions.DEVICE_ORIENTATION)) {
    return
  }
}

XR8.resume()

XR8.resume()

Parameters

None

Description

Resume the current XR session after it has been paused.

Example

// Call XR8.pause() / XR8.resume() when the button is pressed.
document.getElementById('pause').addEventListener(
  'click',
  () => {
    if (!XR8.isPaused()) {
      XR8.pause()
    } else {
      XR8.resume()
    }
  },
  true)

XR8.run()

XR8.run(canvas, webgl2, ownRunLoop, cameraConfig, glContextConfig, allowedDevices, sessionConfiguration)

Parameters

Property	Type	Default	Description
canvas	HTMLCanvasElement		The HTML Canvas that the camera feed will be drawn to.
webgl2 [Optional]	bool	true	If true, use WebGL2 if available, otherwise fallback to WebGL1. If false, always use WebGL1.
ownRunLoop [Optional]	bool	true	If true, XR should use it's own run loop. If false, you will provide your own run loop and be responsible for calling runPreRender and runPostRender yourself [Advanced Users only]
cameraConfig: {direction} [Optional]	object	{direction: XR8.XrConfig.camera().BACK}	Desired camera to use. Supported values for direction are XR8.XrConfig.camera().BACK or XR8.XrConfig.camera().FRONT
glContextConfig [Optional]	WebGLContextAttributes	null	The attributes to configure the WebGL canvas context.
allowedDevices [Optional]	XR8.XrConfig.device()	XR8.XrConfig.device().MOBILE_AND_HEADSETS	Specify the class of devices that the pipeline should run on. If the current device is not in that class, running will fail prior prior to opening the camera. If allowedDevices is XR8.XrConfig.device().ANY, always open the camera. Note that world tracking can only be used with XR8.XrConfig.device().MOBILE_AND_HEADSETS or XR8.XrConfig.device().MOBILE.
sessionConfiguration: {disableXrTablet, xrTabletStartsMinimized, defaultEnvironment} [Optional]	Object	{}	Configure options related to varying types of sessions.

sessionConfiguration is an object with the following [Optional] properties:

Property	Type	Default	Description
disableXrTablet [Optional]	bool	false	Disable the tablet visible in immersive sessions.
xrTabletStartsMinimized [Optional]	bool	false	The tablet will start minimized.
defaultEnvironment {disabled, floorScale, floorTexture, floorColor, fogIntensity, skyTopColor, skyBottomColor, skyGradientStrength} [Optional]	Object	{}	Configure options related to the default environment of your immersive session.

defaultEnvironment is an object with the following [Optional] properties:

Property	Type	Default	Description
disabled [Optional]	bool	false	Disable the default "void space" background.
floorScale [Optional]	Number	1	Shrink or grow the floor texture.
floorTexture [Optional]	Asset		Specify an alternative texture asset or URL for the tiled floor.
floorColor [Optional]	Hex Color	#1A1C2A	Set the floor color.
fogIntensity [Optional]	Number	1	Increase or decrease fog density.
skyTopColor [Optional]	Hex Color	#BDC0D6	Set the color of the sky directly above the user.
skyBottomColor [Optional]	Hex Color	#1A1C2A	Set the color of the sky at the horizon.
skyGradientStrength [Optional]	Number	1	Control how sharply the sky gradient transitions.

Notes:

• cameraConfig: World tracking (SLAM) is only supported on the back camera. If you are using the front camera, you must disable world tracking by calling XR8.XrController.configure({disableWorldTracking: true}) first.

Description

Open the camera and start running the camera run loop.

Example

// Open the camera and start running the camera run loop
// In index.html: <canvas id="camerafeed"></canvas>
XR8.run({canvas: document.getElementById('camerafeed')})

Example - Using Front camera (image tracking only)

// Disable world tracking (SLAM). This is required to use the front camera.
XR8.XrController.configure({disableWorldTracking: true})
// Open the camera and start running the camera run loop
// In index.html: <canvas id="camerafeed"></canvas>
XR8.run({canvas: document.getElementById('camerafeed'), cameraConfig: {direction: XR8.XrConfig.camera().FRONT}})

Example - Set glContextConfig

// Open the camera and start running the camera run loop with an opaque canvas.
// In index.html: <canvas id="camerafeed"></canvas>
XR8.run({canvas: document.getElementById('camerafeed'), glContextConfig: {alpha: false, preserveDrawingBuffer: false}})

XR8.runPreRender()

XR8.runPreRender( timestamp )

Description

Executes all lifecycle updates that should happen before rendering.

IMPORTANT: Make sure that onStart has been called before calling runPreRender()/runPostRender().

Parameters

Parameter	Description
timestamp	The current time, in milliseconds.

Example

// Implement A-Frame components tick() method
function tick() {
  // Check device compatibility and run any necessary view geometry updates and draw the camera feed.
  ...
  // Run XR lifecycle methods
  XR8.runPreRender(Date.now())
  }

XR8.runPostRender()

XR8.runPostRender()

Description

Executes all lifecycle updates that should happen after rendering.

IMPORTANT: Make sure that onStart has been called before calling runPreRender()/runPostRender().

Parameters

None

Example

// Implement A-Frame components tock() method
  function tock() {
  // Check whether XR is initialized
  ...
  // Run XR lifecycle methods
  XR8.runPostRender()
}

XR8.stop()

XR8.stop()

Parameters

None

Description

While stopped, the camera feed is closed and device motion is not tracked. Must call XR8.run() to restart after the engine is stopped.

Example

XR8.stop()

XR8.version()

string XR8.version()

Parameters

None

Description

Get the 8th Wall Web engine version.

Example

console.log(XR8.version())

AccessPass

Description

Provides a module for monetizing your Web AR and Web VR experience. This is only available for 8th Wall Hosted projects, and requires the Payments Module.

import {AccessPass} from 'payments'

Functions

Function	Description
requestPurchaseIfNeeded	Opens a checkout window where the customer can securely make a payment for the provided access pass.

AccessPass.requestPurchaseIfNeeded()

AccessPass.requestPurchaseIfNeeded({ amount, name, productId, statementDescriptor, accessDurationDays, currency, language })

Description

Opens a checkout window where the customer can securely make a payment for the provided access pass.

If a valid access pass has already been purchased in the past, the returned Promise will resolve immediately with information on the previous purchase.

Any parameters provided via this API will supersede any parameters provided in the Module Configuration.

Parameters

Parameter	Type	Description
amount	number	The amount to charge for this access pass, in USD. Minimum of 0.99 and maximum of 99.99.
name	string	The name of the product. This is displayed to users on the checkout screen. Maximum of 30 characters.
productId	string	A unique identifier for this access pass. Maximum of 30 characters.
statementDescriptor	string	The descriptor that appears on the customer’s credit card statement. Maximum of 22 characters.
accessDurationDays	number	The number of days a customer is allowed access for. Minimum of 1 and maximum of 7.
currency	string	The currency to charge the user. Can be 'usd' (US dollars) or 'jpy' (Japanese Yen).
language	string	The language that appears to the end user on the secure checkout page. Can be 'en-US' (English - United States) or 'ja-JP' (Japanese).

Returns

A Promise which will resolve if the customer has completed the purchase successfully. The result includes information about the purchase that was made:

{
  productId: '1-day-access-pass',
  timestamp: 1653413347810,
  expirationTimestamp: 1653499747810,
}

Throws

An error is thrown if the customer does not complete the purchase successfully.

Example - Code

AccessPass.requestPurchaseIfNeeded({ 
    amount: 9.99,
    name: '1-Day Access Pass',
    productId: '1-day-access-pass',
    statementDescriptor: '1DAY ACCESS PASS',
    accessDurationDays: 1,
    currency: 'usd',
    language: 'en-US',
})

XR8.AFrame

A-Frame (https://aframe.io) is a web framework designed for building virtual reality experiences. By adding 8th Wall Web to your A-Frame project, you can now easily build augmented reality experiences for the web.

Adding 8th Wall Web to A-Frame

Cloud Editor

1. Simply add a "meta" tag in head.html to include the "8-Frame library in your project. If you are cloning from any of 8th Wall's A-Frame based templates or self-hosted projects, it will already be there. Also, there is no need to manually add your AppKey.

<meta name="8thwall:renderer" content="aframe:1.3.0">

Self Hosted

8th Wall Web can be added to your A-Frame project in a few easy steps:

1. Include a slightly modified version of A-Frame (referred to as "8-Frame") which fixes some polish concerns:

<script src="//cdn.8thwall.com/web/aframe/8frame-1.3.0.min.js"></script>

2. Add the following script tag to the HEAD of your page. Replace the X's with your app key:

<script src="//apps.8thwall.com/xrweb?appKey=XXXXX"></script>

World Tracking and/or Image Targets

1. If you want World Tracking or Image Target tracking, add an xrweb component to your a-scene tag:

<a-scene xrweb>

xrweb Attributes (all optional)

Component	Type	Default	Description
scale	String	"responsive"	Either responsive or absolute. responsive will return values so that the camera on frame 1 is at the origin defined via XR8.XrController.updateCameraProjectionMatrix(). absolute will return the camera, image targets, etc in meters. The default is responsive. When using absolute the x-position, z-position, and rotation of the starting pose will respect the parameters set in XR8.XrController.updateCameraProjectionMatrix() once scale has been estimated. The y-position will depend on the camera's physical height from the ground plane.
disableWorldTracking	bool	false	If true, turn off SLAM tracking for efficiency.
enableVps	bool	false	If true, look for Project Wayspots and a mesh. The mesh that is returned has no relation to Project Wayspots and will be returned even if no Project Wayspots are configured. Enabling VPS overrides settings for scale and disableWorldTracking.
cameraDirection	string	back	Desired camera to use. Choose from: back or front. Use cameraDirection: front; with mirroredDisplay: true; for selfie mode. Note that world tracking is only supported with cameraDirection: back;.`
allowedDevices	string	"mobile-and-headsets"	Supported device classes. Choose from: 'mobile-and-headsets' , 'mobile' or 'any'. Use 'any' to enable laptop or desktop-type devices with built-in or attached webcams. Note that world tracking is only supported on 'mobile-and-headsets' or mobile.
mirroredDisplay	bool	false	If true, flip left and right in the output geometry and reverse the direction of the camera feed. Use 'mirroredDisplay: true;' with 'cameraDirection: front;' for selfie mode. Should not be enabled if World Tracking (SLAM) is enabled.
disableXrTablet	bool	false	Disable the tablet visible in immersive sessions.
xrTabletStartsMinimized	bool	false	The tablet will start minimized.
disableDefaultEnvironment	bool	false	Disable the default "void space" background.
disableDesktopCameraControls	bool	false	Disable WASD and mouse look for camera.
disableDesktopTouchEmulation	bool	false	Disable desktop fake touches.
disableXrTouchEmulation	bool	false	Don’t emit touch events based on controller raycasts with the scene.
disableCameraReparenting	bool	false	Disable camera -> controller object move
defaultEnvironmentFloorScale	Number	1	Shrink or grow the floor texture.
defaultEnvironmentFloorTexture	Asset		Specify an alternative texture asset or URL for the tiled floor.
defaultEnvironmentFloorColor	Hex Color	#1A1C2A	Set the floor color.
defaultEnvironmentFogIntensity	Number	1	Increase or decrease fog density.
defaultEnvironmentSkyTopColor	Hex Color	#BDC0D6	Set the color of the sky directly above the user.
defaultEnvironmentSkyBottomColor	Hex Color	#1A1C2A	Set the color of the sky at the horizon.
defaultEnvironmentSkyGradientStrength	Number	1	Control how sharply the sky gradient transitions.

Notes:

• cameraDirection: World tracking (SLAM) is only supported on the back camera. If you are using the front camera, you must disable world tracking by setting disableWorldTracking: true.
• World tracking (SLAM) is only supported on mobile devices.
• xrweb and xrface cannot be used at the same time.

Face Effects

1. If you want Face Effects tracking, add an xrface component to your a-scene tag:

<a-scene xrface>

xrface Attributes

Component	Type	Default	Description
cameraDirection	string	back	Desired camera to use. Choose from: back or front. Use cameraDirection: front; with mirroredDisplay: true; for selfie mode.
allowedDevices	string	"mobile"	Supported device classes. Choose from: 'mobile' or 'any'. Use 'any' to enable laptop or desktop-type devices with built-in or attached webcams.
mirroredDisplay	bool	false	If true, flip left and right in the output geometry and reverse the direction of the camera feed. Use 'mirroredDisplay: true;' with 'cameraDirection: front;' for selfie mode.
meshGeometry	array	['face']	Configure which portions of the face mesh will have returned triangle indices. Can be any combination of 'face', 'eyes' and/or 'mouth'.

Notes:

• xrweb and xrface cannot be used at the same time.

Functions

Function	Description
xrwebComponent	Creates an A-Frame component for World Tracking and/or Image Target tracking which can be registered with AFRAME.registerComponent(). Generally won't need to be called directly.
xrfaceComponent	Creates an A-Frame component for Face Effects tracking which can be registered with AFRAME.registerComponent(). Generally won't need to be called directly.

Example - SLAM enabled (default)

  <a-scene xrweb>

Example - SLAM disabled (image tracking only)

  <a-scene xrweb="disableWorldTracking: true">

Example - Enable VPS

  <a-scene xrweb="enableVps: true">

Example - Front camera (image tracking only)

  <a-scene xrweb="disableWorldTracking: true; cameraDirection: front">

XR8.AFrame.xrwebComponent()

XR8.AFrame.xrwebComponent()

Parameters

None

Description

Creates an A-Frame component which can be registered with AFRAME.registerComponent(). This, however, generally won't need to be called directly. On 8th Wall Web script load, this component will be registered automatically if it is detected that A-Frame has loaded (i.e if window.AFRAME exists).

Example

window.AFRAME.registerComponent('xrweb', XR8.AFrame.xrwebComponent())

AFrame Events

This section describes the events emitted by the "xrweb" or "xrface" A-Frame component.

You can listen for these events in your web application to call a function that handles the event.

Events Emitted

The following events are emitted by both "xrweb" and "xrface":

Event Emitted	Description
camerastatuschange	This event is emitted when the status of the camera changes. See onCameraStatusChange from XR8.addCameraPipelineModule for more information on the possible status.
realityerror	This event is emitted when an error has occured when initializing 8th Wall Web. This is the recommended time at which any error messages should be displayed. The XrDevice API can help with determining what type of error messaging should be displayed.
realityready	This event is emitted when 8th Wall Web has initialized and at least one frame has been successfully processed. This is the recommended time at which any loading elements should be hidden.
screenshoterror	This event is emitted in response to the screenshotrequest resulting in an error.
screenshotready	This event is emitted in response to the screenshotrequest event being being completed successfully. The JPEG compressed image of the AFrame canvas will be provided.

Events Emitted by xrweb

Event Emitted	Description
xrimageloading	This event is emitted when detection image loading begins.
xrimagescanning	This event is emitted when all detection images have been loaded and scanning has begun.
xrimagefound	This event is emitted when an image target is first found.
xrimageupdated	This event is emitted when an image target changes position, rotation or scale.
xrimagelost	This event is emitted when an image target is no longer being tracked.
xrmeshfound	This event is emitted when a mesh is first found either after start or after a recenter().
xrmeshupdated	This event is emitted when the first mesh found changes position or rotation.
xrmeshlost	This event is emitted when recenter() is called.
xrprojectwayspotscanning	This event is emitted when all Project Wayspots have been loaded for scanning.
xrprojectwayspotfound	This event is emitted when a Project Wayspot is first found.
xrprojectwayspotupdated	This event is emitted when a Project Wayspot changes position or rotation.
xrprojectwayspotlost	This event is emitted when a Project Wayspot is no longer being tracked.
xrtrackingstatus	This event is emitted when the XrController starts and any time tracking status or reason changes.

Events Emitted by xrface

Event Emitted	Description
xrfaceloading	This event is emitted when when loading begins for additional face AR resources.
xrfacescanning	This event is emitted when AR resources have been loaded and scanning has begun.
xrfacefound	This event is emitted when a face is first found.
xrfacepdated	This event is emitted when face is subsequently found.
xrfacelost	This event is emitted when a face is no longer being tracked.

camerastatuschange

Description

This event is emitted when the status of the camera changes. See onCameraStatusChange from XR8.addCameraPipelineModule for more information on the possible status.

Example:

var handleCameraStatusChange = function handleCameraStatusChange(event) {
  console.log('status change', event.detail.status);

  switch (event.detail.status) {
    case 'requesting':
      // Do something
      break;

    case 'hasStream':
      // Do something
      break;

    case 'failed':
      event.target.emit('realityerror');
      break;
  }
};
let scene = this.el.sceneEl
scene.addEventListener('camerastatuschange', handleCameraStatusChange)

realityerror

Description

This event is emitted when an error has occured when initializing 8th Wall Web. This is the recommended time at which any error messages should be displayed. The XrDevice API can help with determining what type of error messaging should be displayed.

Example:

let scene = this.el.sceneEl
  scene.addEventListener('realityerror', (event) => {
    if (XR8.XrDevice.isDeviceBrowserCompatible()) {
      // Browser is compatible. Print the exception for more information.
      console.log(event.detail.error)
      return
    }

    // Browser is not compatible. Check the reasons why it may not be.
    for (let reason of XR8.XrDevice.incompatibleReasons()) {
      // Handle each XR8.XrDevice.IncompatibilityReasons
    }
  })

realityready

Description

This event is emitted when 8th Wall Web has initialized.

Example:

let scene = this.el.sceneEl
scene.addEventListener('realityready', () => {
  // Hide loading UI
})

screenshoterror

Description

This event is emitted in response to the screenshotrequest resulting in an error.

Example:

let scene = this.el.sceneEl
scene.addEventListener('screenshoterror', (event) => {
  console.log(event.detail)
  // Handle screenshot error.
})

screenshotready

Description

This event is emitted in response to the screenshotrequest event being being completed successfully. The JPEG compressed image of the AFrame canvas will be provided.

Example:

let scene = this.el.sceneEl
scene.addEventListener('screenshotready', (event) => {
  // screenshotPreview is an <img> HTML element
  const image = document.getElementById('screenshotPreview')
  image.src = 'data:image/jpeg;base64,' + event.detail
})

xrimageloading

Description

This event is emitted by xrweb when detection image loading begins.

imageloading.detail : { imageTargets: {name, type, metadata} }

Property	Description
name	The image's name.
type	One of 'FLAT', 'CYLINDRICAL', 'CONICAL'.
metadata	User metadata.

Example:

const componentMap = {}

const addComponents = ({detail}) => {
  detail.imageTargets.forEach(({name, type, metadata}) => {
    // ...
  })
}

this.el.sceneEl.addEventListener('xrimageloading', addComponents)

xrimagescanning

Description

This event is emitted by xrweb when all detection images have been loaded and scanning has begun.

imagescanning.detail : { imageTargets: {name, type, metadata, geometry} }

Property	Description
name	The image's name.
type	One of 'FLAT', 'CYLINDRICAL', 'CONICAL'.
metadata	User metadata.
geometry	Object containing geometry data. If type=FLAT: {scaledWidth, scaledHeight}, lse if type=CYLINDRICAL or type=CONICAL: {height, radiusTop, radiusBottom, arcStartRadians, arcLengthRadians}

If type = FLAT, geometry:

Property	Description
scaledWidth	The width of the image in the scene, when multiplied by scale.
scaledHeight	The height of the image in the scene, when multiplied by scale.

If type= CYLINDRICAL or CONICAL, geometry:

Property	Description
height	Height of the curved target.
radiusTop	Radius of the curved target at the top.
radiusBottom	Radius of the curved target at the bottom.
arcStartRadians	Starting angle in radians.
arcLengthRadians	Central angle in radians.

xrimagefound

Description

This event is emitted by xrweb when an image target is first found.

imagefound.detail : { name, type, position, rotation, scale, scaledWidth, scaledHeight, height, radiusTop, radiusBottom, arcStartRadians, arcLengthRadians }

Property	Description
name	The image's name.
type	One of 'FLAT', 'CYLINDRICAL', 'CONICAL'.`
position: {x, y, z}	The 3d position of the located image.
rotation: {w, x, y, z}	The 3d local orientation of the located image.
scale	A scale factor that should be applied to object attached to this image.

If type = FLAT:

Property	Description
scaledWidth	The width of the image in the scene, when multiplied by scale.
scaledHeight	The height of the image in the scene, when multiplied by scale.

If type= CYLINDRICAL or CONICAL:

Property	Description
height	Height of the curved target.
radiusTop	Radius of the curved target at the top.
radiusBottom	Radius of the curved target at the bottom.
arcStartRadians	Starting angle in radians.
arcLengthRadians	Central angle in radians.

Example:

AFRAME.registerComponent('my-named-image-target', {
  schema: {
    name: { type: 'string' }
  },
  init: function () {
    const object3D = this.el.object3D
    const name = this.data.name
    object3D.visible = false

    const showImage = ({detail}) => {
      if (name != detail.name) {
        return
      }
      object3D.position.copy(detail.position)
      object3D.quaternion.copy(detail.rotation)
      object3D.scale.set(detail.scale, detail.scale, detail.scale)
      object3D.visible = true
    }

    const hideImage = ({detail}) => {
      if (name != detail.name) {
        return
      }
      object3D.visible = false
    }

    this.el.sceneEl.addEventListener('xrimagefound', showImage)
    this.el.sceneEl.addEventListener('xrimageupdated', showImage)
    this.el.sceneEl.addEventListener('xrimagelost', hideImage)
  }
})

xrimageupdated

Description

This event is emitted by xrweb when an image target changes position, rotation or scale.

imageupdated.detail : { name, type, position, rotation, scale, scaledWidth, scaledHeight, height, radiusTop, radiusBottom, arcStartRadians, arcLengthRadians }

Property	Description
name	The image's name.
type	One of 'FLAT', 'CYLINDRICAL', 'CONICAL'.`
position: {x, y, z}	The 3d position of the located image.
rotation: {w, x, y, z}	The 3d local orientation of the located image.
scale	A scale factor that should be applied to object attached to this image.

If type = FLAT:

Property	Description
scaledWidth	The width of the image in the scene, when multiplied by scale.
scaledHeight	The height of the image in the scene, when multiplied by scale.

If type= CYLINDRICAL or CONICAL:

Property	Description
height	Height of the curved target.
radiusTop	Radius of the curved target at the top.
radiusBottom	Radius of the curved target at the bottom.
arcStartRadians	Starting angle in radians.
arcLengthRadians	Central angle in radians.

Example:

AFRAME.registerComponent('my-named-image-target', {
  schema: {
    name: { type: 'string' }
  },
  init: function () {
    const object3D = this.el.object3D
    const name = this.data.name
    object3D.visible = false

    const showImage = ({detail}) => {
      if (name != detail.name) {
        return
      }
      object3D.position.copy(detail.position)
      object3D.quaternion.copy(detail.rotation)
      object3D.scale.set(detail.scale, detail.scale, detail.scale)
      object3D.visible = true
    }

    const hideImage = ({detail}) => {
      if (name != detail.name) {
        return
      }
      object3D.visible = false
    }

    this.el.sceneEl.addEventListener('xrimagefound', showImage)
    this.el.sceneEl.addEventListener('xrimageupdated', showImage)
    this.el.sceneEl.addEventListener('xrimagelost', hideImage)
  }
})

xrimagelost

Description

This event is emitted by xrweb when an image target is no longer being tracked.

imagelost.detail : { name, type, position, rotation, scale, scaledWidth, scaledHeight, height, radiusTop, radiusBottom, arcStartRadians, arcLengthRadians }

Property	Description
name	The image's name.
type	One of 'FLAT', 'CYLINDRICAL', 'CONICAL'.`
position: {x, y, z}	The 3d position of the located image.
rotation: {w, x, y, z}	The 3d local orientation of the located image.
scale	A scale factor that should be applied to object attached to this image.

If type = FLAT:

Property	Description
scaledWidth	The width of the image in the scene, when multiplied by scale.
scaledHeight	The height of the image in the scene, when multiplied by scale.

If type= CYLINDRICAL or CONICAL:

Property	Description
height	Height of the curved target.
radiusTop	Radius of the curved target at the top.
radiusBottom	Radius of the curved target at the bottom.
arcStartRadians	Starting angle in radians.
arcLengthRadians	Central angle in radians.

Example:

AFRAME.registerComponent('my-named-image-target', {
  schema: {
    name: { type: 'string' }
  },
  init: function () {
    const object3D = this.el.object3D
    const name = this.data.name
    object3D.visible = false

    const showImage = ({detail}) => {
      if (name != detail.name) {
        return
      }
      object3D.position.copy(detail.position)
      object3D.quaternion.copy(detail.rotation)
      object3D.scale.set(detail.scale, detail.scale, detail.scale)
      object3D.visible = true
    }

    const hideImage = ({detail}) => {
      if (name != detail.name) {
        return
      }
      object3D.visible = false
    }

    this.el.sceneEl.addEventListener('xrimagefound', showImage)
    this.el.sceneEl.addEventListener('xrimageupdated', showImage)
    this.el.sceneEl.addEventListener('xrimagelost', hideImage)
  }
})

xrmeshfound

Description

This event is emitted when a mesh is first found either after start or after a recenter().

xrmeshfound.detail : { id, position, rotation, bufferGeometry }

Property	Description
id	An id for this mesh that is stable within a session
position: {x, y, z}	The 3d position of the located mesh.
rotation: {w, x, y, z}	The 3d local orientation (quaternion) of the located mesh.
bufferGeometry:	A THREE.BufferGeometry mesh.

xrmeshupdated

Description

This event is emitted when the first mesh found changes position or rotation.

xrmeshupdated.detail : { id, position, rotation }

Property	Description
id	An id for this mesh that is stable within a session
position: {x, y, z}	The 3d position of the located mesh.
rotation: {w, x, y, z}	The 3d local orientation (quaternion) of the located mesh.

xrmeshlost

Description

This event is emitted when recenter() is called.

xrmeshlost.detail : { id }

Property	Description
id	An id for this mesh that is stable within a session

xrprojectwayspotscanning

Description

This event is emitted when all Project Wayspots have been loaded for scanning.

xrprojectwayspotfound.detail : { wayspots: [] }

Property	Description
wayspots: []	An array objects containing Wayspot information.

wayspots is an array of objects with the following properties:

Property	Description
id	An id for this Project Wayspot that is stable within a session
name	Project Wayspot name.
imageUrl	URL to a representative image for this Project Wayspot.
title	Project Wayspot title.
lat	Latitude of this Project Wayspot.
lng	Longitude of this Project Wayspot.

xrprojectwayspotfound

Description

This event is emitted when a Project Wayspot is first found.

xrprojectwayspotfound.detail : { name, position, rotation }

Property	Description
name	The Project Wayspot name.
position: {x, y, z}	The 3d position of the located Project Wayspot.
rotation: {w, x, y, z}	The 3d local orientation (quaternion) of the located Project Wayspot.

xrprojectwayspotupdated

Description

This event is emitted when a Project Wayspot changes position or rotation.

xrprojectwayspotupdated.detail : { name, position, rotation }

Property	Description
name	The Project Wayspot name.
position: {x, y, z}	The 3d position of the located Project Wayspot.
rotation: {w, x, y, z}	The 3d local orientation (quaternion) of the located Project Wayspot.

xrprojectwayspotlost

Description

This event is emitted when a Project Wayspot is no longer being tracked.

xrprojectwayspotlost.detail : { name, position, rotation }

Property	Description
name	The Project Wayspot name.
position: {x, y, z}	The 3d position of the located Project Wayspot.
rotation: {w, x, y, z}	The 3d local orientation (quaternion) of the located Project Wayspot.

xrtrackingstatus

Description

This event is emitted by xrweb when XrController is loaded and any time tracking status or reason changes.

xrtrackingstatus : { status, reason }

Property	Description
status	One of 'LIMITED' or 'NORMAL'.
reason	One of 'INITIALIZING' or 'UNDEFINED'.

Example:

const updateScene = ({detail}) => {
  const {status, reason} = detail
  if (status === 'NORMAL') {
    // Show scene
  }
}
this.el.sceneEl.addEventListener('xrtrackingstatus', updateScene)

xrfaceloading

Description

This event is emitted by xrface when when loading begins for additional face AR resources.

xrfaceloading.detail : {maxDetections, pointsPerDetection, indices, uvs}

Property	Description
maxDetections	The maximum number of faces that can be simultaneously processed.
pointsPerDetection	Number of vertices that will be extracted per face.
indices: [{a, b, c}]	Indexes into the vertices array that form the triangles of the requested mesh, as specified with meshGeometry on configure.
uvs: [{u, v}]	uv positions into a texture map corresponding to the returned vertex points.

Example:

const initMesh = ({detail}) => {
  const {pointsPerDetection, uvs, indices} = detail
  this.el.object3D.add(generateMeshGeometry({pointsPerDetection, uvs, indices}))
}
this.el.sceneEl.addEventListener('xrfaceloading', initMesh)

xrfacescanning

Description

This event is emitted by xrface when all face AR resources have been loaded and scanning has begun.

xrfacescanning.detail : {maxDetections, pointsPerDetection, indices, uvs}

Property	Description
maxDetections	The maximum number of faces that can be simultaneously processed.
pointsPerDetection	Number of vertices that will be extracted per face.
indices: [{a, b, c}]	Indexes into the vertices array that form the triangles of the requested mesh, as specified with meshGeometry on configure.
uvs: [{u, v}]	uv positions into a texture map corresponding to the returned vertex points.

Example:

const initMesh = ({detail}) => {
  const {pointsPerDetection, uvs, indices} = detail
  this.el.object3D.add(generateMeshGeometry({pointsPerDetection, uvs, indices}))
}
this.el.sceneEl.addEventListener('xrfacescanning', initMesh)

xrfacefound

Description

This event is emitted by xrface when a face is first found.

xrfacefound.detail : {id, transform, vertices, normals, attachmentPoints}

Property	Description
id	A numerical id of the located face.
transform: {position, rotation, scale, scaledWidth, scaledHeight, scaledDepth}	Transform information of the located face.
vertices: [{x, y, z}]	Position of face points, relative to transform.
normals: [{x, y, z}]	Normal direction of vertices, relative to transform.
attachmentPoints: { name, position: {x,y,z} }	See XR8.FaceController.AttachmentPoints for list of available attachment points. position is relative to the transform.

transform is an object with the following properties:

Property	Description
position {x, y, z}	The 3d position of the located face.
rotation {w, x, y, z}	The 3d local orientation of the located face.
scale	A scale factor that should be applied to objects attached to this face.
scaledWidth	Approximate width of the head in the scene when multiplied by scale.
scaledHeight	Approximate height of the head in the scene when multiplied by scale.
scaledDepth	Approximate depth of the head in the scene when multiplied by scale.

Example:

const faceRigidComponent = {
  init: function () {
    const object3D = this.el.object3D
    object3D.visible = false
    const show = ({detail}) => {
      const {position, rotation, scale} = detail.transform
      object3D.position.copy(position)
      object3D.quaternion.copy(rotation)
      object3D.scale.set(scale, scale, scale)
      object3D.visible = true
    }
    const hide = ({detail}) => { object3D.visible = false }
    this.el.sceneEl.addEventListener('xrfacefound', show)
    this.el.sceneEl.addEventListener('xrfaceupdated', show)
    this.el.sceneEl.addEventListener('xrfacelost', hide)
  }
}

xrfaceupdated

Description

This event is emitted by xrface when face is subsequently found.

xrfaceupdated.detail : {id, transform, vertices, normals, attachmentPoints}

Property	Description
id	A numerical id of the located face.
transform: {position, rotation, scale, scaledWidth, scaledHeight, scaledDepth}	Transform information of the located face.
vertices: [{x, y, z}]	Position of face points, relative to transform.
normals: [{x, y, z}]	Normal direction of vertices, relative to transform.
attachmentPoints: { name, position: {x,y,z} }	See XR8.FaceController.AttachmentPoints for list of available attachment points. position is relative to the transform.

transform is an object with the following properties:

Property	Description
position {x, y, z}	The 3d position of the located face.
rotation {w, x, y, z}	The 3d local orientation of the located face.
scale	A scale factor that should be applied to objects attached to this face.
scaledWidth	Approximate width of the head in the scene when multiplied by scale.
scaledHeight	Approximate height of the head in the scene when multiplied by scale.
scaledDepth	Approximate depth of the head in the scene when multiplied by scale.

Example:

const faceRigidComponent = {
  init: function () {
    const object3D = this.el.object3D
    object3D.visible = false
    const show = ({detail}) => {
      const {position, rotation, scale} = detail.transform
      object3D.position.copy(position)
      object3D.quaternion.copy(rotation)
      object3D.scale.set(scale, scale, scale)
      object3D.visible = true
    }
    const hide = ({detail}) => { object3D.visible = false }
    this.el.sceneEl.addEventListener('xrfacefound', show)
    this.el.sceneEl.addEventListener('xrfaceupdated', show)
    this.el.sceneEl.addEventListener('xrfacelost', hide)
  }
}

xrfacelost

Description

This event is emitted by xrface when a face is no longer being tracked.

xrfacelost.detail : {id}

Property	Description
id	A numerical id of the face that was lost.

Example:

const faceRigidComponent = {
  init: function () {
    const object3D = this.el.object3D
    object3D.visible = false
    const show = ({detail}) => {
      const {position, rotation, scale} = detail.transform
      object3D.position.copy(position)
      object3D.quaternion.copy(rotation)
      object3D.scale.set(scale, scale, scale)
      object3D.visible = true
    }
    const hide = ({detail}) => { object3D.visible = false }
    this.el.sceneEl.addEventListener('xrfacefound', show)
    this.el.sceneEl.addEventListener('xrfaceupdated', show)
    this.el.sceneEl.addEventListener('xrfacelost', hide)
  }
}

AFrame Event Listeners

This section describes the events that are listened for by the "xrweb" A-Frame component

You can emit these events in your web application to perform various actions:

Event Listener	Description
hidecamerafeed	Hides the camera feed. Tracking does not stop.
recenter	Recenters the camera feed to its origin. If a new origin is provided as an argument, the camera's origin will be reset to that, then it will recenter.
screenshotrequest	Emits a request to the engine to capture a screenshot of the AFrame canvas. The engine will emit a screenshotready event with the JPEG compressed image or screenshoterror if an error has occured.
showcamerafeed	Shows the camera feed.
stopxr	Stop the current XR session. While stopped, the camera feed is stopped and device motion is not tracked.

hidecamerafeed

scene.emit('hidecamerafeed')

Parameters

None

Description

Hides the camera feed. Tracking does not stop.

Example

let scene = this.el.sceneEl
scene.emit('hidecamerafeed')

recenter

scene.emit('recenter', {origin, facing})

Parameters

Parameter	Description
origin: {x, y, z} [Optional]	The location of the new origin.
facing: {w, x, y, z} [Optional]	A quaternion representing direction the camera should face at the origin.

Description

Recenters the camera feed to its origin. If a new origin is provided as an argument, the camera's origin will be reset to that, then it will recenter.

If origin and facing are not provided, camera is reset to origin previously specified by a call to recenter or the last call to updateCameraProjectionMatrix(). Note: with A-Frame, updateCameraProjectionMatrix() initially gets called based on initial camera position in the scene.

Example

let scene = this.el.sceneEl
scene.emit('recenter')

// OR

let scene = this.el.sceneEl
scene.emit('recenter', {
  origin: {x: 1, y: 4, z: 0},
  facing: {w: 0.9856, x:0, y:0.169, z:0}
})

screenshotrequest

scene.emit('screenshotrequest')

Parameters

None

Description

Emits a request to the engine to capture a screenshot of the AFrame canvas. The engine will emit a screenshotready event with the JPEG compressed image or screenshoterror if an error has occured.

Example

const scene = this.el.sceneEl
const photoButton = document.getElementById('photoButton')

// Emit screenshotrequest when user taps
photoButton.addEventListener('click', () => {
  image.src = ""
  scene.emit('screenshotrequest')
})

scene.addEventListener('screenshotready', event => {
  image.src = 'data:image/jpeg;base64,' + event.detail
})

scene.addEventListener('screenshoterror', event => {
  console.log("error")
})

showcamerafeed

scene.emit('showcamerafeed')

Parameters

None

Description

Shows the camera feed.

Example

let scene = this.el.sceneEl
scene.emit('showcamerafeed')

stopxr

scene.emit('stopxr')

Parameters

None

Description

Stop the current XR session. While stopped, the camera feed is stopped and device motion is not tracked.

Example

let scene = this.el.sceneEl
scene.emit('stopxr')

XR8.Babylonjs

Babylon.js (https://www.babylonjs.com/) is a complete JavaScript framework for building 3D games and experiences with HTML5 and WebGL. Combined with 8th Wall Web, you can create powerful Web AR experiences.

Tutorial Video:

• Integrating Babylon.js and 8th Wall Web: https://youtu.be/RhZaebNpaEY

Description

Provides an integration that interfaces with the BabylonJS environment and lifecyle to drive the Babylon.js camera to do virtual overlays.

Functions

Function	Description
xrCameraBehavior	Get a behavior that can be attached to a Babylon camera to run World Tracking and/or Image Targets.
faceCameraBehavior	Get a behavior that can be attached to a Babylon camera to run Face Effects.

XR8.Babylonjs.faceCameraBehavior()

XR8.Babylonjs.faceCameraBehavior(config, faceConfig)

Description

Get a behavior that can be attached to a Babylon camera like so: camera.addBehavior(XR8.Babylonjs.faceCameraBehavior())

Parameters

Parameter	Description
config [Optional]	Configuration parameters to pass to XR8.run()
faceConfig [Optional]	Face configuration parameters to pass to XR8.FaceController

config [Optional] is an object with the following properties:

Property	Type	Default	Description
webgl2 [Optional]	bool	false	If true, use WebGL2 if available, otherwise fallback to WebGL1. If false, always use WebGL1.
ownRunLoop [Optional]	bool	true	If true, XR should use it's own run loop. If false, you will provide your own run loop and be responsible for calling runPreRender and runPostRender yourself [Advanced Users only]
cameraConfig: {direction} [Optional]	object	{direction: XR8.XrConfig.camera().BACK}	Desired camera to use. Supported values for direction are XR8.XrConfig.camera().BACK or XR8.XrConfig.camera().FRONT
glContextConfig [Optional]	WebGLContextAttributes	null	The attributes to configure the WebGL canvas context.
allowedDevices [Optional]	XR8.XrConfig.device()	XR8.XrConfig.device().MOBILE	Specify the class of devices that the pipeline should run on. If the current device is not in that class, running will fail prior prior to opening the camera. If allowedDevices is XR8.XrConfig.device().ANY, always open the camera. Note that world tracking can only be used with XR8.XrConfig.device().MOBILE.

faceConfig [Optional] is an object with the following properties:

Parameter	Description
nearClip [Optional]	The distance from the camera of the near clip plane. By default it will use the Babylon camera.minZ
farClip [Optional]	The distance from the camera of the far clip plane. By default it will use the Babylon camera.maxZ
meshGeometry [Optional]	List that contains which parts of the head geometry are visible. Options are: [XR8.FaceController.MeshGeometry.FACE, XR8.FaceController.MeshGeometry.EYES, XR8.FaceController.MeshGeometry.NOSE,]. The default is [XR8.FaceController.MeshGeometry.FACE]
imageTargets [Optional]	List of names of the image target to detect. Can be modified at runtime. Note: All currently active image targets will be replaced with the ones specified in this list.
leftHandedAxes [Optional]	If true, use left-handed coordinates.
imageTargets [Optional]	If true, flip left and right in the output.

Returns

A Babylon JS behavior that connects the Face Effects engine to the Babylon camera and starts the camera feed and tracking.

Example

const startScene = (canvas) => {
  const engine = new BABYLON.Engine(canvas, true /* antialias */)
  const scene = new BABYLON.Scene(engine)
  scene.useRightHandedSystem = false
  
  const camera = new BABYLON.FreeCamera('camera', new BABYLON.Vector3(0, 0, 0), scene)
  camera.rotation = new BABYLON.Vector3(0, scene.useRightHandedSystem ? Math.PI : 0, 0)
  camera.minZ = 0.0001
  camera.maxZ = 10000

  // Add a light to the scene  
  const directionalLight = 
  new BABYLON.DirectionalLight("DirectionalLight", new BABYLON.Vector3(-5, -10, 7), scene)
  directionalLight.intensity = 0.5
  
  // Mesh logic
  const faceMesh = new BABYLON.Mesh("face", scene);
  const material = new BABYLON.StandardMaterial("boxMaterial", scene)
  material.diffuseColor = new BABYLON.Color3(173 / 255.0, 80 / 255.0, 255 / 255.0)
  faceMesh.material = material
  
  let facePoints = []

  const runConfig = {
    cameraConfig: {XR8.XrConfig.camera().FRONT},
    allowedDevices: XR8.XrConfig.device().ANY,
    verbose: true,
  }

  camera.addBehavior(XR8.Babylonjs.faceCameraBehavior(runConfig)) // Connect camera to XR and show camera feed.

  engine.runRenderLoop(() => {
    scene.render()
  })
}

XR8.Babylonjs.xrCameraBehavior()

XR8.Babylonjs.xrCameraBehavior(config, xrConfig)

Description

Get a behavior that can be attached to a Babylon camera like so: camera.addBehavior(XR8.Babylonjs.xrCameraBehavior())

Parameters

Parameter	Description
config [Optional]	Configuration parameters to pass to XR8.run()
xrConfig [Optional]	Configuration parameters to pass to XR8.XrController

config [Optional] is an object with the following properties:

Property	Type	Default	Description
webgl2 [Optional]	bool	false	If true, use WebGL2 if available, otherwise fallback to WebGL1. If false, always use WebGL1.
ownRunLoop [Optional]	bool	false	If true, XR should use it's own run loop. If false, you will provide your own run loop and be responsible for calling runPreRender and runPostRender yourself [Advanced Users only]
cameraConfig: {direction} [Optional]	object	{direction: XR8.XrConfig.camera().BACK}	Desired camera to use. Supported values for direction are XR8.XrConfig.camera().BACK or XR8.XrConfig.camera().FRONT
glContextConfig [Optional]	WebGLContextAttributes	null	The attributes to configure the WebGL canvas context.
allowedDevices [Optional]	XR8.XrConfig.device()	XR8.XrConfig.device().MOBILE	Specify the class of devices that the pipeline should run on. If the current device is not in that class, running will fail prior prior to opening the camera. If allowedDevices is XR8.XrConfig.device().ANY, always open the camera. Note that world tracking can only be used with XR8.XrConfig.device().MOBILE.

xrConfig [Optional] is an object with the following properties:

Parameter	Description
enableLighting [Optional]	If true, return an estimate of lighting information.
enableWorldPoints [Optional]	If true, return the map points used for tracking.
disableWorldTracking [Optional]	If true, turn off SLAM tracking for efficiency.
imageTargets [Optional]	List of names of the image target to detect. Can be modified at runtime. Note: All currently active image targets will be replaced with the ones specified in this list.
leftHandedAxes [Optional]	If true, use left-handed coordinates.
imageTargets [Optional]	If true, flip left and right in the output.

Returns

A Babylon JS behavior that connects the XR engine to the Babylon camera and starts the camera feed and tracking.

Example

let surface, engine, scene, camera

const startScene = () => {
  const canvas = document.getElementById('renderCanvas')

  engine = new BABYLON.Engine(canvas, true, { stencil: true, preserveDrawingBuffer: true })
  engine.enableOfflineSupport = false

  scene = new BABYLON.Scene(engine)
  camera = new BABYLON.FreeCamera('camera', new BABYLON.Vector3(0, 3, 0), scene)

  initXrScene({ scene, camera }) // Add objects to the scene and set starting camera position.

  // Connect the camera to the XR engine and show camera feed
  camera.addBehavior(XR8.Babylonjs.xrCameraBehavior())

  engine.runRenderLoop(() => {
    scene.render()
  })

  window.addEventListener('resize', () => {
    engine.resize()
  })
}

BabylonJS Observables

Image Target Observables

onXrImageLoadingObservable: Fires when detection image loading begins.

onXrImageLoadingObservable : { imageTargets: {name, type, metadata} }

onXrImageScanningObservable: Fires when all detection images have been loaded and scanning has begun.

onXrImageScanningObservable : { imageTargets: {name, type, metadata, geometry} }

onXrImageFoundObservable: Fires when an image target is first found.

onXrImageFoundObservable : { name, type, position, rotation, scale, scaledWidth, scaledHeight, height, radiusTop, radiusBottom, arcStartRadians, arcLengthRadians }

onXrImageUpdatedObservable: Fires when an image target changes position, rotation or scale.

onXrImageUpdatedObservable : { name, type, position, rotation, scale, scaledWidth, scaledHeight, height, radiusTop, radiusBottom, arcStartRadians, arcLengthRadians }

onXrImageLostObservable: Fires when an image target is no longer being tracked.

onXrImageLostObservable : { name, type, position, rotation, scale, scaledWidth, scaledHeight, height, radiusTop, radiusBottom, arcStartRadians, arcLengthRadians }

Face Effects Observables

onFaceLoadingObservable: Fires when loading begins for additional face AR resources.

onFaceLoadingObservable : {maxDetections, pointsPerDetection, indices, uvs}

onFaceScanningObservable: Fires when all face AR resources have been loaded and scanning has begun.

onFaceScanningObservable: {maxDetections, pointsPerDetection, indices, uvs}

onFaceFoundObservable: Fires when a face is first found.

onFaceFoundObservable : {id, transform, attachmentPoints, vertices, normals}

onFaceUpdatedObservable: Fires when a face is subsequently found.

onFaceUpdatedObservable : {id, transform, attachmentPoints, vertices, normals}

onFaceLostObservable: Fires when a face is no longer being tracked.

onFaceLostObservable : {id}

Image Target Example

scene.onXrImageUpdatedObservable.add(e => {
  target.position.copyFrom(e.position)
  target.rotationQuaternion.copyFrom(e.rotation)
  target.scaling.set(e.scale, e.scale, e.scale)
})

Face Effects Example

// this is called when the face is first found.  It provides the static information about the
// face such as the UVs and indices
scene.onFaceLoadingObservable.add((event) => {
  const {indices, maxDetections, pointsPerDetection, uvs} = event

  // Babylon expects all vertex data to be a flat list of numbers
  facePoints = Array(pointsPerDetection)
  for (let i = 0; i < pointsPerDetection; i++) {
    const facePoint = BABYLON.MeshBuilder.CreateBox("box", {size: 0.02}, scene)
    facePoint.material = material
    facePoint.parent = faceMesh
    facePoints[i] = facePoint
  }
})

// this is called each time the face is updated which is on a per-frame basis
scene.onFaceUpdatedObservable.add((event) => {
  const {vertices, normals, transform} = event;
  const {scale, position, rotation} = transform
  
  vertices.map((v, i) => {
    facePoints[i].position.x = v.x
    facePoints[i].position.y = v.y
    facePoints[i].position.z = v.z
  })

  faceMesh.scalingDeterminant = scale
  faceMesh.position = position
  faceMesh.rotationQuaternion = rotation
})

CameraPipelineModule

8th Wall camera applications are built using a camera pipeline module framework. Applications install modules which then control the behavior of the application at runtime.

Refer to XR8.addCameraPipelineModule() for details on adding camera pipeline modules to your application.

A camera pipeline module object must have a .name string which is unique within the application. It should implement one or more of the following camera lifecycle methods. These methods will be executed at the appropriate point in the run loop.

During the main runtime of an application, each camera frame goes through the following cycle:

onBeforeRun -> onCameraStatusChange (requesting -> hasStream -> hasVideo | failed) -> onStart -> onAttach -> onProcessGpu -> onProcessCpu -> onUpdate -> onRender

Camera modules should implement one or more of the following camera lifecycle methods:

Function	Description
onAppResourcesLoaded	Called when we have received the resources attached to an app from the server.
onAttach	Called before the first time a module receives frame updates. It is called on modules that were added either before or after the pipeline is running.
onBeforeRun	Called immediately after XR8.run(). If any promises are returned, XR will wait on all promises before continuing.
onCameraStatusChange	Called when a change occurs during the camera permissions request.
onCanvasSizeChange	Called when the canvas changes size.
onDetach	is called after the last time a module receives frame updates. This is either after the engine is stopped or the module is manually removed from the pipeline, whichever comes first.
onDeviceOrientationChange	Called when the device changes landscape/portrait orientation.
onException	Called when an error occurs in XR. Called with the error object.
onPaused	Called when XR8.pause() is called.
onProcessCpu	Called to read results of GPU processing and return usable data.
onProcessGpu	Called to start GPU processing.
onRemove	is called when a module is removed from the pipeline.
onRender	Called after onUpdate. This is the time for the rendering engine to issue any WebGL drawing commands. If an application is providing its own run loop and is relying on XR8.runPreRender() and XR8.runPostRender(), this method is not called and all rendering must be coordinated by the external run loop.
onResume	Called when XR8.resume() is called.
onStart	Called when XR starts. First callback after XR8.run() is called.
onUpdate	Called to update the scene before render. Data returned by modules in onProcessGpu and onProcessCpu will be present as processGpu.modulename and processCpu.modulename where the name is given by module.name = "modulename".
onVideoSizeChange	Called when the canvas changes size.
requiredPermissions	Modules can indicate what browser capabilities they require that may need permissions requests. These can be used by the framework to request appropriate permissions if absent, or to create components that request the appropriate permissions before running XR.

Note: Camera modules that implement onProcessGpu or onProcessCpu can provide data to subsequent stages of the pipeline. This is done by the module's name.

onAppResourcesLoaded()

onAppResourcesLoaded: ({ framework, imageTargets, version })

Description

Called when we have received the resources attached to an app from the server.

Parameters

Parameter	Description
framework	The framework bindings for this module for dispatching events.
imageTargets [Optional]	An array of image targets with the fields {imagePath, metadata, name}
version	The engine version, e.g. 14.0.8.949

Example

XR8.addCameraPipelineModule({
  name = 'myPipelineModule',
  onAppResourcesLoaded = ({ framework, version, imageTargets }) => {
    //...
  },
})

onAttach()

onAttach: ({framework, canvas, GLctx, computeCtx, isWebgl2, orientation, videoWidth, videoHeight, canvasWidth, canvasHeight, status, stream, video, version, imageTargets, config})

Description

onAttach() is called before the first time a module receives frame updates. It is called on modules that were added either before or after the pipeline is running. It includes all the most recent data available from:

• onStart
• onDeviceOrientationChange
• onCanvasSizeChange
• onVideoSizeChange
• onCameraStatusChange
• onAppResourcesLoaded

Parameters

Parameter	Description
framework	The framework bindings for this module for dispatching events.
canvas	The canvas that backs GPU processing and user display.
GLctx	The drawing canvas's WebGLRenderingContext or WebGL2RenderingContext.
computeCtx	The compute canvas's WebGLRenderingContext or WebGL2RenderingContext.
isWebgl2	True if GLCtx is a WebGL2RenderingContext.
orientation	The rotation of the ui from portrait, in degrees (-90, 0, 90, 180).
videoWidth	The height of the camera feed, in pixels.
videoHeight	The height of the camera feed, in pixels.
canvasWidth	The width of the GLctx canvas, in pixels.
canvasHeight	The height of the GLctx canvas, in pixels.
status	One of [ 'requesting', 'hasStream', 'hasVideo', 'failed' ]
stream	The MediaStream associated with the camera feed.
video	The video dom element displaying the stream.
version [Optional]	The engine version, e.g. 14.0.8.949, if app resources are loaded.
imageTargets [Optional]	An array of image targets with the fields {imagePath, metadata, name}
config	The configuration parameters that were passed to XR8.run().

onBeforeRun()

onBeforeRun: ({ config })

Description

onBeforeRun is called immediately after XR8.run(). If any promises are returned, XR will wait on all promises before continuing.

Parameters

Parameter	Description
config	The configuration parameters that were passed to XR8.run().

onCameraStatusChange()

onCameraStatusChange: ({ status, stream, video, config })

Description

Called when a change occurs during the camera permissions request.

Called with the status, and, if applicable, a reference to the newly available data. The typical status flow will be:

requesting -> hasStream -> hasVideo.

Parameters

Parameter	Description
status	One of [ 'requesting', 'hasStream', 'hasVideo', 'failed' ]
stream: [Optional]	The MediaStream associated with the camera feed, if status is hasStream.
video: [Optional]	The video DOM element displaying the stream, if status is hasVideo.
config	The configuration parameters that were passed to XR8.run(), if status is "requesting".

The status parameter has the following states:

State	Description
requesting	In 'requesting', the browser is opening the camera, and if applicable, checking the user permissons. In this state, it is appropriate to display a prompt to the user to accept camera permissions.
hasStream	Once the user permissions are granted and the camera is successfully opened, the status switches to 'hasStream' and any user prompts regarding permissions can be dismissed.
hasVideo	Once camera frame data starts to be available for processing, the status switches to 'hasVideo', and the camera feed can begin displaying.
failed	If the camera feed fails to open, the status is 'failed'. In this case it's possible that the user has denied permissions, and so helping them to re-enable permissions is advisable.

Example

XR8.addCameraPipelineModule({
  name = 'camerastartupmodule',
  onCameraStatusChange = ({status}) => {
    if (status == 'requesting') {
      myApplication.showCameraPermissionsPrompt()
    } else if (status == 'hasStream') {
      myApplication.dismissCameraPermissionsPrompt()
    } else if (status == 'hasVideo') {
      myApplication.startMainApplictation()
    } else if (status == 'failed') {
      myApplication.promptUserToChangeBrowserSettings()
    }
  },
})

onCanvasSizeChange()

onCanvasSizeChange: ({ GLctx, computeCtx, videoWidth, videoHeight, canvasWidth, canvasHeight })

Description

Called when the canvas changes size. Called with dimensions of video and canvas.

Parameters

Parameter	Description
GLctx	The drawing canvas's WebGLRenderingContext or WebGL2RenderingContext.
computeCtx	The compute canvas's WebGLRenderingContext or WebGL2RenderingContext.
videoWidth	The width of the camera feed, in pixels.
videoHeight	The height of the camera feed, in pixels.
canvasWidth	The width of the GLctx canvas, in pixels.
canvasHeight	The height of the GLctx canvas, in pixels.

Example

XR8.addCameraPipelineModule({
  name: 'mycamerapipelinemodule',
  onCanvasSizeChange: ({ GLctx, videoWidth, videoHeight, canvasWidth, canvasHeight }) => {
    myHandleResize({ GLctx, videoWidth, videoHeight, canvasWidth, canvasHeight })
  },
})

onDetach()

onDetach: ({framework})

Description

onDetach is called after the last time a module receives frame updates. This is either after the engine is stopped or the module is manually removed from the pipeline, whichever comes first.

Parameters

Parameter	Description
framework	The framework bindings for this module for dispatching events.

onDeviceOrientationChange()

onDeviceOrientationChange: ({ GLctx, computeCtx, videoWidth, videoHeight, orientation })

Description

Called when the device changes landscape/portrait orientation.

Parameters

Parameter	Description
GLctx	The drawing canvas's WebGLRenderingContext or WebGL2RenderingContext.
computeCtx	The compute canvas's WebGLRenderingContext or WebGL2RenderingContext.
videoWidth	The width of the camera feed, in pixels.
videoHeight	The height of the camera feed, in pixels.
orientation	The rotation of the ui from portrait, in degrees (-90, 0, 90, 180).

Example

XR8.addCameraPipelineModule({
  name: 'mycamerapipelinemodule',
  onDeviceOrientationChange: ({ GLctx, videoWidth, videoHeight, orientation }) => {
    // handleResize({ GLctx, videoWidth, videoHeight, orientation })
  },
})

onException()

onException: (error)

Description

Called when an error occurs in XR. Called with the error object.

Parameters

Parameter	Description
error	The error object that was thrown

Example

XR8.addCameraPipelineModule({
  name: 'mycamerapipelinemodule',
    onException : (error) => {
      console.error('XR threw an exception', error)
  },
})

onPaused()

onPaused: ()

Description

Called when XR8.pause() is called.

Parameters

None

Example

XR8.addCameraPipelineModule({
  name: 'mycamerapipelinemodule',
  onPaused: () => {
    console.log('pausing application')
  },
})

onProcessGpu()

onProcessGpu: ({ framework, frameStartResult })

Description

Called to start GPU processing

Parameters

Parameter	Description
framework	{ dispatchEvent(eventName, detail) } : Emits a named event with the supplied detail.
frameStartResult	{ cameraTexture, computeTexture, GLctx, computeCtx, textureWidth, textureHeight, orientation, videoTime, repeatFrame }

The frameStartResult parameter has the following properties:

Property	Description
cameraTexture	The drawing canvas's WebGLTexture containing camera feed data.
computeTexture	The compute canvas's WebGLTexture containing camera feed data.
GLctx	The drawing canvas's WebGLRenderingContext or WebGL2RenderingContext.
computeCtx	The compute canvas's WebGLRenderingContext or WebGL2RenderingContext.
textureWidth	The width (in pixels) of the camera feed texture.
textureHeight	The height (in pixels) of the camera feed texture.
orientation	The rotation of the ui from portrait, in degrees (-90, 0, 90, 180).
videoTime	The timestamp of this video frame.
repeatFrame	True if the camera feed has not updated since the last call.

Returns

Any data that you wish to provide to onProcessCpu and onUpdate should be returned. It will be provided to those methods as processGpuResult.modulename

Example

XR8.addCameraPipelineModule({
  name: 'mycamerapipelinemodule',
  onProcessGpu: ({frameStartResult}) => {
    const {cameraTexture, GLctx, textureWidth, textureHeight} = frameStartResult

    if(!cameraTexture.name){
      console.error("[index] Camera texture does not have a name")
    }

    const restoreParams = XR8.GlTextureRenderer.getGLctxParameters(GLctx, [GLctx.TEXTURE0])
    // Do relevant GPU processing here
    ...
    XR8.GlTextureRenderer.setGLctxParameters(GLctx, restoreParams)

    // These fields will be provided to onProcessCpu and onUpdate
    return {gpuDataA, gpuDataB}
  },
})

onProcessCpu()

onProcessCpu: ({ framework, frameStartResult, processGpuResult })

Description

Called to read results of GPU processing and return usable data. Called with { frameStartResult, processGpuResult }. Data returned by modules in onProcessGpu will be present as processGpu.modulename where the name is given by module.name = "modulename".

Parameter	Description
framework	The framework bindings for this module for dispatching events.
frameStartResult	The data that was provided at the beginning of a frame.
processGpuResult	Data returned by all installed modules during onProcessGpu.

Returns

Any data that you wish to provide to onUpdate should be returned. It will be provided to that method as processCpuResult.modulename

Example

XR8.addCameraPipelineModule({
  name: 'mycamerapipelinemodule',
  onProcessCpu: ({ frameStartResult, processGpuResult }) => {
    const GLctx = frameStartResult.GLctx
    const { cameraTexture } = frameStartResult
    const { camerapixelarray, mycamerapipelinemodule } = processGpuResult

    // Do something interesting with mycamerapipelinemodule.gpuDataA and mycamerapipelinemodule.gpuDataB
    ...
    
    // These fields will be provided to onUpdate
    return {cpuDataA, cpuDataB}
  },
})