diff --git a/_docs/10_general/03_how-to-use-url-params.md b/_docs/10_general/03_how-to-use-url-params.md index baa5b9cf..ddbc1dc4 100644 --- a/_docs/10_general/03_how-to-use-url-params.md +++ b/_docs/10_general/03_how-to-use-url-params.md @@ -4,7 +4,7 @@ menu: How to use URL params category: general permalink: /how-to-use-url-parameters excerpt: "You can add URL parameters to see where your customers are coming from." -last_modified_at: 2026-10-17 +last_modified_at: 2026-10-29 --- 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. @@ -43,7 +43,7 @@ The UTM codes will show up on the dashboard in the "Referrals" dropdown menu: [Read the UTM guide](https://buffer.com/library/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](/allow-params)-feature. +We drop non-UTM parameters from the URLs. From script version 12, we do collect the names of parameters that have a value, like `gclid`, but not their values, so you can tell paid from organic traffic. You can turn this off with [ignore metrics](/ignore-metrics). If you want to allow more URL parameters, for example, `project-id`, use our [allow params](/allow-params)-feature. ### Forbidden characters diff --git a/_docs/10_general/10_what_we_collect.md b/_docs/10_general/10_what_we_collect.md index 26e7256f..d486c15e 100644 --- a/_docs/10_general/10_what_we_collect.md +++ b/_docs/10_general/10_what_we_collect.md @@ -4,7 +4,7 @@ category: general permalink: /what-we-collect hidden: true excerpt: "Simple Analytics only collects privacy-insensitive data. Here is a list of what we do and don’t collect from your visitors." -last_modified_at: 2026-10-17 +last_modified_at: 2026-10-29 --- Not collecting any information would be silly and unrealistic for an analytics tool. We do collect information that is necessary to show you _simple_ analytics, but unlike other analytics tools, we don't collect more than absolutely necessary. Here is a list of what we **do and don't** collect from your visitors. @@ -131,7 +131,7 @@ None of these IDs are linked to a person or personal data, and none are stored o > We **partially collect** and **partially store** URLs -Too much information in the URL can be confusing and can make your stats messy. We only collect and store the first part of the URL. If an URL looks like this `https://example.com/index.html?search=keyword#top` we will only store `https://example.com/index.html`, also known as the protocol (`https`), hostname (`example.com`), and pathname (`/index.html`). +Too much information in the URL can be confusing and can make your stats messy. We only collect and store the first part of the URL. If an URL looks like this `https://example.com/index.html?search=keyword#top` we will only store `https://example.com/index.html`, also known as the protocol (`https`), hostname (`example.com`), and pathname (`/index.html`). From script version 12, we also collect the names of URL parameters that have a value, like `search`. We don't collect their values, except for [UTM codes](#utm-parameters) and [allowed parameters](/allow-params). Read more on [using URL parameters](/how-to-use-url-parameters). ### Referrers @@ -195,7 +195,7 @@ When a visitor scrolls on a page we record how far they scrolled. We do store th ### Script settings -We send some script settings along with the page view. To identify the embed script and check if the page view comes from a robot. The script settings include things like `version: script_version_2`, `robot: true`. +We send some script settings along with the page view. To identify the embed script and check if the page view comes from a robot. The script settings include things like `version: script_version_2`, `robot: true`. From script version 12, we also send the URL of the embed script without its query string. ### Do Not Track diff --git a/_docs/10_general/15_metrics.md b/_docs/10_general/15_metrics.md index 36b41af7..4d2a0bad 100644 --- a/_docs/10_general/15_metrics.md +++ b/_docs/10_general/15_metrics.md @@ -3,7 +3,7 @@ title: Metrics category: general permalink: /metrics excerpt: "We never track visitors so the data below is never linked to one specific visitor. Here is a list of metrics we collect." -last_modified_at: 2026-10-17 +last_modified_at: 2026-10-29 hidden: true redirect_from: - /data-points @@ -39,7 +39,7 @@ To know where customers come from, we store the page's referrer. This means that For example `https://simpleanalytics.com/?utm_source=newsletter` -The part after the `?` is called [URL parameters](/how-to-use-url-parameters). We only keep the UTM codes (`utm_source`/`ref`, `utm_medium`, `utm_content`, `utm_campaign`, `utm_term`) and drop all other URL parameters, unless you [allow them](/allow-params). The UTM codes are something that the customer adds to the URLs. They are usually generic terms like "newsletter_may" or "twitter_campaign_2". Don't put personal data in UTM codes. [See below][5]. +The part after the `?` is called [URL parameters](/how-to-use-url-parameters). We only keep the UTM codes (`utm_source`/`ref`, `utm_medium`, `utm_content`, `utm_campaign`, `utm_term`) and drop all other URL parameters, unless you [allow them](/allow-params). From script version 12, we also collect the names of the other parameters that have a value, but not their values, unless you [ignore `querykeys`](/ignore-metrics). The UTM codes are something that the customer adds to the URLs. They are usually generic terms like "newsletter_may" or "twitter_campaign_2". Don't put personal data in UTM codes. [See below][5]. ### Unique @@ -89,7 +89,7 @@ To know which type of device the visitor used, we store the user agent. This is

Somewhat important

-We send some script settings along with the page view. To identify the embed script and check if the page view comes from a robot. The script settings include things like `version: script_version_2`, `robot: true`. +We send some script settings along with the page view. To identify the embed script and check if the page view comes from a robot. The script settings include things like `version: script_version_2`, `robot: true`. From script version 12, we also send the URL of the embed script without its query string. ### Dimensions diff --git a/_docs/20_install-script/00_v12.md b/_docs/20_install-script/00_v12.md new file mode 100644 index 00000000..e2ba5ec7 --- /dev/null +++ b/_docs/20_install-script/00_v12.md @@ -0,0 +1,34 @@ +--- +title: Embed script v12 +category: install-script +hidden: true +permalink: /script/v12 +last_modified_at: 2026-10-29 +created_at: 2026-10-29 +--- + +Our public script is now at v12. You get it automatically with `latest.js`. If you use [SRI](/sri), update to the v12 script and hash. + +## New features + +- [Inline events](/events/inline) are part of the main script: add `data-simple-event` to clicks and form submits, with `data-simple-event-*` attributes as metadata. +- Optional [404 detection](/events/inline#404-pages): `data-detect-404="true"` sends a `page_404` event. +- We collect the names of query parameters that have a value. For example, `gclid` tells paid from organic traffic. We still only collect values of UTM codes, `ref`, and [allowed parameters](/allow-params). Opt out with [`data-ignore-metrics="querykeys"`](/ignore-metrics). +- [Overwrite the referrer](/overwrite-referrer) with `data-referrer` or `sa_settings.referrer`. +- Optional [time on page pings](/pings): `data-pings="5,60"` sends the visible time at those seconds. +- [Automated events](/automated-events) collect clicks on phone (`tel:`) links. +- Inline and automated events use `fetch` with `keepalive` when the browser supports it, with an image request as fallback, so they are more likely to arrive when the visitor navigates away. + +## Improvements and fixes + +- [Time on page](/explained/time-on-page) is reliable on mobile and only counts visible time. +- Automated events no longer block or delay links: Cmd, Ctrl, and middle clicks work, and there's no 5 second delay. +- Automated events work with a [custom namespace](/events#the-variable-sa_event-is-already-used) and skip links with `data-simple-event`. +- Visitors arriving through a Cloudflare challenge are counted as [unique](/uniques). +- Ignoring `scrolled` no longer drops the screen size. +- Manual page views with a different query string are no longer merged. +- [`data-allow-params`](/allow-params) is case-insensitive. +- Fixed false bot detection with the Phantom wallet extension. +- Removed the retired Cloudflare app build. + +If you are a developer you might want to see [what changed](https://github.com/simpleanalytics/scripts/compare/v11...v12) in our open-source repository. diff --git a/_docs/20_install-script/01_script.md b/_docs/20_install-script/01_script.md index 2c031fc4..c6e7b7a5 100644 --- a/_docs/20_install-script/01_script.md +++ b/_docs/20_install-script/01_script.md @@ -2,7 +2,7 @@ title: How to add our script category: install-script permalink: /script -last_modified_at: 2026-10-25 +last_modified_at: 2026-10-29 --- Include these two lines on every page at the end of your `` (or anywhere else): @@ -88,6 +88,7 @@ These settings are available: | `metadataCollector` | [`data-metadata-collector`][12] | `"myAddMetadataFunction"` | | `pings` | [`data-pings`][13] | `[5, 30, 60]` | | `detect404` | [`data-detect-404`][14] | `true` | +| `referrer` | [`data-referrer`][15] | `"https://example.com/"` | For `pathOverwriter` and `metadataCollector`, use the name of a function on `window`, not the function itself. The script logs the settings it received in the browser console. @@ -105,6 +106,7 @@ For `pathOverwriter` and `metadataCollector`, use the name of a function on `win [12]: /metadata [13]: /pings [14]: /events/inline#404-pages +[15]: /overwrite-referrer ## Browser support diff --git a/_docs/20_install-script/02_custom.md b/_docs/20_install-script/02_custom.md index a32881f2..7d9cb942 100644 --- a/_docs/20_install-script/02_custom.md +++ b/_docs/20_install-script/02_custom.md @@ -2,7 +2,7 @@ title: Trigger custom page views category: install-script permalink: /trigger-custom-page-views -last_modified_at: 2026-10-17 +last_modified_at: 2026-10-29 --- Normally you want to trigger a custom page view for _Single Page Apps_ (SPAs) like React, Vue, and Angular. Because pages are not completely reloaded on navigation we need a way to track those navigations as page views. @@ -49,7 +49,7 @@ You can read our source code [on GitHub](https://github.com/simpleanalytics/scri ## Use custom collection anyway -There might be situation where you don't want to auto collect page views. When you add the `data-auto-collect="false"` attribute you can expose a function called `sa_pageview`. When you call this function, the script will send a page view with the path you give as a parameter. If you don't give a path it will use `window.location.pathname` as a default. This only works with `latest.js`, not with our [light script](/light). +There might be a situation where you don't want to auto collect page views. When you add the `data-auto-collect="false"` attribute, the script doesn't send page views by itself and you send them with the `sa_pageview` function. When you call this function, the script will send a page view with the path you give as a parameter. If you don't give a path it will use `window.location.pathname` as a default. This only works with `latest.js`, not with our [light script](/light). ```html +``` + +We clean this referrer the same way as [the referrer from the browser](/how-to-use-url-parameters#using-the-referrer-url). Later page views in a single page app still use the previous page as their referrer. If you [ignore the `referrer` metric](/ignore-metrics), we don't send it. + +You can also set it with `referrer` in [`sa_settings`](/script#settings-via-javascript). diff --git a/_docs/20_script-settings/05_allow-url-parameters.md b/_docs/20_script-settings/05_allow-url-parameters.md index a40248d6..c5885770 100644 --- a/_docs/20_script-settings/05_allow-url-parameters.md +++ b/_docs/20_script-settings/05_allow-url-parameters.md @@ -3,7 +3,7 @@ title: Allow URL parameters category: script-settings permalink: /allow-params created_at: 2022-07-26 -last_modified_at: 2026-10-17 +last_modified_at: 2026-10-29 --- By default, we collect all UTM parameters (with and without the `utm_` prefix) and the `ref` (which is short for `utm_source`) parameter: @@ -27,6 +27,6 @@ If you want to capture `product-id` and `article-slug` from your website's URLs, > ``` -> **Warning:** Defined parameters in `data-allow-params` are case-sensitive. +From script version 12, parameter names in `data-allow-params` are case-insensitive, so `product-id` also allows `Product-ID`. In older versions they are case-sensitive. Read more on [how to use URL parameters](/how-to-use-url-parameters) on your website. diff --git a/_docs/55_events/00_inline-events.md b/_docs/55_events/00_inline-events.md index 29c0f39a..a7c34730 100644 --- a/_docs/55_events/00_inline-events.md +++ b/_docs/55_events/00_inline-events.md @@ -2,7 +2,7 @@ title: Inline events category: events permalink: /events/inline -last_modified_at: 2026-10-25 +last_modified_at: 2026-10-29 --- From script version 12, our main script sends an event when a visitor interacts with an element that has a `data-simple-event` attribute. You don't need to write JavaScript or load an extra script. @@ -11,8 +11,6 @@ From script version 12, our main script sends an event when a visitor interacts ``` -If you added the beta `inline-events.js` script, remove it. Otherwise every event is sent twice. - ### Clicks Add `data-simple-event="event_name"` to any clickable element: diff --git a/_docs/55_events/01_introduction.md b/_docs/55_events/01_introduction.md index a2b817be..6570d7ae 100644 --- a/_docs/55_events/01_introduction.md +++ b/_docs/55_events/01_introduction.md @@ -3,10 +3,10 @@ title: Introduction to events menu: Introduction category: events permalink: /events -last_modified_at: 2026-10-17 +last_modified_at: 2026-10-29 --- -With events in Simple Analytics you can collect counts of certain events. Let's say, you want to record a button click, you can fire an event for that. To make it easier for non-developers, we created [an automated events script](/automated-events). This script collects events for downloads, outbound links, and clicks on email links. You will need to install our separate script for it, but after that you don't need to modify any code. +With events in Simple Analytics you can collect counts of certain events. Let's say, you want to record a button click, you can fire an event for that. To make it easier for non-developers, we created [an automated events script](/automated-events). This script collects events for downloads, outbound links, and clicks on email and phone links. You will need to install our separate script for it, but after that you don't need to modify any code. If you want to get your hands dirty, you can collect events for all kinds of custom events. Like form submits, button clicks, and many more. We created a simple video showing how to collect events in Simple Analytics. [Here you go](https://www.youtube.com/watch?v=CCvdgTReqms) @@ -64,7 +64,7 @@ To send metadata with your event, [check our metadata page](/metadata). ## Inline events helper -We created a simple helper script that allows you to use data attributes for events: +From script version 12, our main script supports data attributes for events: ```html See pricing @@ -143,4 +143,4 @@ If the `sa_event` variable is already in use you can change it with the `data-na ``` -The namespace also changes other variables. For example, `sa_metadata` becomes `ba_metadata` and `sa_loaded` becomes `ba_loaded`. The [`sa_pageview`](/trigger-custom-page-views#use-custom-collection-anyway) function keeps its name. If you use [automated events](/automated-events), add `data-sa-global="ba_event"` to the automated events script. +The namespace also changes other variables. For example, `sa_metadata` becomes `ba_metadata` and `sa_loaded` becomes `ba_loaded`. From script version 12, the [`sa_pageview`](/trigger-custom-page-views#use-custom-collection-anyway) function becomes `ba_pageview` too. Older versions keep `sa_pageview`. If you use [automated events](/automated-events), add `data-sa-global="ba_event"` to the automated events script. diff --git a/_docs/55_events/15_metadata.md b/_docs/55_events/15_metadata.md index d5034e05..2d709fde 100644 --- a/_docs/55_events/15_metadata.md +++ b/_docs/55_events/15_metadata.md @@ -3,7 +3,7 @@ title: Collect metadata category: events permalink: /metadata created_at: 2022-07-26 -last_modified_at: 2026-10-17 +last_modified_at: 2026-10-29 --- To collect additional data on top of [our collected metrics](/metrics), you can append metadata. With this feature you can specify specific parameters and it will be included in our database with your datapoints (events or page views). @@ -81,7 +81,9 @@ An example on how to to set metadata on the `window` object: ``` -Our script reads the `sa_metadata` object once, when it loads, and appends this metadata to every event and page view. Make sure to define it before the script loads. To change the metadata later, for example after a route change in a single page app, update the properties of the same object instead of assigning a new object: +Our script appends this metadata to every event and page view. From script version 12, it reads `sa_metadata` every time it sends data, so you can also assign a new object later, for example after a route change in a single page app. + +Older versions read the object once, when the script loads. With those, define it before the script loads and update the properties of the same object instead of assigning a new object: ```js sa_metadata.theme_color = "blue"; diff --git a/_docs/55_events/20-sa-link-event.md b/_docs/55_events/20-sa-link-event.md index cfd7cfe5..263e49d0 100644 --- a/_docs/55_events/20-sa-link-event.md +++ b/_docs/55_events/20-sa-link-event.md @@ -3,10 +3,10 @@ title: Collect events for link clicks category: events permalink: /events/custom-link-clicks menu: Custom link clicks -last_modified_at: 2022-07-18 +last_modified_at: 2026-10-29 --- -The [automated events script](/automated-events) does collect events for outbound links. It does not require any coding, just adding a script. You probably want to use [that script](/automated-events). +The [automated events script](/automated-events) does collect events for outbound links. It does not require any coding, just adding a script. You probably want to use [that script](/automated-events). From script version 12, you can also add a [`data-simple-event`](/events/inline) attribute to any link without extra code. If you want to collect events for other links or control a bit more on how it works, you can use the code below. Let's say you have a HTML page with this content: