Documentation

Getting Started

Argusmetrics is privacy-first web analytics: no cookies, nothing stored on the visitor's device, and the IP address never kept in any form. The source is open under the AGPL-3.0.

Create an account and verify your email address
Add your website in the dashboard to get a tracking code
Verify that you own the domain by adding the TXT record the settings page gives you. Tracking is blocked until you do, and nothing is recorded in the meantime.
Paste the tracking script into your site's <head>
Start seeing data in real-time

Domain verification is not optional. A website that has not been verified records nothing at all, and the tracking script gives no error: the page loads, the request goes out, and the dashboard stays empty. If you have pasted the script and see no data, check the settings page for that website first.

Self-hosted: Throughout these docs, replace https://your-argusmetrics-instance.com with the URL where you host Argusmetrics. The tracking script and API both live on your own instance.

Installation

Step 1: Get Your Tracking Code

After adding a website in your dashboard, you'll receive a unique tracking code. It looks like this:

ABC123XYZ

Step 2: Add Script to Your Website

Add this snippet to the <head> section of your website, right before the closing </head> tag:

<script
  defer
  data-tracking-code="YOUR_TRACKING_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

Replace YOUR_TRACKING_CODE with your actual tracking code.

When you need data-api-endpoint: only when the tracking script is served from somewhere other than your Argusmetrics instance. That happens if you copy the script file onto your own CDN or bundle it with your site, which is the case on some static hosts. If you load it straight from your instance, as the snippet above does, the script already knows where to post and the attribute does nothing.

Get it wrong in that situation and the requests go to your hosting provider instead, which answers with a page rather than an error, so it fails silently and the dashboard simply stays empty.

Platform-Specific Guides

Click on your platform for step-by-step instructions:

Open your Framer project
Go to Site Settings → General → Custom Code
Paste this code in "End of <head> tag":

<script
  defer
  data-tracking-code="YOUR_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

Replace YOUR_CODE with your tracking code
Publish your site

✓ Done! Analytics will start tracking within minutes.

Open your Webflow project
Go to Project Settings → Custom Code
Paste this code in "Head Code" section:

<script
  defer
  data-tracking-code="YOUR_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

Replace YOUR_CODE with your tracking code
Click Save Changes
Publish your site

✓ That's it! Your Webflow site is now being tracked.

Go to Online Store → Themes
Click Actions → Edit Code on your active theme
Find and open theme.liquid file
Locate the </head> tag
Paste this code just before </head>:

<script
  defer
  data-tracking-code="YOUR_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

Replace YOUR_CODE with your tracking code
Click Save

✓ Perfect! Your Shopify store is now tracking visitors and sales.

Go to Settings → Advanced → Code Injection
Paste this code in the "Header" section:

<script
  defer
  data-tracking-code="YOUR_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

Replace YOUR_CODE with your tracking code
Click Save

✓ All set! Your Squarespace site is now tracking visitors.

✅ Recommended: Use our official WordPress plugin for easy installation. No theme editing required!

Step 1: Deploy Argusmetrics & sign in

Self-host Argusmetrics on your own server, see the GitHub repo for the Docker quickstart
Open your instance at https://your-argusmetrics-instance.com and sign in
It's free and open source (AGPL-3.0), unlimited sites and pageviews

Step 2: Add your website

On the dashboard, click "Add Website"
Enter your website name and domain (e.g. https://yoursite.com)
You will receive an 8-character tracking code

Step 3: Verify your domain

Domain verification is required before tracking starts. This confirms you own the domain.

Go to Settings for your website in the dashboard
Copy the DNS TXT record shown:
Type: TXT
Host: _argusmetrics.yoursite.com
Value: [your unique verification token]
Add the TXT record at your DNS provider (Loopia, Cloudflare, GoDaddy, etc.)
Wait 1-5 minutes, then click "Verify Domain Now"

Step 4: Install the WordPress plugin

Download the plugin: .zip or .tar.gz
In WordPress: Plugins → Add New → Upload Plugin
Upload the .zip file and click Install Now
Click Activate

Step 5: Configure the plugin

Go to Settings → Argusmetrics
Paste your 8-character tracking code
Check "Exclude Administrators" (so your own visits are not tracked)
Click Save Settings

Done! Visit your site and check your dashboard on your Argusmetrics instance, data appears in real-time.

Note: Argusmetrics sets no cookies and stores nothing on the visitor's device, so it needs no consent itself. Whether you still need a consent plugin depends on everything else on your site: embedded video, fonts, ad pixels, chat widgets. Check what else is loading before removing anything.

⚠️ Avoid: Do NOT edit your theme's header.php directly - your changes will be lost when updating the theme!

Alternative: Child Theme (Advanced)

If you prefer not to use a plugin:

Create a child theme (preserves code during theme updates)
Add the script to your child theme's header.php
Paste before </head>

💡 Tip: Just copy-paste the code below into your project - it works out of the box!

Next.js 13+ (App Router)

Add to app/layout.js or app/layout.tsx:

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <script
          defer
          data-tracking-code="YOUR_CODE"
          data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
          src="https://your-argusmetrics-instance.com/static/tracker.min.js"
        ></script>
      </head>
      <body>{children}</body>
    </html>
  );
}

Next.js 12 (Pages Router)

Add to pages/_document.js:

import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head>
        <script
          defer
          data-tracking-code="YOUR_CODE"
          data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
          src="https://your-argusmetrics-instance.com/static/tracker.min.js"
        ></script>
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

React (Create React App)

Add to public/index.html inside <head>:

<script
  defer
  data-tracking-code="YOUR_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

Paste this code in the <head> section of every HTML page:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Your Website</title>

  <!-- Argusmetrics Analytics -->
  <script
    defer
    data-tracking-code="YOUR_CODE"
    data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
    src="https://your-argusmetrics-instance.com/static/tracker.min.js"
  ></script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

✓ That's it! Copy the script tag and add it to all your HTML pages. Analytics will start tracking immediately.

Required: Static hosting platforms (GitHub Pages, Netlify, Cloudflare Pages, Vercel, etc.) do not support POST requests. You must add the data-api-endpoint attribute, otherwise tracking requests will silently fail.

The tracking script automatically sends data to the same domain it's loaded from. Since your site is hosted on a static platform, you need to tell it where the API is:

<script
  defer
  data-tracking-code="YOUR_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

Without data-api-endpoint, the script sends POST requests to your static host (e.g., GitHub Pages), which returns a 405 error. The script catches errors silently, so you won't see any error messages, tracking just doesn't work.

How to verify: Open your browser's DevTools (F12) → Network tab → visit your site → look for a POST request to /track. It should return 200, not 405.

Step 3: Verify Installation

Visit your website and check your Argusmetrics dashboard. You should see a real-time visitor within seconds.

Custom Events

Track custom actions like button clicks, form submissions, purchases, or any user interaction.

Basic Event Tracking

window.argus.trackEvent('signup');

Events with Properties

Add custom properties to track additional context:

window.argus.trackEvent('purchase', {
  plan: 'pro',
  amount: 9,
  currency: 'EUR'
});

Example: Track Button Click

<button onclick="window.argus.trackEvent('cta_click', {button: 'Get Started'})">
  Get Started
</button>

Custom Properties

Segment your analytics by attaching custom properties to pageviews. Perfect for tracking user types, A/B tests, subscription plans, and more.

🎯 Use Cases: Filter analytics by user plan (free/pro), A/B test variant, user ID, language, or any custom dimension specific to your business.

Tracking Pageviews with Properties

Pass custom properties when tracking pageviews:

window.argus.track({
  plan: 'pro',
  userId: '12345',
  experiment: 'variant-A'
});

Example: Track a Visitor's Plan on Your Site

<script>
  // Track pageview with this visitor's plan on YOUR site (not Argusmetrics', Argusmetrics has no plans, it's free and self-hosted)
  window.argus.track({
    plan: 'premium',
    userId: '12345',
    isLoggedIn: 'true'
  });
