API.md

Modules

series

This module provides a list of standardized series for use in analyzing web experiences. each series can be registered with a name using DataChunks.addSeries(name, series).

Classes

DataChunks

Constants

facets

facetFns

A collection of facet factory functions. Each function takes one or more parameters and returns a facet function according to the parameters.

Functions

seriesValueFn(bundle) ⇒ number | undefined

A series value function calculates the series value of a bundle. If no value is returned, then the bundle will not be considered for the series.

eventFilterFn(event) ⇒ boolean

bundleFilter(bundle) ⇒ boolean

A filter function that will return true for matching bundles and false for non-matching bundles.

skipFilterFn(attributeName) ⇒ boolean

Function used for skipping certain filtering attributes. The logic of the function depends on the context, for instance when filtering bundles, this function is chained as a filter function in order to skip certain attributes.

existenceFilterFn(attributeName) ⇒ boolean

Function used for whitelist filtering attributes. The logic of the function depends on the context, for instance when filtering bundles, this function is chained as a filter function in order to ditch attributes.

valuesExtractorFn(attributeName, bundle, parent) ⇒ boolean

Function used for extracting the values for a certain attribute out of a dataset specific to the context.

combinerExtractorFn(attributeName, parent) ⇒ string

Function used for inferring the combiner that's going to be used when filtering attributes.

groupByFn(bundle) ⇒ Array.<string> | string | undefined

A grouping function returns a group name or undefined for each bundle, according to the group that the bundle belongs to.

linearRegression(data) ⇒ Line

Peform a linear ordinary squares regression against an array. This regression takes the array index as the independent variable and the data in the array as the dependent variable.

zTestTwoProportions(sample1, conversions1, sample2, conversions2) ⇒ number

Performs a Z Test between two proportions. This test assumes that the data is normally distributed and will calculate the p-value for the difference between the two proportions.

erf(x)

The error function, also known as the Gauss error function.

calcMeanVariance(data) ⇒ MeanVariance

Calculate mean and variance of a dataset.

samplingError(total, samples)

Determines the sampling error based on a binomial distribution. Each sample is a Bernoulli trial, where the probability of success is the proportion of the total population that has the attribute of interest. The sampling error is calculated as the standard error of the proportion.

tTest(left, right) ⇒ number

Performs a significance test on the data. The test assumes that the data is normally distributed and will calculate the p-value for the difference between the two data sets.

toHumanReadable(num, precision) ⇒ String

Returns a human readable number

computeConversionRate(conversions, visits) ⇒ number

Conversion rates are computed as the ratio of conversions to visits. The conversion rate is capped at 100%.

addCalculatedProps(bundle) ⇒ Bundle

Calculates properties on the bundle, so that bundle-level filtering can be performed

Typedefs

RawEvent : Object

a raw RUM event

RawBundle : Object

a raw bundle of events, all belonging to the same page view

Bundle : Object

a processed bundle of events, with extra properties

RawChunk : Object

a list of raw, unprocessed bundles as delivered by the endpoint

Aggregate : Object

an object that contains aggregate metrics

Totals ⇐ Object<string,

A total is an object that contains {Metric} objects for each defined series.

FacetFn ⇒ Array.<string>

A facet function takes a bundle and returns an array of facet values.

Line : Object

MeanVariance : Object

series

This module provides a list of standardized series for use in analyzing web experiences. each series can be registered with a name using DataChunks.addSeries(name, series).

• series
  • .pageViews ⇒ number
  • .visits ⇒ number
  • .bounces ⇒ number
  • .lcp ⇒ number
  • .cls ⇒ number
  • .inp ⇒ number
  • .ttfb
  • .engagement ⇒ number
  • .earned ⇒ number
  • .organic ⇒ number

series.pageViews ⇒ number

A page view is an impression of a page. At this moment, pre-rendering is also considered a page view.

Kind: static constant of series
Returns: number - the number of page views

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.visits ⇒ number

A visit is a page view that does not follow an internal link. This means a visit starts when users follow an external link or enter the URL in the browser.

Kind: static constant of series
Returns: number - the number of visits

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.bounces ⇒ number

A bounce is a visit that does not have any click events.

Kind: static constant of series
Returns: number - the number of bounces

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.lcp ⇒ number

The largest contentful paint is the time it takes for the largest contentful element to load.

Kind: static constant of series
Returns: number - the largest contentful paint

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.cls ⇒ number

The cumulative layout shift is the sum of all layout shifts in a page view.

Kind: static constant of series
Returns: number - the cumulative layout shift

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.inp ⇒ number

The interaction to next paint is the time it takes for the next paint after an interaction.

