---
title: "Installation"
slug: "download-and-integration"
updated: 2025-07-24T12:43:20Z
published: 2025-07-24T12:43:20Z
canonical: "docs.mapp.com/download-and-integration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

The Smart Pixel can be used in various environments. This guide explains how to install and integrate the pixel using two main approaches: via CDN (recommended) or via manual file download. It also provides options for more advanced JavaScript setups such as npm and RequireJS.

---

## 1 Installation Options

There are two ways to integrate the Smart Pixel:

- **Load it via CDN** *(recommended)*
- **Download the files from GitHub and host them yourself**

**Comparison: CDN vs. GitHub Download**

| **Aspect** | **CDN (Recommended)** | **GitHub Download** |
| --- | --- | --- |
| **Update Management** | Always up-to-date, auto-updated | Manual updates required |
| **Maintenance Effort** | Minimal | Higher – files must be hosted and maintained |
| **Track Domain Usage** | Can be served via custom tracking domain | Custom domain possible, but setup required |
| **Data Quality & Ad Blockers** | Higher, especially with custom domain | Lower – more likely to be blocked |
| **Version Control** | Always uses latest version | You control the exact version used |
| **Compliance Requirements** | May not meet strict enterprise/security requirements | Suitable for environments requiring static files |

---

### 1.1 Use via CDN

The easiest and most robust way to use the Smart Pixel is via CDN. This ensures you always use the latest version without any manual updates.

---

### 1.2 Download from GitHub

If you prefer to host the files yourself, you can download the Smart Pixel package from [GitHub](https://github.com/Webtrekk/Webtrekk-Smart-Pixel/releases). It includes:

| **File** | **Description** |
| --- | --- |
| `loader.min.js` | Loads the Smart Pixel asynchronously and controls debug mode. (enable/disable). |
| `smart-pixel.debug.js` | Debug version for testing and development. |
| `smart-pixel.min.js` | Minified version for production environments. |

> [!NOTE]
> Save both `smart-pixel.debug.js` and `smart-pixel.min.js` in the same directory on your server.

---

## 2 Integration for Browser Environments

Use one of the following options depending on your setup:

CDN Integration (Recommended)Self-hosted (GitHub Download)

```xml
<head>
  <script>
    window.loaderConfig_ = {
      trackId: '[TRACK_ID]',
      domain: '[TRACK_DOMAIN]',
    };
  </script>
  <script async src="https://[TRACK_DOMAIN]/js/latest/smart-pixel.min.js"></script>
</head>
```

```xml
<head>
  <script>
    window.loaderConfig_ = {
      trackId: '[TRACK_ID]',
      domain: '[TRACK_DOMAIN]',
    };
  </script>
  <script async src="/js/loader.min.js"></script>
</head>
```

> [!WARNING]
> Note
> 
> Always define the `loaderConfig_` object before including the loader script. This configuration tells the loader where to find the pixel file and how to initialize it.

The configuration object loaderConfig_ must include at least the following properties:

- **trackId:** Your unique Track ID, identifying your Mapp dataset.
- **domain:** The Track Domain: through which requests are sent (e.g., track.webtrekk.net or a custom domain like track.example.com).

---

## 3 Advanced Integration (JavaScript Environments)

The following methods are intended for developers who work with JavaScript-based applications, such as Single Page Applications (SPAs) or modular frontend projects. These approaches allow the Smart Pixel to be integrated via JavaScript modules instead of HTML-based scripts.

### 3.1 Installation via npm (Node.js Projects)

If you’re working in a Node.js-based frontend setup (e.g. using Webpack, Vite or similar), you can install the Smart Pixel package via npm:

```bash
npm i @webtrekk-smart-pixel/core
```

You need to simulate a browser-like environment by providing `window` and `document`. Also, enable debug mode during development by setting the environment variable:

```bash
NODE_ENV=development
```

Example usage:

```bash
var webtrekkSmartPixel = require('@webtrekk-smart-pixel/core');
var wtSmart = webtrekkSmartPixel.use(window, window.document);
```

> [!NOTE]
> Note
> 
> This setup assumes you manage script loading and initialization in your application’s codebase.

### 3.2 Integration with RequireJS

If your project uses RequireJS (an older JavaScript module loader), you can integrate the Smart Pixel as follows:

```javascript
requirejs(['wtSmart'], function(wtSmart) {
    window.wtSmart = window.wtSmart ? window.wtSmart : wtSmart.use(window, window.document);
});
```

> [!NOTE]
> Note
> 
> The Smart Pixel library must be available as a RequireJS-compatible module in your project structure.

Track IDs are used to assign requests to an account. You find the track ID under *Mapp Q3 >**Configuration > System Configuration > Data Collection.* If the same information is to be recorded for multiple accounts, you can enter the corresponding Track IDs of the accounts comma-separated.

Specify your Mapp Intelligence track domain. This information is provided by your account manager.