</script>

Example: A/B Testing

<script>
  // Track which A/B test variant the user sees
  const variant = Math.random() < 0.5 ? 'A' : 'B';

  window.argus.track({
    experiment: 'pricing-test',
    variant: variant
  });
</script>

Filtering by Properties in Dashboard

Go to your website dashboard
Click "Add Property Filter" button (purple button)
Enter property key (e.g., "plan")
Enter property value (e.g., "pro")
Click "Apply Filter"
Dashboard now shows analytics for only that segment

💡 Pro Tip: You can apply multiple property filters simultaneously to drill down into specific user segments. For example, filter by plan: pro AND experiment: variant-A to see how premium users interact with your A/B test.

Property Keys Best Practices

plan - Your customer's subscription tier on your own site (e.g. free, silver, gold)
userId - Track individual user journeys
experiment - A/B test experiment name
variant - A/B test variant (A, B, control)
language - User language preference (en, sv, no, da)
isLoggedIn - Whether user is authenticated (true, false)
campaign - Marketing campaign identifier

⚠️ Privacy Note: Do not include personally identifiable information (PII) like names, emails, or addresses in properties. Use anonymized IDs instead.

Conversion Goals

Track important business metrics like signups, purchases, or form submissions.

Setting Up Goals

Go to your website dashboard
Click "Goals" tab
Click "Create Goal"
Enter goal name (e.g., "signup", "purchase")
Track events with that name

💡 Tip: Goals automatically track custom events with matching names. Track "signup" events, create a "signup" goal, and see conversion rates instantly.

Campaign & Ad Tracking

Track the performance of your ad campaigns from Meta, Google Ads, TikTok, and any other platform using UTM parameters.

No extra setup needed. The tracking script automatically reads UTM parameters from your URLs and sends them to the dashboard.

What are UTM Parameters?

UTM parameters are tags you add to the end of your ad URLs. When someone clicks the link, Argusmetrics reads the tags and shows you exactly which campaigns are driving traffic.

Parameter	Purpose	Example
`utm_source`	Where the ad is shown	facebook, google, instagram
`utm_medium`	Type of traffic	cpc, email, social
`utm_campaign`	Campaign name	summer_sale, launch_2026
`utm_content`	Ad variant	image_a, video_b
`utm_term`	Search keyword (Google Ads)	cheap+shoes

Example: Meta (Facebook) Ads

When creating an ad in Meta Ads Manager, set your destination URL like this:

https://yoursite.com/offer?utm_source=facebook&utm_medium=cpc&utm_campaign=summer_sale&utm_content=video_v1

In your dashboard, this visit will show up under UTM Campaigns with source facebook, medium cpc, and campaign summer_sale. The traffic channel will automatically be categorized as "Paid".

Example: Google Ads

https://yoursite.com/landing?utm_source=google&utm_medium=cpc&utm_campaign=brand_keywords&utm_term=web+analytics

Tip: Both Meta and Google can generate UTM parameters automatically. In Meta Ads Manager, use the "URL Parameters" field. In Google Ads, enable "Auto-tagging" in your account settings.

Traffic Channels

Argusmetrics automatically categorizes your traffic into channels based on UTM parameters and referrer data:

Channel	How it's detected
Paid	`utm_medium` is `cpc`, `ppc`, or `paid`
Email	`utm_medium` is `email`
Organic	Referrer is Google, Bing, DuckDuckGo, etc.
Social	Referrer is Facebook, Twitter, LinkedIn, etc.
Referral	Referrer is another website
Direct	No referrer (typed URL, bookmark, etc.)

What You See in the Dashboard

UTM Campaigns: Table showing source, medium, campaign name, and visitor count
Traffic Channels: Chart breaking down Paid vs Organic vs Direct vs Social traffic
Goals: Combine with conversion goals to see which campaigns actually convert

Combining with Goals

Set up a conversion goal (e.g., "signup") and then check the UTM Campaigns section to see which ad campaigns are driving actual conversions, not just clicks.

