- What is it
- Installation
- Configuration
- Usage
- Events
- Customization
- Browser compatibility
- Code of Conduct
- Maintainers
- About SumUp
Signal is a script that collects specific page performance events and sends them to a configurable service url.
At the moment Signal is distributed as a script. Meaning you have to build your own version and embed it in your web page. In order to build your version of it, follow these steps:
Clone the repo using SSH
git clone git@github.com:sumup-oss/signal.gitOr using https
git clone https://github.com/sumup-oss/signal.gitRun
yarnCopy the .env.example to .env:
cp .env.example .envThe .env file contains the following values:
SERVICE_URL=""
APPLICATION_NAME=""
PERFORMANCE_OBSERVER_METRICS=""The url where events will be send to
This is app's identifier and is useful when you have more than one application which is sending events
You can configure which metrics supported by PerformanceObserver you want to track by specifying them in comma-separated list.
Please keep in mind that these 6 metrics are included by default:
- first-paint
- first-contentful-paint
- largest-contentful-paint
- first-input-delay
- cumulative-layout-shift
- time-to-first-byte
In the example below custom user metrics are enabled additionally to the default FCP and FID metrics -
PERFORMANCE_OBSERVER_METRICS="first-paint,first-contentful-paint,first-input-delay,user-timing"Now you are ready to build the script. If you want to customize the events, please refer to Customization.
In order to generate the script, run
yarn buildCopy the output from build/perf.js
pbcopy < build/perf.jsAdd the script to the <head> tag of your html file. This is required due to how you collect the time-to-interactive metric.
Here's the full list of events that this script supports out of the box.
The events are provided by both the PerformanceObserver and PerformanceTiming APIs.
- first-paint ("paint" entry) enabled by default, controlled via config
- first-contentful-paint ("paint" entry) enabled by default, controlled via config
- first-input-delay ("first-input" entry) enabled by default, controlled via config
- largest-contentful-paint ("largest-contentful-paint" entry) enabled by default, controlled via config
- cumulative-layout-shift ("layout-shift" entry) enabled by default, controlled via config
- time-to-first-byte ("navigation" entry) enabled by default, controlled via config
- user-timing ("measure" entry) disabled by default, controlled via config
- element-timing ("element" entry) disabled by default, controlled via config
- resource-timing ("resource" entry) disabled by default, controlled via config
- navigation-timing ("navigation" entry) disabled by default, controlled via config
- time-to-interactive always enabled ("longtask" entry)
- dom-interactive always enabled
- dom-content-loaded always enabled
- dom-loading always enabled
- dom-complete always enabled
More detailed documentation about each metric, how they relate to each other and how they should be used can be found in Confluence - https://sumupteam.atlassian.net/wiki/spaces/DEV/pages/1431569763/Tracking+Performance.
Keep in mind each API has a different browser support. Please refer to Browser compatibility section for more info on it.
All events are transported using the Navigator.sendBeacon api.
The events from the PerformanceObserver API (first-paint, first-contentful-paint and time-to-interactive) are dispatched individually and as soon as they are available, to avoid losing the data.
The events from the PerformanceTiming API (dom-interactive, dom-content-loaded, dom-loading, dom-complete) are batched into a single request and are dispatched after the onload event. This is due since we have to wait for some properties after the onload event anyways.
By default each event is enhanced with the following metadata:
{
event_name,
user_agent,
google_analytics_client_id,
connection_type,
effective_connection_type,
url,
timestamp,
application;
}Please refer to Customization for more information on how to add/remove properties and events
You can customize both Events and Metadata fields.
You can edit both PerformanceObserver and PerformanceTiming handlers. All you have to do is edit the perf.ts file.
You'll have to edit two files:
- The Event type definition
IEnhancedMetric - The event enhancement function
enhance
The script is powered by three APIs:
If sendBeacon isn't available, the script won't be executed. There isn't a fallback with XHR due to the blocking nature of it.
Since each type of event has a different browser support, please refer to the table to understand which events you can support. The majority of the PerformanceObserver APIs that are required to get metric values, are only available in Chromium-based browsers (e.g. Google Chrome, Microsoft Edge, Opera, Brave, Samsung Internet, etc.).:
| Event | Browser |
|---|---|
| first-paint | Chromium |
| first-contentful-paint | Chromium |
| largest-contentful-paint | Chromium |
| first-input-delay | Chromium |
| cumulative-layout-shift | Chromium |
| time-to-first-byte | Chromium, Firefox |
| time-to-interactive | Chromium |
| user-timing | Chromium, Firefox |
| element-timing | Chromium |
| resource-timing | Chromium, Firefox |
| navigation-timing | Chromium, Firefox |
| dom-interactive | Every major browser |
| dom-content-loaded | Every major browser |
| dom-loading | Every major browser |
| dom-complete | Every major browser |
We want to foster an inclusive and friendly community around our Open Source efforts. Like all SumUp Open Source projects, this project follows the Contributor Covenant Code of Conduct. Please, read it and follow it.
If you feel another member of the community violated our CoC or you are experiencing problems participating in our community because of another individual's behavior, please get in touch with our maintainers. We will enforce the CoC.
SumUp is a mobile-point of sale provider. It is our mission to make easy and fast card payments a reality across the entire world. You can pay with SumUp in more than 30 countries, already. Our engineers work in Berlin, Cologne, Sofia, and Sāo Paulo. They write code in JavaScript, Swift, Ruby, Go, Java, Erlang, Elixir, and more.
Want to come work with us? Head to our careers page to find out more.