Kind: static constant of series
Returns: number - the interaction to next paint

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.ttfb

The time to first byte is the time it takes for the first byte to arrive.

Kind: static constant of series

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.engagement ⇒ number

A page view is considered engaged if there has been at least some user interaction or significant content has been viewed, i.e. 4 or more viewmedia or viewblock events.

Kind: static constant of series
Returns: number - the number of engaged page views

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.earned ⇒ number

The number of earned visits is the number of visits that are not paid or owned.

Kind: static constant of series
Returns: number - the number of earned conversions

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

series.organic ⇒ number

The number of organic visits is the number of visits that are not paid.

Kind: static constant of series
Returns: number - the number of earned conversions

Param	Type	Description
bundle	Bundle	a series of events that belong to the same page view

DataChunks

Kind: global class

• DataChunks
  • new DataChunks()
  • .bundles ⇒ Array.<Bundle>
  • .filter
  • .aggregates ⇒ Object.<string, Totals>
  • .totals ⇒ Totals
  • .facets ⇒ Object.<string, Array.<Facet>>
  • .addSeries(seriesName, seriesValueFn)
  • .addInterpolation(seriesName, sourceSeries, interpolationFn)
  • .addFacet(facetName, facetValueFn, facetCombiner, negativeCombiner)
  • .addHistogramFacet(facetName, baseFacet, bucketOptions, formatter)
  • .load(chunks)
  • .addData(chunks)
  • .hasConversion(aBundle, filterSpec, combiner) ⇒ boolean
  • .group(groupByFn) ⇒ Object.<string, Array.<Bundle>>

new DataChunks()

This class is used to filter, group, and aggregate data from RUM events.

dataChunks.bundles ⇒ Array.<Bundle>

Kind: instance property of DataChunks
Returns: Array.<Bundle> - all bundles, regardless of the chunk they belong to

dataChunks.filter

Defines what filter to apply to the data. The filter is an object that specifies the valid values for each defined facet. Filter values are the same values that can get returned by the valueFn that has been added with addFacet.

Kind: instance property of DataChunks

Param	Type	Description
filterSpec	Object.<string, Array.<string>>	the filter specification

dataChunks.aggregates ⇒ Object.<string, Totals>

Aggregates the grouped data into series data. Each series has been provided by addSeries and will be used to calculate the value of each bundle in the group. The aggregated data will be stored in the seriesIn[groupName][seriesName] object. Each result will be an object with the following properties:

• count
• sum
• min
• max
• mean
• percentile(p)

Kind: instance property of DataChunks
Returns: Object.<string, Totals> - series data

dataChunks.totals ⇒ Totals

Aggregates the filtered data into totals. The totals will be stored in the totalIn object. The result will be an object with one key for each series that has been added with addSeries. Each value will be an object with the following properties:

• count
• sum
• min
• max
• mean
• percentile(p)

Kind: instance property of DataChunks
Returns: Totals - total data

dataChunks.facets ⇒ Object.<string, Array.<Facet>>

Calculates facets for all data. For each function added through addFacet, it will determine the most common values, their frequency and their weight. The result will be an object with one key for each facet, containining an array of facet objects.

Kind: instance property of DataChunks
Returns: Object.<string, Array.<Facet>> - facets data

dataChunks.addSeries(seriesName, seriesValueFn)

A series is a named list of values, which are calculated for each bundle in the data set.

Kind: instance method of DataChunks

Param	Type	Description
seriesName	string	name of the series
seriesValueFn	seriesValueFn	function that returns the series value for each bundle

dataChunks.addInterpolation(seriesName, sourceSeries, interpolationFn)

An interpolation is a series that is calulated based on the aggrega values of other series. The interpolation function will receive the list of source series and an interpolation function that will return the interpolated value. The interpolation function will have as many arguments as there are source series.

Kind: instance method of DataChunks

Param	Type	Description
seriesName	string	name of the (interpolated) series
sourceSeries	Array.<string>	list of source series to interpolate from
interpolationFn	function

dataChunks.addFacet(facetName, facetValueFn, facetCombiner, negativeCombiner)

A facet function works on the entire data set.

Kind: instance method of DataChunks

Param	Type	Default	Description
facetName	string		name of the facet
facetValueFn	groupByFn		function that returns the facet value – can return multiple values
facetCombiner	string	"some"	how to combine multiple values, default is 'some', can be 'every'
negativeCombiner	string		how to combine multiple values for the negative facet, possible values are 'none' and 'never'. Only when this parameter is set, a negative facet will be created.