Note: Argusmetrics does not support retargeting pixels (Meta Pixel, Google Tag, etc.) since these require third-party cookies and cross-site tracking. We track which campaigns bring traffic and conversions, but we don't feed data back to ad platforms for retargeting.

Outbound Link Tracking

Argusmetrics automatically tracks clicks on external links. No configuration needed!

What Gets Tracked

Links to different domains (e.g., yoursite.com → google.com)
Links with target="_blank"
HTTP and HTTPS links only

Excluding Domains

To exclude certain domains from tracking (e.g., your own subdomains):

<script
  defer
  data-tracking-code="YOUR_CODE"
  data-api-endpoint="https://your-argusmetrics-instance.com/api/v1/analytics/track"
  data-exclude-outbound="stripe.com,paypal.com"
  src="https://your-argusmetrics-instance.com/static/tracker.min.js"
></script>

404 Error Tracking

Find and fix broken links by tracking 404 errors automatically.

Setup

Add this code to your 404 error page:

<script>
  if (window.argus) {
    window.argus.trackEvent('404 Error', {
      path: window.location.pathname,
      referrer: document.referrer || 'direct'
    });
  }
</script>

404 errors will appear in your dashboard's "404 Errors" section with:

Broken URL path
Number of times accessed
Referrer (where visitors came from)
Last seen timestamp

Ecommerce Analytics

Track revenue, products, and conversion funnels with built-in ecommerce analytics. Perfect for SaaS, Shopify, WooCommerce, and any online store.

No extra setup needed. The tracking script already includes trackEcommerce(). Just call it at the right moments in your checkout flow.

Event Types

Track the full customer journey with 8 event types:

Event	When to use
`view_item`	Visitor views a product page
`add_to_cart`	Product added to cart
`remove_from_cart`	Product removed from cart
`begin_checkout`	Checkout process started
`add_payment_info`	Payment details entered
`add_shipping_info`	Shipping details entered
`purchase`	Purchase completed
`refund`	Refund processed

Track a Purchase

window.argus.trackEcommerce('purchase', {
  transaction_id: 'order-123',
  revenue: 99.99,
  currency: 'USD',
  tax: 8.00,
  shipping: 5.99,
  product_name: 'Pro Plan',
  product_id: 'plan_pro',
  quantity: 1
});

Track Product Views

window.argus.trackEcommerce('view_item', {
  product_name: 'Pro Plan',
  product_id: 'plan_pro',
  price: 99.99
});

Track Add to Cart

window.argus.trackEcommerce('add_to_cart', {
  product_name: 'Starter Plan',
  product_id: 'plan_starter',
  quantity: 1,
  price: 29.99
});

Full Checkout Funnel Example

// 1. Product page
argus.trackEcommerce('view_item', {
  product_name: 'Pro Plan', product_id: 'plan_pro', price: 99.99
});

// 2. Add to cart button
argus.trackEcommerce('add_to_cart', {
  product_name: 'Pro Plan', product_id: 'plan_pro', quantity: 1, price: 99.99
});

// 3. Checkout page
argus.trackEcommerce('begin_checkout', {
  revenue: 99.99, currency: 'USD'
});

// 4. After successful payment
argus.trackEcommerce('purchase', {
  transaction_id: 'order-456',
  revenue: 99.99,
  currency: 'USD',
  product_name: 'Pro Plan',
  product_id: 'plan_pro'
});

Custom Properties

Attach extra data like payment method or coupon codes:

argus.trackEcommerce('purchase', {
  transaction_id: 'order-789',
  revenue: 79.99,
  product_name: 'Pro Plan',
  properties: {
    payment_method: 'credit_card',
    coupon: 'SAVE20'
  }
});

Server-Side Tracking (API)

You can also send ecommerce events directly from your backend:

POST /api/v1/analytics/track-ecommerce
Content-Type: application/json

