npm package: @metalitix/metalitix-threejs
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-Threejs 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-threejs
```

## Usage

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

---

1. If not already done so, create a ThreeJS project.

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

3. Run `npm install @metalitix/metalitix-threejs` to install the Metalitix-ThreeJS 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 your camera ([`PerspectiveCamera`](https://threejs.org/docs/#api/en/cameras/PerspectiveCamera)) and your scene ([`Object3D`](https://threejs.org/docs/#api/en/core/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.

   ```javascript
   import MetalitixLogger from '@metalitix/metalitix-threejs';
   ...
   const apiKey = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
   const logger = new MetalitixLogger(apiKey);
   ...
   const camera = new THREE.PerspectiveCamera();
   const myScene = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial());
   logger.startSession(camera, myScene);
   ```

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/v/three.js/advanced-features).