Predictive Preloading

This project will let you predict the next user navigation and preload the corresponding document. It's supposed to integrate with Speed Kit.

User Manual Changelog Documented Configuration

Setup

1. nvm use or switch to node 19 manually
2. npm install to install dependencies
3. npm run prepare to register the pre-commit hook
4. Build the project

• npm run watch: will start watch mode and a dev server with a test page. Source maps, debug logs and visualisation are available.
• npm run build: will build the project with development features. Source maps, debug logs and visualisation are available.
• npm run build:prod: will build and minify the project without development features. Source maps, debug logs and visualisation are not available.
• npm run build:debug: will build and minify the project without development features. Source maps, debug logs and visualisation are available.

Build

• The code gets compiled to /dist. This snippet can be copy-pasted into websites to get a live demo. Choose either the dev (predictivePreloading.dev.js) or prod build (predictivePreloading.js).

Usage

The project can be configured to individual websites. Please refer to the PredictivePreloadConfig.ts for the commented API.

Preloads will by default be reported by calling SpeedKit.preload. The argument is an array of urls:

["/local/link-1", "/local/link-2", "..."]
Copy

You can change the preload behaviour by defining custom functions in the config. preloadFunction let you do whatever you want with an array of URL strings. It might be a good idea to check if your own prerequisites are met by defining an own runCondition. Insert logs into the preloadFunction to report what is being preloaded.

You can also define your own runCondition to toggle predictive preloading on your own terms. By default, it's enabled on every page it is included in.

You can test your Predictive Preloading right in the browser. Build the project in dev mode, copy the content dist/predictivePreloading.dev.js and paste it into your Dev Tools console. Then Call predictivePreload(). You can also paste a custom configuration as an argument into the new PredictivePreloading() function call. Use the following configuration to enable debug logs and visualization:

new PredictivePreloading({
  logs: true,
  visualization: true
})
Copy

Please refer to the User Manual for more instructions.

Analytics

The object containing the preload metadata information is sent via the custom Rum event predictivePreloadingMetadata on leavePage. preloading Metadata and Failures will be reported in the custom RUM event pp on leavePage, when the config option rum is truthy.

Contributing

• Please use gitflow to contribute to this project.
• We're using Compile Conditions. Please wrap code that's not supposed to be shipped to customers inside feature flags:

  //#if _DEBUG
  myDebugCode();
  //#endif
  Copy

• Please test before you commit.
• You will be provided with a templated merge message. Please fill it out when opening the Merge Request in Gitlab.
• If you change config options, please document the current status of the option in src/types/PredictivePreloadConfig.ts.

Testing

We have some automated unit tests for most parts of this project. Run npm run test:unit to check them. If you run them by calling mocha directly, you may have to add the following options: -r jsdom-global/register --exit. Unit tests should be enabled as pre-commit hooks. In case that didn't happen, please run npm run prepare. Passing unit tests is mandatory for committing and merging.

We have some automated E2E tests to check the functionality of the whole project. Run npm run test:e2e to execute them. Passing E2E tests is mandatory for merging.

We should also test things manually before merging. Here are some helpers for that:

Report Candidates

Import createBeacon and add to the predictivePreload function in the predictivePreloading.ts:

document.addEventListener('click', (e) => {
  e.preventDefault();
  console.log(createBeacon(config, state));
});
Copy

Things to test

• Prod Build ejects code inside debug compile conditions
• Touch-based candidate selection works only on touch-enabled user interactions
  • Elements outside of safe zone are excluded from predictive preloading
  • Invisible elements and elements with invisible parents are excluded
• Hover-based candidate selection works only on pointer-enabled user interactions
• Pointer-based candidate selection selects elements that are in the path of the cursor
  • See visualisation to estimate which elements to expect in the beacon
  • Points are assigned to elements, which correlate to the confidence for the next click
  • Scan zone is divided into a scan pointer pattern along the predicted cursor path
  • Scan pattern stretches out with higher cursor velocity
  • Scan pattern only returns links correlating to the scanned element
  • Scan pattern can be configured
• Predictive preloading is disabled
  • While scrolling
  • For low battery + not charging in chrome
  • For data saver mode on chrome
• Preloading URLs works
  • For Touch: URLs are preloaded from bottom to top
  • For Hover: URLs are preloaded immediately
  • Requests are queued and loaded in an interval as specified in the requestInterval option
  • There are never more requests sent at a than specified in the concurrentRequests option
  • Never sends more requests than specified in the requestLimit option
  • Preloaded URLs are reported via Post Message to the Service Worker
• RUM based preloading works
  • candidates with a score of >0.9 are priority-preloaded
  • candidates with a score of <0.9 should create a preload candidate with a calculated amount of points
  • RUM candidates in the viewport should be priority-preloaded
• Failure to execute a preload should be communicated to SpeedKit in a post message
• Never throws a console error, even in deprecated browsers
• Never introduces longtasks

Release

We use git flow to publish releases through the Gitlab CI pipeline.

Before the release

• Check if all tests are green
• Test library manually, as described above
• Get the next version number by checking the tags or the package.json
• Make sure all the features you need are on develop.
• Make any last minute amends

Releasing

1. Bump version number in package.json and commit
2. Create a prerelease: git checkout prerelease, git pull origin develop and git push.
3. Check the prerelease: Are the snippets, docs and changelog okay?
4. Start the release: git flow release start v1.2.3
5. git flow release finish 'v1.2.3'
6. On develop: git push
7. On master: git push --follow-tags
8. Create a release from the new tag in GitLab
9. Manually update the User Manual with new or changed features.
10. Inform the team of the new release in the #product-releases Slack channel

The Gitlab Pipeline will create a new release:

• Main version
• Debug version
• Changelog
• Documented Configuration

Please note that the release and release:pre tasks are only to be executed in the CI, not locally.

After the release

• Check if all tests are still green
• Notify Team Integration and Team Speed Kit about changes