Skip to content
Collect and send page performance metrics with ease
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
src
.env.example
.eslintrc
.gitignore
.prettierrc
CODE_OF_CONDUCT.md
LICENSE
README.md
package.json
rollup.config.js
tsconfig.json
yarn.lock

README.md

License Contributor Covenant

Signal

Collect and send page performance metrics with ease

Table of contents

What is it

Signal is a script that collects specific page performance events and sends them to a configurable service url.

Installation

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.git

Or using https

git clone https://github.com/sumup-oss/signal.git

Run

yarn

Copy the .env.example to .env:

cp .env.example .env

The .env file contains the following values:

SERVICE_URL="" # (Required) The endpoint where events will be send to
APPLICATION_NAME="" # (Optional) the application identier. This is useful when you have more than one application sending events

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 build

Copy the output from build/perf.js

pbcopy < build/perf.js

Add the script to the <head> tag of your html file. This is required due to how you collect the time-to-interactive metric.

Events

The events are provided by both the PerformanceObserver and PerformanceTiming APIs.

Via PerformanceObserver (paint entry)

  • first-paint
  • first-contentful-paint

Via PerformanceObserver (longtask entry)

  • time-to-interactive

Via PerformanceTiming

  • dom-interactive
  • dom-content-loaded
  • dom-loading
  • dom-complete

Keep in mind each API has a different browser support. Please refer to Browser compatibility section for more info on it.

Event dispatch

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.

Event enhancing

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

Customization

You can customize both Events and Metadata fields.

Customizing Events

You can edit both PerformanceObserver and PerformanceTiming handlers. All you have to do is edit the perf.ts file.

Customizing Metadata fields

You'll have to edit two files:

Browser compatibility

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:

Event Browser
first-paint Chrome only
first-contentful-paint Chrome only
time-to-interactive Chrome only
dom-interactive Every major browser
dom-content-loaded Every major browser
dom-loading Every major browser
dom-complete Every major browser

Code of conduct (CoC)

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.

Maintainers

About SumUp

SumUp logo

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.

You can’t perform that action at this time.