npm package: @metalitix/metalitix-aframe
Description: Metalitix™ is a powerful platform-agnostic software providing comprehensive 3D and immersive environment analytics, offering visualization tools, cross-platform compatibility, data security, and insights to optimize user experiences in the Metaverse.
Latest version: 1.4.1

# Metalitix-Aframe Logger

Metalitix™ is a powerful platform-agnostic software providing comprehensive 3D and immersive environment analytics, offering visualization tools, cross-platform compatibility, data security, and insights to optimize user experiences in the Metaverse. Compatible with popular 3D engines like Three.js, AFrame, Decentraland, 8th Wall, Unity, and Unreal Engine, it provides a suite of data collection and visualization tools for XR and 3D experiences.

## Install

```sh
npm install @metalitix/metalitix-aframe
```

## Usage

> [Click here for an example project on Github.](https://github.com/Metalitix/metalitix-aframe-example)

---

1. If not already done so, create an AFrame project.

2. Create an account and project on [Metalitix](https://app.metalitix.com/). Follow our [Getting Started](https://docs.metalitix.com/getting-started) guide to upload a model and whitelist your domains.

3. Run `npm install @metalitix/metalitix-aframe` to install the Metalitix-Aframe Logger.

4. Instantiate the `MetalitixLogger` by passing in the `apiKey` from your project settings found in the [Metalitix dashboard](https://app.metalitix.com/). Then, start the logger session by calling `startSession()` and passing in the A-Frame scene ([`a-scene`](https://aframe.io/docs/1.4.1/core/scene.html)) and your own scene ([`a-entity`](https://aframe.io/docs/1.4.1/core/entity.html) or [`Object3D`](https://aframe.io/docs/1.4.1/core/entity.html#object3d)). Your own scene is the 3D model of the experience or the parent for your scene's models.

    > The camera and your scene object should not be parents or children of each other. 

    > Metalitix will record camera movement relative to your scene object's transformations. So, it is not necessary to manually calibrate the scene in the [Metalitix dashboard](https://app.metalitix.com/). If you do not pass a scene object, then recorded camera movement will be in world coordinates and manual calibration may be necessary.

   ```html
   <a-scene id="aframe-scene">
     <a-entity id="my-scene"></a-entity>
     <!-- This is the scene model or the parent for the scene's models. -->
   </a-scene>
   ...
   <script>
     import MetalitixLogger from '@metalitix/metalitix-aframe';
     ...
     const apiKey = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
     const logger = new MetalitixLogger(apiKey);
     ...
     const aframeScene = document.getElementById('aframe-scene');
     const myScene = document.getElementById('my-scene');
     logger.startSession(aframeScene, myScene);
   </script>
   ```

5. **Metalitix is now configured to gather analytics on your project!** To test, engage with your experience to create a session. Then, navigate to the *Sessions* tab within your project on the [Metalitix dashboard](https://app.metalitix.com/). Within a few minutes, you will see your session appear at the top of the table. It will be marked as *Active* until the session ends. When a session no longer says *Active*, its data will appear on the *Metrics* tab. Heatmap data, on the other hand, is calculated in real-time for small projects and every 24 hours for large projects.

## Full API List

To learn more about the spatial analytics that Metalitix can collect, please make an account on [Metalitix](https://app.metalitix.com/) to gain access to our [Full API List](https://docs.metalitix.com/advanced-features).