@eggplantio/real-user-data-sdk-js NPM

Real User Data SDK

Overview

The Real User Data SDK facilitates the collection of non-PII (Personally Identifiable Information) such as customer behaviour, device specifications, performance timing, software release versions, and business impact (revenue, conversion). This data is processed by our cloud-based platform to generate a modern class of aggregated data insights. In particular, these insights drive decision-making and test automation within Eggplant's suite of AI-assisted end-to-end user testing known as Eggplant DAI. We refer to this process as CXO (Customer Experience Optimisation).

In order to instrument an application with this SDK you need to be aware of two components:

Definition, - this SDK (this repository) which describes and consists of all the capabilities and ways to use/capture/collect/send data from web applications. See the "Installation Guide" below.
Implementation - a different piece of code created by you that describes how the SDK should behave, collect and where to send the collected data.

In order for the SDK to successfully collect data, it is mandatory to have both components. Once you have both scripts and those are ready to be deployed, you can simply add them to your website, either in the < head > tag, at the end of the < body > tag or within a tag manager like Google Tag manager, Tealium etc.

If you are not using a tag manager, someone technical need to manually deploy the tags into your web application. If you don't want to monitor certain pages, simply do not deploy the tags on those pages. Deploying this SDK is similar in nature with deploying any other monitoring SDK on the market such as Google Analytics, Pingdom etc.

Once the tags are deployed, the SDK will start monitoring, collecting and sending data according to your implementation.

New version is here!

We are glad to introduce the newest version of RCI - Real User Data SDK.

Browsers support

IE / Edge	Firefox	Chrome	Safari	iOS Safari	Samsung	Opera
IE11, Edge	last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions

The browsers stated in the table above are the ones that we tested on but is not an exhaustive representation of our SDK browser compatibility.

Generally speaking, we are supporting the last 2 versions for all the popular browsers for the current bundle (the default artefact) and IE 11 and everything since then till present via the legacy bundle.

Documentation

Please see the SDK documentation and examples below. You can also see the REST Api Documentation for more details about what can be captured.

So how to use Real User Data SDK

Compile the source code using webpack

webpack --config=config/webpack.js --env=scope=core --env=rulesTarget=current --env=mode=production

Add the dist/rci.min.js script to your website via local javascript file, CDN, NPM package or GTM, and you are ready to go.

You can always check out this repository and look at the examples directory.

E-Commerce with conversion

Use this example as starting point if you are going to collect data about converting User Journeys.

Custom collector

Use this example as starting point if you are going to collect custom data.

Error collector

Use this example as starting point if you are going to collect data when an error occurs in your website.

OnLoad collector

Use this example as starting point if you are going to collect data after page loads.

Web-based collector

Use this example as starting point if you are going to collect data from webpages

Installation Guide

npm package

Install the package via NPM or Yarn

npm i @eggplantio/real-user-data-sdk-js

Include module in your application as ES6 module

import * as rciSdk from '@eggplantio/real-user-data-sdk-js';

Use from CDN

You can load specific version of package from AWS CDN. Then include this script in your page code.

You can use our latest tag to be always up-to-date with our last version of real-user-data-sdk library.

<script src="https://sdk.real-user-data.eggplant.cloud/latest/rci.min.js"></script>

Or if you want to stick with a certain version you can bind to a specific version by using the following code:

<script src="https://sdk.real-user-data.eggplant.cloud/v1.0.8/rci.min.js"></script>

Where v1.0.8 is the version of your choosing.

Save sources to project

Copy dist/rci.min.js file to your project and load it.

<script src="rci.min.js"></script>

JS SDK

Producer

A producer is a class which executes all the Collectors provided. It expects a Transport and collection of Collectors. When collect is called, the event is prepared and then sent using the Transport.

Collectors

A function, object or class with an async prepare method. The prepare method is given an event and is expected to return an augmented event.

Default Collectors

The default collection (array) of Collectors provided by the SDK. New Collectors can be merged with the default Collectors to compose unique sequences of collection.

Web Based Collectors

You can use the web focused collectors in 2 manners:

either one by one
either using the web focused collectors collection

Using it one by one

This is particularly useful if you want to choose only certain collectors that you might need for your custom implementation.

So to achieve the integration with the web collectors you can do something like this before calling the RCI SDK bootstrap method with the collectors array.

  // Step 1: Capture your default collectors
  const defaults = rciSdk.collector.defaultCollectors;

  // Step 2: Capture WebFocusedCollectors
  const webFocusedCollectors =
      [
        new rciSdk.collector.WebBackEndCollector(),
        new rciSdk.collector.WebPageLoadTimesCollector(),
        new rciSdk.collector.WebVitalsCollector()
      ];

  // Step 3: Create the final collectors collection
  const finalCollectorCollection = defaults.concat(webFocusedCollectors);

Note that the WebPaintTimesCollector was left out on purpose to exemplify the flexibility of this method of adding the web focused collectors.

Using the web collectors collection

If you want to just get the full web focused package you can just the use the pre-existing collectors collection prepared within the framework. Keep in mind that is mainly for convenience but is sacrificing the flexibility factor.

To do so you can have this code before injecting the array of collectors into the bootstrapper.

  // Step 1: Capture your default collectors
  const defaults = rciSdk.collector.defaultCollectors;

  // Step 2: Capture WebFocusedCollectors
  const {webFocusedCollectors} = rciSdk.collector;

  // Step 3: Create the final collectors collection
  const finalCollectorCollection = defaults.concat(webFocusedCollectors);

Normalization Helper

Normalizing currency values