dataChunks.addHistogramFacet(facetName, baseFacet, bucketOptions, formatter)

Adds a histogram facet, derived from an existing facet. This facet will group the data into buckets, based on the values of the base facet. You can specify the bucket size, limits and the type of bucketing.

Kind: instance method of DataChunks

Param	Type	Description
facetName	string	name of your new facet
baseFacet	string	name of the base facet, from which to derive the histogram
bucketOptions	object
bucketOptions.count	number	number of buckets
bucketOptions.min	number	minimum value of the histogram
bucketOptions.max	number	maximum value of the histogram
bucketOptions.steps	'linear' | 'logarithmic' | 'quantiles'	type of bucketing, can be 'linear' (each bucket has the same value range), 'logarithmic' (same value range on logarithmic scale), or 'quantiles' (buckets are roughly equal in size based on the current facet values, but the bucket min/max values are less predictable)
formatter	function	a number formatter

dataChunks.load(chunks)

Load raw chunks. This will replace data that has been loaded before

Kind: instance method of DataChunks

Param	Type	Description
chunks	Array.<RawChunk>	the raw data to load, an array of chunks

dataChunks.addData(chunks)

Load more data. This will amend the data that has been loaded before

Kind: instance method of DataChunks

Param	Type	Description
chunks	RawChunk	the raw data to load, an array of chunks

dataChunks.hasConversion(aBundle, filterSpec, combiner) ⇒ boolean

Checks if a conversion has happened in the bundle. A conversion means a business metric that has been achieved, for instance a click on a certain link.

Kind: instance method of DataChunks
Returns: boolean - the result of the check.

Param	Type	Description
aBundle	Bundle	the bundle to check.
filterSpec	Object.<string, Array.<string>>	uses the same format as the filter specification. For instance { checkpoint: ['click'] } means that inside a bundle an event that has the checkpoint attribute set to 'click' must exist.
combiner	string	used to determine if all or some filters must match. By default, 'every' is used.

dataChunks.group(groupByFn) ⇒ Object.<string, Array.<Bundle>>

Groups the filteredIn data by the groupFn. The groupFn should return a string that will be used as the key for the group. If the groupFn returns a falsy value, the bundle will be skipped.

Kind: instance method of DataChunks
Returns: Object.<string, Array.<Bundle>> - grouped data, each key is a group and each vaule is an array of bundles

Param	Type	Description
groupByFn	groupByFn	for each object, determine the group key

facets

Kind: global constant
Import: Bundle from './distiller.js'

• facets
  • .userAgent(bundle) ⇒ Array.<string>
  • .url(bundle) ⇒ string
  • .checkpoint(bundle) ⇒ Array.<string>
  • .vitals(bundle) ⇒ Array.<string>
  • .lcpTarget(bundle) ⇒ Array.<string>
  • .lcpSource(bundle) ⇒ Array.<string>
  • .acquisitionSource(bundle) ⇒ Array.<string>
  • .enterSource(bundle) ⇒ Array.<string>
  • .mediaTarget(bundle) ⇒ Array.<string>

facets.userAgent(bundle) ⇒ Array.<string>

Extracts each of device type and operating system from the simplified user agent string.

Kind: static method of facets
Returns: Array.<string> - a list of device types and operating systems

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.url(bundle) ⇒ string

Extracts the path from the URL and removes potential PII such as ids, hashes, and other encoded data.

Kind: static method of facets
Returns: string - the path of the URL

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.checkpoint(bundle) ⇒ Array.<string>

Extracts the checkpoints from the bundle. Each checkpoint that occurs at least once in the bundle is returned as a facet value.

Kind: static method of facets
Returns: Array.<string> - a list of checkpoints

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.vitals(bundle) ⇒ Array.<string>

Classifies the bundle according to the Core Web Vitals metrics. For each metric in LCP, CLS, and INP, the score is calculated as good, needs improvement, or poor. The result is a list of the form [goodLCP, niCLS, poorINP]

Kind: static method of facets
Returns: Array.<string> - a list of CWV metrics

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.lcpTarget(bundle) ⇒ Array.<string>

Extracts the target of the Largest Contentful Paint (LCP) event from the bundle.

Kind: static method of facets
Returns: Array.<string> - a list of LCP targets

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.lcpSource(bundle) ⇒ Array.<string>

Extracts the source of the Largest Contentful Paint (LCP) event from the bundle.

Kind: static method of facets
Returns: Array.<string> - a list of LCP sources

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.acquisitionSource(bundle) ⇒ Array.<string>

Extracts the acquisition source from the bundle. As acquisition sources can be strings like paid:video:youtube, each of paid, paid:video, and paid:video:youtube are returned as separate values.

