Integration Overview

The Betterlytics tracking script collects pageviews out of the box, with no configuration needed. Everything else is opt-in: each capability is enabled with an attribute on the script tag, or an option in the @betterlytics/tracker npm package. You only load what you use, so the script stays lightweight.

Haven’t installed the script yet? Start with the Cloud Quick Start, or Self-Hosting Setup if you run your own instance.

Capabilities

Capability	Enable with	Guide
Custom events	`betterlytics.event()`	Custom Events
Global properties	`data-global-properties` or `setGlobalProperties()`	Global Properties
Dynamic URL normalization	`data-dynamic-urls`	Dynamic URLs
Outbound link tracking	`data-outbound-links`	Outbound Links
Core Web Vitals	`data-web-vitals`	Web Vitals
Error tracking	`data-track-errors`	Error Tracking
Session replay	`data-replay`	Session Replay

Self-hosting? Everything on this page works on a self-hosted instance once the script loads from your instance and sends events to it, see Tracking Scripts. New capabilities land on Cloud first and reach the self-hosted image with its periodic updates. The cloud vs self-hosted comparison shows the current status.

A Complete Example

A script tag with outbound links, Web Vitals, error tracking, and dynamic URL normalization enabled looks like this:


<script
  async
  src="https://betterlytics.io/analytics.js"
  data-site-id="your-site-id"
  data-outbound-links="full"
  data-web-vitals="true"
  data-track-errors="true"
  data-dynamic-urls="/product/**,/user/*/settings"
></script>

Session Replay is not included in this example because it involves consent handling, sampling, and masking decisions that deserve more than a copy-paste. The Session Replay guide walks through them.

Each guide covers the full configuration reference for its capability, including additional attributes for fine-tuning behavior.

Script Tag or NPM Package?

Script tag: Best for plain HTML sites, CMS platforms (Shopify, Webflow), and no-code setups. Add it to your site’s <head> and configure with data- attributes.
WordPress: Skip the script tag entirely — the WordPress Plugin handles installation and configuration from wp-admin.
NPM package: Recommended for React, Next.js, Vue, and other modern frameworks. It provides a typed API, cleaner SPA support, and the same capabilities as options passed to betterlytics.init().

The integration panel in your dashboard shows the recommended setup for your specific framework, along with a real-time verification tool.

Troubleshooting

If data isn’t showing up after integration, the Troubleshooting guide walks through the most common causes, from caching and CSP headers to framework-specific gotchas.