A goal value normalized is offered via our Normalization Helper. Be aware that this will only work if your goal type is of the type "purchase". If the value you want to send to the cloud is directly in the main currency unit like EUR, GBP, USD and so on, you can normalize it by calling the method like this:

NormalizationHelper.normalizeGoalValue(948.34);
// output: 94834

If your value is directly in pence, cents and so on, you can set the fullUnit flag on false and the value will be left as is and the denominations will be cut

NormalizationHelper.normalizeGoalValue(948.34, false);
// output: 948

Transport

A class which knows how to send the event to the target destination when the async method execute is called.

The transport can be set up in 2 ways:

the new way that supports multiple tenancies and can send the captured event to multiple locations in one go
the legacy way (that has a targetURL passed to it) that only supports one tenancy and can send the captured event to one location in one go

New way to setup

In order to setup the transport you need to pass the following parameters to the transport constructor:

    const transport = new Transport(tenancies);

where tenancies is an array of tenancies looking like this:

  const tenancies = [
    {
      name: 'E2E Test',
      targetUrl: 'https://target.domain/v1/111-222/stream',
      tenancyId: '111-222',
      target: {
        targetedData: "URLPathName",
        searchMode: "regex",
        searchValue: '.+(\/test\/).+'
      }
    },
    {
      name: 'Beacon Generator 1',
      targetUrl: 'https://target.domain/v1/333-444/stream',
      tenancyId: '333-444',
      target: {
        targetedData: "fullURL",
        searchMode: "regex",
        searchValue: '.+(\/somethingElse\/).+'
      }
    }
  ];

The event will be sent to all matching tenancies.

The naive search engine supports multiple targeted data sources:

fullURL: The full URL. Example: "https://www.example.com/test/"
URLHost: The host of the URL. Example: "www.example.com" (Note: This includes the port if available)
URLPathName: The path name of the URL. Example: "/test/"
URLSearch: The search part of the URL. Example: "?lorem=ipsum"
CanonicalLinks: The canonical links of the page. Example: "https://www.example.com/test/" (Note, this is assuming that are implemented correctly with rel attribute being available)

Search-wise, it supports the following modes:

perfectMatch: The search value must be exactly the same as the targeted data. Example: "https://www.example.com/test/" in "https://www.example.com/test/"
partialMatch: The search value is a substring of the targeted data. Example: "test" in "https://www.example.com/test/"
regex: The search value is a regular expression. Example: "/.+(\/test\/).+/"

Old way to setup

In order to setup the transport in the legacy way you need to pass an targetURL transport constructor:

    const transport = new Transport("https://www.beaconStore.com/test/");

The data will be sent to "https://www.beaconStore.com/test/"

Triggering mechanism

There are 2 ways in which you can trigger events which should be judged case by case.

Data based case

The first case is when your event is dependent on some data being populated. For this particular case we prepared a TriggerHelper class which will check your required data till it gets populated and then when it has everything it will trigger an event. It is basically a glorified for loop with timeouts.

The use of this is detailed in /examples/Vanilla/OnLoad/conversion.js. It basically accepts the following

interval (How often it should check for changes in data)
timeout (When it should time out, e.g. if you have interval set to 10 and timeout set to 1000, the condition will be checked 100 times and then the event will be sent anyway with whatever data has in place)
producer - the class instance that has the "collect" method ready to be triggered
event (Optional) - this is in case you want to collect any data from a particular event (If it is triggered from an event)
condition - Reference of the function that checks for the data
action - Reference of the function that performs the sending of event action

Event based case

When the core is loaded successfully, an event is triggered on the window object that the implementer or the instrumentation can bind on when the instrumentation is bootstrapped. Also an additional property with the name of the same event is set on the window object in order for the instrumentation to not wait for the core to emit if the core is already present on the page

This can be used in the following manner:

if (window.hasOwnProperty('RCICoreReady')) {
    // Trigger the RCI instrumentation bootstrap process straight away
} else {
    // Bind on event and wait for dispatch 
    window.addEventListener("RCICoreReady", function(e) {
         // Trigger the RCI instrumentation when the event is emitted
    });
}

Support IE 11 and older phones

To support IE11 you need to compile source in legacy mode.

webpack --config=config/webpack.js --env=scope=core --env=rulesTarget=legacy --env=mode=production

current build supports last 2 most recent versions of browsers, while legacy aim to support all browsers up to IE11 while maintaining same functionality. The difference in result files are 25kB (current) vs 50kB (legacy).

Contributing

The main purpose of this repository is to continue to evolve rci event collector, making it faster and easier to use. Development of this SDK happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements, raising issues and suggesting new features. Read below to learn how you can take part in it.

Code of Conduct

This SDK has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Running the tests

The project has 2 types of tests to ensure the quality of the code and the stability of the project.

One suite of end-to-end tests that are available alongside the code that is being tested. Using the following:

Jest as the generic testing framework, using the inbuilt assertion library.
Sinon used for mocking various internal components and providing a stable interface for components that are outside the scope of the project.

The other suite, is the end-to-end tests that are available in the ./tests folder. This suite is using the following tools:

Puppeteer as the browser driver.
Express as the web server used to serve the assets
Mocha as the testing framework
Chai as the assertion library

Conveniently, there are commands to run the unit tests as well as the end-to-end tests within ./package.json.

In order to run the unit tests, you can use the following command:

npm run test:unit

In order to run the end-to-end tests, you can use the following command:

npm run test:e2e

In order to run the unit tests and the end-to-end tests together, you can use the following command:

npm run test

Contributors

Questions

For questions and support please use the official contact us page.

Issues

Please make sure to read the existing issues and new issue template before opening one. Issues not conforming to the guidelines may be closed immediately.