Kind: static method of facets
Returns: Array.<string> - a list of acquisition sources

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.enterSource(bundle) ⇒ Array.<string>

Classifies the referrer page of the enter event.

Kind: static method of facets
Returns: Array.<string> - a list of referrer classifications, following the pattern:

• the original source URL
• the type and vendor of the referrer, e.g. search:google
• the type of the referrer, e.g. search
• the vendor of the referrer, regardless of type, e.g. *:google

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facets.mediaTarget(bundle) ⇒ Array.<string>

Extracts the target of the media view event from the bundle. This is typically the URL of an image or video, and the URL is stripped of query parameters, hash, user, and password.

Kind: static method of facets
Returns: Array.<string> - a list of media targets

Param	Type	Description
bundle	Bundle	the bundle of sampled rum events

facetFns

A collection of facet factory functions. Each function takes one or more parameters and returns a facet function according to the parameters.

Kind: global constant

• facetFns
  • .checkpointSource(cp) ⇒ FacetFn
  • .checkpointTarget(cp) ⇒ FacetFn

facetFns.checkpointSource(cp) ⇒ FacetFn

Returns a function that creates a facet function for the source of the given checkpoint.

Kind: static method of facetFns
Returns: FacetFn - - a facet function

Param	Type	Description
cp	string	the checkpoint

facetFns.checkpointTarget(cp) ⇒ FacetFn

Returns a function that creates a facet function for the target of the given checkpoint.

Kind: static method of facetFns
Returns: FacetFn - a facet function

Param	Type	Description
cp	string	the checkpoint

seriesValueFn(bundle) ⇒ number | undefined

A series value function calculates the series value of a bundle. If no value is returned, then the bundle will not be considered for the series.

Kind: global function
Returns: number | undefined - the series value or undefined

Param	Type	Description
bundle	Bundle	the bundle to calculate the series value for

eventFilterFn(event) ⇒ boolean

Kind: global function
Returns: boolean - true if the event should be included

Param	Type	Description
event	Event	the event to check

bundleFilter(bundle) ⇒ boolean

A filter function that will return true for matching bundles and false for non-matching bundles.

Kind: global function
Returns: boolean - true if the bundle matches the filter

Param	Type	Description
bundle	Bundle	the bundle to check

skipFilterFn(attributeName) ⇒ boolean

Function used for skipping certain filtering attributes. The logic of the function depends on the context, for instance when filtering bundles, this function is chained as a filter function in order to skip certain attributes.

Kind: global function
Returns: boolean - true if the attribute should be included or not.

Param	Type	Description
attributeName	string	the name of the attribute to skip.

existenceFilterFn(attributeName) ⇒ boolean

Function used for whitelist filtering attributes. The logic of the function depends on the context, for instance when filtering bundles, this function is chained as a filter function in order to ditch attributes.

Kind: global function
Returns: boolean - true if the attribute should be included or not.

Param	Type	Description
attributeName	string	the name of the whitelisted attribute.

valuesExtractorFn(attributeName, bundle, parent) ⇒ boolean

Function used for extracting the values for a certain attribute out of a dataset specific to the context.

Kind: global function
Returns: boolean - true if the attribute should be included or not.

Param	Type	Description
attributeName	string	the name of the attribute to extract.
bundle	Bundle	the dataset to extract the attribute from.
parent	DataChunks	the parent object that contains the bundles.

combinerExtractorFn(attributeName, parent) ⇒ string

Function used for inferring the combiner that's going to be used when filtering attributes.

Kind: global function
Returns: string - 'some' or 'every'.

Param	Type	Description
attributeName	string	the name of the attribute to extract.
parent	DataChunks	the parent object that contains the bundles.

groupByFn(bundle) ⇒ Array.<string> | string | undefined

A grouping function returns a group name or undefined for each bundle, according to the group that the bundle belongs to.

Kind: global function
Returns: Array.<string> | string | undefined - the group name(s) or undefined

Param	Type	Description
bundle	Bundle	the bundle to check

linearRegression(data) ⇒ Line

Peform a linear ordinary squares regression against an array. This regression takes the array index as the independent variable and the data in the array as the dependent variable.

Kind: global function
Returns: Line - the slope and intercept of the regression function

Param	Type	Description
data	Array.<number>	an array of input data

zTestTwoProportions(sample1, conversions1, sample2, conversions2) ⇒ number

Performs a Z Test between two proportions. This test assumes that the data is normally distributed and will calculate the p-value for the difference between the two proportions.

Kind: global function
Returns: number - the p-value, a value between 0 and 1

