---
description: Construction of an AR experience using SLAM
---

# Build a Basic Surface Tracking Experience

{% content-ref url="https://app.gitbook.com/o/QMsd5hT6sxA9FBIB03yh/s/3UKy7VHRJWrNarYaMp13/" %}
[Blippar Documentation Centre](https://app.gitbook.com/o/QMsd5hT6sxA9FBIB03yh/s/3UKy7VHRJWrNarYaMp13/)
{% endcontent-ref %}

## Introduction

This guide walks you through the construction of a basic scene built using A-Frame and the WebAR SDK. The output will be a 3D Astronaut model fixed to the identified surface ([see here](#h_01fgv39p8vf50z5y4hrm28ybv6))

To simply display 3D models no knowledge of A-Frame beyond what's outlined below is necessary. However if you want to make more advanced experiences, familiarity with A-Frame will be very helpful. You can find out more about A-Frame in their[ ](https://aframe.io/docs/1.2.0/introduction/)[excellent documentation.](https://aframe.io/docs/1.2.0/introduction/)

## Process

Complete the below mentioned steps to create and launch an AR experience using Blippar WebAR SDK and A-frame integration

## **Step:1 Create an HTML File & Include the WebAR SDK** <a href="#h_01ffspkxcab3c1w6n1jena8cxe" id="h_01ffspkxcab3c1w6n1jena8cxe"></a>

* Create a HTML document in your favourite editor.
* Include AFrame Script before WebAR SDK.
* To include the **WebAR SDK** in this, we drop in a **\<script>** tag under the **\<head>** tag pointing to the WebAR SDK.
* The exact form of the below will look different depending on how you installed the WebAR SDK. The example which follows assumes you downloaded the WebAR SDK and extracted it so that the script file - <mark style="color:blue;">webar-sdk.min.js</mark> and libs folder is in the same location as your HTML file. Follow the instructions in the[ ](https://patrickttest.gitbook.io/webar-sdk/-MkrnSkYFVhXKBdyZ3pk/introduction/signup-and-download#install)[Install section ](../../getting-started/installing-webar-sdk)to find the right tag for your setup.
* Also a models folder containing a test GLB model file is assumed to be in the same location as your HTML file. To begin with this example, use this GLB model in [this link](https://webar-sdk.blippar.com/static/models/astronaut.glb) for testing.
* The final folder structure should look like this:

<figure><img src="https://content.gitbook.com/content/gB7n9g4VahmV5cBj9PpR/blobs/80bWKxMlKF5XNNdPHCaJ/Screenshot%202023-03-02%20at%202.16.13%20PM.png" alt=""><figcaption><p>Folder Structure</p></figcaption></figure>

```html
<html>
  <head>
    <title>WebAR SDK Basic Scene</title>
    <script src="https://aframe.io/releases/1.3.0/aframe.min.js"></script>
    <script src="./webar-sdk.min.js"></script>
  </head>

  <body>
  </body>
</html>
```

{% hint style="info" %}
* From Webar SDK v1.1.0-beta and above, A-frame script has to be included separately
* Supports A-frame version 1.3.0
{% endhint %}

## **Step 2: Create a WebAR Scene**

* The **webar-scene** is the WebAR version of A-Frame's[ ](https://aframe.io/docs/1.2.0/core/scene.html#sidebar)[scene](https://aframe.io/docs/1.2.0/core/scene.html#sidebar) entity, and functions in much the same way.
* To turn a normal scene entity into a WebAR Scene we add an A-Frame **\<a-scene>** and add a few specific components.
* Most importantly we add the **webar-scene** component and set the **key:** property to the license key you got when you created the project (see[ here ](../../getting-started/installing-webar-sdk)for instructions)
* The other components will just make sure everything is setup correctly.

{% hint style="danger" %}
Remember to change the key value or you will receive an "invalid key" error when you deploy.
{% endhint %}

```html
...

<body>

  <a-scene
    webar-scene="key: xxxxxxxx-1111-2222-3333-yyyyyyyyyyyy"
    vr-mode-ui="enabled: false"
    device-orientation-permission-ui="enabled: false"
    loading-screen="enabled: false">
  </a-scene>
</body>
```

## **Step 3: Add a WebAR Camera** <a href="#h_01ffspmfpksf98zc7zpn54g48s" id="h_01ffspmfpksf98zc7zpn54g48s"></a>

* The <mark style="color:red;">webar-camera</mark> is, like the <mark style="color:red;">webar-scene</mark>, the WebAR version of A-Frame's[ ](https://aframe.io/docs/1.2.0/primitives/a-camera.html#sidebar)[camera](https://aframe.io/docs/1.2.0/primitives/a-camera.html#sidebar) entity
* Within the <mark style="color:orange;">\<a-scene></mark> entity add an A-Frame <mark style="color:orange;">\<a-camera></mark> entity and give it a <mark style="color:red;">webar-camera</mark> component.

```html
<body>
  ...

    <a-camera webar-camera></a-camera>

  </a-scene>
</body>
```

## **Step 4: Load your 3D Assets** <a href="#h_01ffspmfpksf98zc7zpn54g48s" id="h_01ffspmfpksf98zc7zpn54g48s"></a>

* To ensure the models are fully loaded before the experience starts so we provide the best user experience, we use A-Frame's[ Asset Management System](https://aframe.io/docs/1.2.0/core/asset-management-system.html) ​
* Add an <mark style="color:orange;">\<a-assets></mark> entity and load any model files to be used as <mark style="color:orange;">\<a-asset-item></mark> entities. Included with the downloaded WebAR SDK is a model of an astronaut to use as an example.

```html
<a-scene 
    ... 
    ...>

    <a-assets>    
      <a-asset-item
        id="astronaut"
        src="models/astronaut.glb">
      </a-asset-item>
​    </a-assets>

​  </a-scene> 
```

## **Step 5: Add a WebAR Stage** <a href="#h_01ffspmref6tagtgaaq92svyb5" id="h_01ffspmref6tagtgaaq92svyb5"></a>

* Next we add a <mark style="color:red;">webar-stage</mark> entity, this will be the parent to all the 3D models and represents the tracked surface. Any models placed onto the <mark style="color:red;">webar-stage</mark> will be displayed on the tracked surface. This is where all the action happens.
* Within the <mark style="color:orange;">\<a-scene></mark> entity add an A-Frame <mark style="color:orange;">\<a-entity></mark> entity and give it a <mark style="color:red;">webar-stage</mark> component:
* A 3D model placed under a webAR stage will be displayed on a detected surface.

```html
<body>
   
   ...

    <a-entity webar-stage>
       <!-- Optionally, proceed to the next step to enhance UX with interactive features -->
       <!-- Or, skip the next optional step and proceed to the subsequent one to place your 3D AR models here -->
    </a-entity>

  </a-scene>
</body>
```

## **Step 6 : Integrate Enhanced UX with Stage Cursor, Rotation, and Scaling** <a href="#h_01ffspmref6tagtgaaq92svyb5" id="h_01ffspmref6tagtgaaq92svyb5"></a>

This step is **mandatory** to ensure a fully interactive AR experience. Integrate a cursor to allow users to place the AR model precisely by tapping on the screen. This step also introduces gesture-based interactions such as rotation and scaling, making the scene more engaging. This involves using the <mark style="color:orange;">`webar-ux-control`</mark> component, which should be a child of the <mark style="color:orange;">`webar-stage`</mark> entity.

* **Add the** <mark style="color:orange;">`webar-ux-control`</mark> **entity**: Insert an <mark style="color:orange;">`<a-entity>`</mark> with the <mark style="color:orange;">`webar-ux-control`</mark> component as a child of <mark style="color:orange;">`<a-entity webar-stage>`</mark>. Set <mark style="color:blue;">`stageCursorUX: true`</mark> to enable the stage cursor, and use <mark style="color:blue;">`userGestureRotation: true`</mark> and <mark style="color:blue;">`userGestureScale: true`</mark> to allow users to rotate the model by swiping and scale the model by pinching.

```html
<body>
   
   ...

    <a-entity webar-stage>
       <a-entity webar-ux-control="stageCursorUX: true; userGestureRotation: true; userGestureScale: true">
       <!-- Read the next step to place 3D AR models here -->
       </a-entity>
    </a-entity>

  </a-scene>
</body>
```

* **Understanding the Stage Cursor**: With <mark style="color:blue;">`stageCursorUX: true`</mark>, a visual cursor appears on the identified surface within the AR scene. Users can tap the screen to place the 3D model at the cursor's location, providing an intuitive way to control where the model appears in the physical environment. Conversely, setting <mark style="color:red;">`stageCursorUX: false`</mark> will hide the cursor, disabling this placement feature
* **Integrate Gesture-Based Interaction**: As with the `userGestureRotation` and `userGestureScale` attributes, users can interact with the model by rotating it with a swipe or scaling it with a pinch gesture, offering a more interactive AR experience.

## **Step 7: Add a 3D Model** <a href="#h_01ffspmz7kbr039sr842ngd532" id="h_01ffspmz7kbr039sr842ngd532"></a>

* To the <mark style="color:red;">webar-stage</mark> we add our preloaded model.
* Specify the glb model files to be loaded in A-Frame’s <mark style="color:orange;">\<a-assets>\<a-asset-item></mark> tag. For more details, please refer to A-FRame’s [Asset Management System](https://aframe.io/docs/1.2.0/core/asset-management-system.html) document.
* Add the 3d model asset <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">gltf-model</mark>=”<mark style="color:blue;">#astronaut”</mark>> under the parent <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-stage</mark><mark style="color:orange;">></mark> <mark style="color:blue;">element</mark>.
* Also add the <mark style="color:red;">webar-loadmonitor</mark> attribute to the entities to display the loading progress screen before starting the surface tracking. See the <mark style="color:red;">webar-loadmonitor</mark> properties table for more details.

```html
<body>

  ...

    <a-assets>
      <a-asset-item
        id="astronaut"
        src="models/astronaut.glb">
      </a-asset-item>
    </a-assets>

    <a-entity webar-stage>
        <!-- Place 3D AR models here -->
        <a-entity gltf-model="#astronaut" id="astronaut_1" 
                  rotation="0 0 0" position="0 0 0" scale="0.25 0.25 0.25"
                  webar-loadmonitor="elType: glb"></a-entity>
    </a-entity>

  </a-scene>
</body>
```

## **Full Source Code** <a href="#h_01ffspn81p2sbwwsrazawp12ce" id="h_01ffspn81p2sbwwsrazawp12ce"></a>

In case we lost you along the way, here is the whole thing:

```html
<!DOCTYPE html>
<html>
<head>
  <title>Blippar Web Surface Tracking</title>
  <script src="https://aframe.io/releases/1.3.0/aframe.min.js"></script>
  <script src="./webar-sdk.min.js"></script>
</head>

  <body>
   <a-scene
      webar-scene="key: xxxxxxxx-1111-2222-3333-yyyyyyyyyyyy"
      vr-mode-ui="enabled: false"
      device-orientation-permission-ui="enabled: false"
      loading-screen="enabled: false">

      <a-camera webar-camera></a-camera>

      <a-assets>
        <a-asset-item
          id="astronaut"
          src="models/astronaut.glb">
        </a-asset-item>
      </a-assets>

      <a-entity webar-stage>
        <!-- Place 3D AR models here -->
        <a-entity gltf-model="#astronaut" id="astronaut_1" 
                  rotation="0 0 0" position="0 0 0" scale="0.25 0.25 0.25"
                  webar-loadmonitor="elType: glb"></a-entity>
      </a-entity>
    </a-scene>
  </body>
</html>
```

## **Deployment** <a href="#h_01ffsda5d7s1k3gpayx3jdz4ds" id="h_01ffsda5d7s1k3gpayx3jdz4ds"></a>

Deploy your files (the HTML file and if you downloaded the SDK the blippar folder) to your web server, (note you can also develop and host locally in Dev Mode, see more info here [Develop Locally.](../../publish-your-creation/develop-locally))

{% hint style="danger" %}
Your website **must have https** **enabled,** this is to enable the browser to access your camera.
{% endhint %}

{% hint style="info" %}
Launching the Experience

Navigate to your page, the WebAR SDK should work with any modern browser but is extensively tested with Safari (iOS) and Chrome (android). If all has gone well you will see the below. Information about launching the AR experience is available[ ](https://patrickttest.gitbook.io/webar-sdk/-MkrnSkYFVhXKBdyZ3pk/introduction/launching-a-webar-experience)[here.](../../publish-your-creation/launch-the-experience)
{% endhint %}

## **Resulting Surface Tracking Experience** <a href="#h_01fgv39p8vf50z5y4hrm28ybv6" id="h_01fgv39p8vf50z5y4hrm28ybv6"></a>

<div data-full-width="false"><figure><img src="https://888555036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgB7n9g4VahmV5cBj9PpR%2Fuploads%2F3k9hewoWXFfPrqpyiyao%2Ftrex_blippar-min.gif?alt=media&#x26;token=d70aa126-23e0-47c8-b1ee-335170e5ea81" alt="Surface Tracking Experience" width="240"><figcaption><p>Surface Tracking Experience</p></figcaption></figure></div>
