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. It includes:
File | Description |
| Loads the Smart Pixel asynchronously and controls debug mode. (enable/disable). |
| Debug version for testing and development. |
| Minified version for production environments. |
Save both
smart-pixel.debug.jsandsmart-pixel.min.jsin the same directory on your server.
2 Integration for Browser Environments
Use one of the following options depending on your setup:
<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><head>
<script>
window.loaderConfig_ = {
trackId: '[TRACK_ID]',
domain: '[TRACK_DOMAIN]',
};
</script>
<script async src="/js/loader.min.js"></script>
</head>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:
npm i @webtrekk-smart-pixel/coreYou need to simulate a browser-like environment by providing window and document. Also, enable debug mode during development by setting the environment variable:
NODE_ENV=developmentExample usage:
var webtrekkSmartPixel = require('@webtrekk-smart-pixel/core');
var wtSmart = webtrekkSmartPixel.use(window, window.document);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:
requirejs(['wtSmart'], function(wtSmart) {
window.wtSmart = window.wtSmart ? window.wtSmart : wtSmart.use(window, window.document);
});Note
The Smart Pixel library must be available as a RequireJS-compatible module in your project structure.