Param	Type	Description
sample1	number	the sample size of the first group (e.g. total number of visitors)
conversions1	number	the number of conversions in the first group
sample2	number	the sample size of the second group
conversions2	number	the number of conversions in the second group

erf(x)

The error function, also known as the Gauss error function.

Kind: global function

Param	Type	Description
x	number	the value to calculate the error function for

calcMeanVariance(data) ⇒ MeanVariance

Calculate mean and variance of a dataset.

Kind: global function
Returns: MeanVariance - mean and variance of the input dataset

Param	Type	Description
data	Array.<number>	the input data

samplingError(total, samples)

Determines the sampling error based on a binomial distribution. Each sample is a Bernoulli trial, where the probability of success is the proportion of the total population that has the attribute of interest. The sampling error is calculated as the standard error of the proportion.

Kind: global function

Param	Type	Description
total	number	the expectation value of the total population
samples	number	the number of successful trials (i.e. samples)

tTest(left, right) ⇒ number

Performs a significance test on the data. The test assumes that the data is normally distributed and will calculate the p-value for the difference between the two data sets.

Kind: global function
Returns: number - the p-value, a value between 0 and 1

Param	Type	Description
left	Array.<number>	the first data set
right	Array.<number>	the second data set

toHumanReadable(num, precision) ⇒ String

Returns a human readable number

Kind: global function
Returns: String - a human readable number

Param	Type	Description
num	Number	a number
precision	Number	the number of significant digits

computeConversionRate(conversions, visits) ⇒ number

Conversion rates are computed as the ratio of conversions to visits. The conversion rate is capped at 100%.

Kind: global function
Returns: number - the conversion rate as a percentage

Param	Description
conversions	the number of conversions
visits	the number of visits

addCalculatedProps(bundle) ⇒ Bundle

Calculates properties on the bundle, so that bundle-level filtering can be performed

Kind: global function
Returns: Bundle - a bundle with additional properties

Param	Type	Description
bundle	RawBundle	the raw input bundle, without calculated properties

RawEvent : Object

a raw RUM event

Kind: global typedef
Properties

Name	Type	Description
checkpoint	string	the name of the event that happened
target	string | number	the target of the event, typically an external URL
source	string	the source of the event, typically a CSS selector
value	number	the value of a CWV metric
timeDelta	number	– the difference in milliseconds between this event's time and the containing bundle's timestamp

RawBundle : Object

a raw bundle of events, all belonging to the same page view

Kind: global typedef
Properties

Name	Type	Description
id	string	the unique identifier of the bundle. IDs can duplicate across bundles
host	string	the hostname that the page view was made to
time	string	exact time of the first event in the bundle, in ISO8601 format
timeSlot	string	the hourly timesot that this bundle belongs to
url	string	the URL of the request, without URL parameters
userAgent	string	the user agent class, for instance desktop:windows or mobile:ios
hostType	string	the type of host, for instance 'helix' or 'aemcs'
weight	number	the weight, or sampling ratio 1:n of the bundle
events	RawEvent	the list of events that make up the bundle

Bundle : Object

a processed bundle of events, with extra properties

Kind: global typedef
Extends: RawBundle
Properties

Name	Type	Description
visit	boolean	does this bundle start a visit
conversion	boolean	did a conversion happen in this visit
cwvINP	number	interaction to next paint, for the entire bundle
cwvLCP	number	largest contentful paint, for the entire bundle
cwvCLS	number	cumulative layout shift, for the entire bundle
ttfb	number	time to first byte, for the entire bundle

RawChunk : Object

a list of raw, unprocessed bundles as delivered by the endpoint

Kind: global typedef
Properties

Name	Type	Description
date	string	the base date of all bundles in the chunk
rumBundles	Array.<RawBundle>	the bundles, as retrieved from the server

Aggregate : Object

an object that contains aggregate metrics

Kind: global typedef

Totals ⇐ Object<string,

A total is an object that contains {Metric} objects for each defined series.

Kind: global typedef
Extends: Object<string,

FacetFn ⇒ Array.<string>

A facet function takes a bundle and returns an array of facet values.

Kind: global typedef
Returns: Array.<string> - Array of facet values

Param	Type	Description
bundle	Bundle	The bundle to process

Line : Object

Kind: global typedef
Properties

Name	Type	Description
slope	number	the slope of the linear function, i.e. increase of y for every increase of x
intercept	number	the intercept of the linear function, i.e. the value of y for x equals zero

MeanVariance : Object

Kind: global typedef
Properties

Name	Type	Description
mean	number	the mean of a dataset
variance	number	the variance of a dataset