{
  "tracking_code": "YOUR_CODE",
  "event_type": "purchase",
  "event_name": "Product Purchase",
  "transaction_id": "order-123",
  "revenue": 99.99,
  "currency": "USD",
  "product_name": "Pro Plan",
  "product_id": "plan_pro"
}

What You See in the Dashboard

Total Revenue: Sum of all purchases in the selected period
Total Transactions: Number of completed purchases
Average Order Value: Revenue / transactions
Top Products: Best-selling products by revenue
Revenue Chart: Revenue over time (daily)
Conversion Funnel: Drop-off rates from view to purchase

Multi-currency support: Revenue is tracked per currency (USD, EUR, SEK, etc.). The dashboard filters by currency automatically.

Available Fields

Field	Type	Description
`transaction_id`	string	Unique order ID (required for purchases)
`revenue`	number	Total transaction amount
`currency`	string	ISO 4217 code (default: USD)
`tax`	number	Tax amount
`shipping`	number	Shipping cost
`product_name`	string	Product name
`product_id`	string	Product SKU/ID
`product_category`	string	Product category
`product_brand`	string	Product brand
`quantity`	number	Quantity (default: 1)
`price`	number	Price per unit
`properties`	object	Custom key/value data

Team Management

Collaborate with your team by inviting members with different permission levels.

Roles

👑 Owner

Full access. Can delete the website, manage team roles, and invite admins/viewers.

⚙️ Admin

Can view analytics, edit settings, manage goals, and invite admins/viewers (cannot delete the website, remove the owner, or change member roles).

👁️ Viewer

Read-only access to the dashboard. No settings, team management, or editing permissions.

Inviting Team Members

Go to your website dashboard
Click "Team" tab
Click "Invite Team Member"
Enter email and select role
They'll receive an invitation email

API Reference

Access your analytics data programmatically via our RESTful API.

Authentication

Create an API token in your website settings and pass it in the X-API-Token header:

curl -H "X-API-Token: YOUR_API_TOKEN" \
  "https://your-argusmetrics-instance.com/api/v1/analytics/stats/7?start_date=2026-08-01&end_date=2026-08-31"

Track Pageview

POST /api/v1/analytics/track
Content-Type: application/json

{
  "tracking_code": "YOUR_CODE",
  "path": "/about",
  "referrer": "https://google.com",
  "screen_width": 1920
}

Track Custom Event

POST /api/v1/analytics/track-event
Content-Type: application/json

{
  "tracking_code": "YOUR_CODE",
  "event_name": "signup",
  "properties": {
    "plan": "pro",
    "amount": 9
  }
}

Quick Start (30 seconds)

Getting Started

Installation

Step 1: Get Your Tracking Code

Step 2: Add Script to Your Website

Platform-Specific Guides

Step 1: Deploy Argusmetrics & sign in

Step 2: Add your website

Step 3: Verify your domain

Step 4: Install the WordPress plugin

Step 5: Configure the plugin

Alternative: Child Theme (Advanced)

Next.js 13+ (App Router)

Next.js 12 (Pages Router)

React (Create React App)

Step 3: Verify Installation

Custom Events

Basic Event Tracking

Events with Properties

Example: Track Button Click

Custom Properties

Tracking Pageviews with Properties

Example: Track a Visitor's Plan on Your Site

Example: A/B Testing

Filtering by Properties in Dashboard

Property Keys Best Practices

Conversion Goals

Setting Up Goals

Campaign & Ad Tracking

What are UTM Parameters?

Example: Meta (Facebook) Ads

Example: Google Ads

Traffic Channels

What You See in the Dashboard

Combining with Goals

Outbound Link Tracking

What Gets Tracked

Excluding Domains

404 Error Tracking

Setup

Ecommerce Analytics

Event Types

Track a Purchase

Track Product Views

Track Add to Cart

Full Checkout Funnel Example

Custom Properties

Server-Side Tracking (API)

What You See in the Dashboard

Available Fields

Team Management

Roles

👑 Owner

⚙️ Admin

👁️ Viewer

Inviting Team Members

API Reference

Authentication

Track Pageview

Track Custom Event

Need Help?