Quickstart

This is the shortest path to a working dashboard: the browser script on its own. For server, edge or log sources, see Sources.

1. Create a site

Create a site for your domain in the dashboard. Every new site gets a script source automatically.

2. Add the script tag

Add this to the <head> of every page you want to track:

<script
  defer
  src="https://cdn.metrikstack.com/js/script.js"
  data-site="SITE_ID"
></script>

• defer keeps the script off the critical rendering path.
• data-site is your site's public id. It isn't a secret; ingest is rate-limited per site and per visitor.
• The script is under 1.5 kB gzipped, has no dependencies and sets no cookies.

It tracks pageviews automatically, including navigation in single-page apps (it patches history.pushState and listens for popstate). When the tab closes or the visitor navigates away, it sends a leave event with time on page and scroll depth.

Custom events

<script>
  window.metrikstack.track('signup', { plan: 'pro' });
</script>

Local development

By default the script does nothing on localhost and file: origins, so local testing stays out of your production data. To track locally anyway, for example to check the integration, add data-allow-local:

<script
  defer
  src="https://cdn.metrikstack.com/js/script.js"
  data-site="SITE_ID"
  data-allow-local
></script>

3. Wait for the first event

Open your site and load a page. The site's Install and Sources pages in the dashboard show that they are waiting for the first event until the script's pageview arrives, which usually takes a few seconds.

Serving the script from your own domain

Some ad blockers and privacy extensions block requests to known analytics domains. Serving the script from your own domain avoids that. The script sends its events to the origin it was loaded from, so proxy both the script and the /v1/event path (plus /v1/error if you use error tracking).

Next.js

Add rewrites in next.config.js:

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/js/script.js',
        destination: 'https://cdn.metrikstack.com/js/script.js',
      },
      {
        source: '/v1/event',
        destination: 'https://cdn.metrikstack.com/v1/event',
      },
    ];
  },
};

Then point the script tag at your own path:

<script defer src="/js/script.js" data-site="SITE_ID"></script>

nginx

location = /js/script.js {
    proxy_pass https://cdn.metrikstack.com/js/script.js;
    proxy_set_header Host cdn.metrikstack.com;
    proxy_ssl_server_name on;
    proxy_cache_valid 200 1h;
}

location = /v1/event {
    proxy_pass https://cdn.metrikstack.com/v1/event;
    proxy_set_header Host cdn.metrikstack.com;
    proxy_ssl_server_name on;
}

If /v1/event is already taken on your domain, set data-api on the script tag to another base URL, such as /stats. The script appends /v1/event to it, so proxy /stats/v1/event instead.

Next steps

• Add a server SDK or edge integration next to the script to count the traffic it misses: visitors with ad blockers, bots and cache hits.
• Read How merging works to see how several sources for one site are combined into one pageview count.