How to use URL parameters edit

Download PDF

There are a few ways we determine where a visitor comes from. We automatically detect the previous page (referrer) from the visitor’s browser, but you can also add a URL parameter to override this and set a custom referrer.

Using a URL parameter

If the current URL on your site includes a parameter named ref or utm_source, we use this value instead of the browser’s previous page.

For example, if you were to include this link in an email newsletter, Simple Analytics records the referrer as email in your dashboard, no matter where user actually comes from:

UTM codes

UTM codes are bits of text you can add to a link that tell Simple Analytics (as well as other analytics tools) a little bit more information about each link. Here’s a sample of what one looks like:

We support the following codes:

  • UTM source (e.g.: utm_source=company-x)
  • UTM medium (e.g.: utm_medium=newsletter)
  • UTM campaign (e.g.: utm_campaign=march_01)
  • UTM content (e.g.: utm_content=button_red)
  • UTM term (e.g.: utm_term=shoes, this param is deprecated as it is intended to contain user generated content)

The UTM codes will show up on the dashboard in the “Referrals” dropdown menu:

Read the UTM guide at Buffer to learn more about UTM codes.

We drop non-UTM parameters from the URLs. If you want to allow more URL parameters, for example, project-id, use our allow params-feature.

Forbidden characters

Certain character are not allowed in the URL parameter. Letters and numbers are always okay, but if you want to use special characters (like spaces, ;, /, ?, :, @, &, =, +, $, or ,) you need to escape your URL parameter. A good website that does this for you is

Valid examples of URL parameters:

Using the referrer URL

We always the URL of the referring page from the visitor’s browser. We only save the part of the referrer before ? or #, so if the referrer URL is, we only store Note that the protocol (https://) is also removed. We also ignore common subdomains like www., m., l., and www2..

You don’t have to do anything to make this work.

Parsing of values

We parse the URL parameter differently than the referrer URL. Because you generate the URL parameters yourself, we don’t want to touch these too much. Instead, we decode their values (so you can use forbidden characters) and convert hostnames to more general names. For example, we convert to google. We still store the original value, but we show google as the referrer in the dashboard. We do this so we can combine similar referrers, such as,, and, into simply google.

Referrer URLs contain the full URL that the browser gives us, such as From this URL we store as the referrer and keep as the original URL. We drop the query (?query=sensitive+information), protocol (https://), and common subdomain (www.).

If you want to allow more URL parameters than the UTM parameters from your own website, use our allow params-feature.