Repository containing the Browser SDK for the Sematext Experience. It is used to collect end-user data from browsers using various browser APIs. It is designed to work with traditional web applications as well as single-page apps (SPAs). The collected data includes:
- Page load metrics,
- HTTP requests metrics,
- Page resources metrics,
- Long tasks metrics,
- Web Vitals metrics,
- Element timing metrics,
- User metrics,
- On-page transaction metrics.
The Experience script is developed using ECMAScript 2015. For builds and development it uses:
npm- Node package manageryarn- Package dependency managerflow- Static type checkerCypress.io- Integration tests framework
There are two parts of the Experience script:
- The loader script
- The metrics gathering script
The loader script is responsible for loading the metrics gathering script.
It adds the actual <script> tags with the content of the main metric script.
The loader script keeps track and buffers commands that will be sent once the
metrics gathering script loads and is configured.
Please note that the loader and the Experience script depend on each other. Before changing the scripts keep in mind that developers who have already added the script to their website will use the older loader script unless they update it.
The main entry point of the loader script is in src/snippet.js.
This is the unminified ES2015 version
of the loader script which is responsible for loading the metrics gathering script.
To generate the minified snippet of the loader script use yarn run generate-snippet.
Keep in mind that the loader script should be compact.
The main entry point of the Experience script is in src/index.js. Use eslint to catch any
style issues and flow to catch any type errors.
You can use the following commands:
yarn run startto start the development serveryarn run lintto runlinton the codeyarn run flowto runflowtype checksyarn run buildto build the production bundleyarn run devto build the development (not minified) bundle
You can test the loader and Experience scripts using one of the test websites that are provided:
test.html- simple app that can be used to generate page load events and HTTP requeststestspa.html- simple single-page app used to generaterouteChangeevents and HTTP requestslarge.html- app used for testing large requests sent from the Experience scripte2e.html- app used for most of the integration tests
Run yarn run start to run a small test website which runs the dev
version of the Experience script. After making changes to the script, reload the
website to see the changes.
If you wish to automatically test single page applications there is a second test application
called spa.html (see testspa.html file) which you start by running yarn run start. It
automatically runs routeChange commands every 10 seconds and HTTP requests every 5 seconds.
Cypress.io is used for automatic testing. The integration
tests are included in the cypress/integration/ directory and cover all the crucial
features of the script itself. The tests are using the same set of HTML files used
by the manual tests.
To run the full set of tests run yarn e2e. The results will include a table with test
results similar to the following:
Spec Tests Passing Failing Pending Skipped
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ✔ buffer.spec.js 00:10 1 1 - - - │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ✔ elementtiming.spec.js 00:46 3 3 - - - │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ✔ integration.spec.js 00:15 4 4 - - - │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ✖ large.spec.js 00:05 1 - 1 - - │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ✔ longtask.spec.js 00:30 2 2 - - - │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ✔ transactions.spec.js 00:15 1 1 - - - │
├────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ✔ web-vitals.spec.js 00:10 1 1 - - - │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
✖ 1 of 7 failed (14%) 02:15 13 12 1 - -
In order to configure the Experience script to send data to multiple Experience receivers you need to add the Experience snippet multiple times. Only the first snippet should have URL to the Experience script set so that it's loaded only once, for example:
<script type="text/javascript">
...
INSERT SCRIPT SNIPPET HERE
...
(window,document,"script","/experience.js","strumTest");
</script>
<script type="text/javascript">
...
INSERT SCRIPT SNIPPET HERE
...
(window,document,"script",null,"strumUS");
</script>
<script type="text/javascript">
window.STRUM_CONTEXTS = ['strumTest', 'strumUS'];
var receivers = [
'https://rum-receiver.test.sematext.com',
'https://rum-receiver.sematext.com',
]
strumTest('config', {
token: 'b12s3ssd-d11s-2d39-7231-f3s22grd635f',
receiverUrl: receivers[0],
ignoreOrigins: receivers,
});
strumUS('config', {
token: '8763d12d-1j3t-932v-b498-544290z98k43',
receiverUrl: receivers[1],
ignoreOrigins: receivers,
});
</script>Pull requests for bug fixes, improvements and new features are more than welcome. When opening
a new pull request please take the time to briefly describe the changes. Make sure that the newly
introduced code passes the lint and flow checks along with the integration tests. Once the PR
is submitted we will review and merge your changes.