@adobe/rum-distiller - npm Package Compare versions

Comparing version 1.6.1 to 1.7.0

API.md

@@ -18,2 +18,13 @@ ## Modules
 
+## Constants
+
+<dl>
+<dt><a href="#facets">facets</a></dt>
+<dd></dd>
+<dt><a href="#facetFns">facetFns</a></dt>
+<dd><p>A collection of facet factory functions. Each function takes one or more
+parameters and returns a facet function according to the parameters.</p>
+</dd>
+</dl>
+
 ## Functions
@@ -117,2 +128,5 @@
 </dd>
+<dt><a href="#FacetFn">FacetFn</a> ⇒ <code>Array.&lt;string&gt;</code></dt>
+<dd><p>A facet function takes a bundle and returns an array of facet values.</p>
+</dd>
 <dt><a href="#Line">Line</a> : <code>Object</code></dt>
@@ -476,2 +490,180 @@ <dd></dd>
 
+<a name="facets"></a>
+
+## facets
+**Kind**: global constant  
+**Import**: [<code>Bundle</code>](#Bundle) from './distiller.js'  
+
+* [facets](#facets)
+    * [.userAgent(bundle)](#facets.userAgent) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.url(bundle)](#facets.url) ⇒ <code>string</code>
+    * [.checkpoint(bundle)](#facets.checkpoint) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.vitals(bundle)](#facets.vitals) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.lcpTarget(bundle)](#facets.lcpTarget) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.lcpSource(bundle)](#facets.lcpSource) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.acquisitionSource(bundle)](#facets.acquisitionSource) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.enterSource(bundle)](#facets.enterSource) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.mediaTarget(bundle)](#facets.mediaTarget) ⇒ <code>Array.&lt;string&gt;</code>
+
+<a name="facets.userAgent"></a>
+
+### facets.userAgent(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+Extracts each of device type and operating system from
+the simplified user agent string.
+
+**Kind**: static method of [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - a list of device types and operating systems  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.url"></a>
+
+### facets.url(bundle) ⇒ <code>string</code>
+Extracts the path from the URL and removes potential PII such as
+ids, hashes, and other encoded data.
+
+**Kind**: static method of [<code>facets</code>](#facets)  
+**Returns**: <code>string</code> - the path of the URL  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.checkpoint"></a>
+
+### facets.checkpoint(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+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 [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - a list of checkpoints  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.vitals"></a>
+
+### facets.vitals(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+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 [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - a list of CWV metrics  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.lcpTarget"></a>
+
+### facets.lcpTarget(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+Extracts the target of the Largest Contentful Paint (LCP) event from the bundle.
+
+**Kind**: static method of [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - a list of LCP targets  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.lcpSource"></a>
+
+### facets.lcpSource(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+Extracts the source of the Largest Contentful Paint (LCP) event from the bundle.
+
+**Kind**: static method of [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - a list of LCP sources  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.acquisitionSource"></a>
+
+### facets.acquisitionSource(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+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 [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - a list of acquisition sources  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.enterSource"></a>
+
+### facets.enterSource(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+Classifies the referrer page of the enter event.
+
+**Kind**: static method of [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - 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 | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facets.mediaTarget"></a>
+
+### facets.mediaTarget(bundle) ⇒ <code>Array.&lt;string&gt;</code>
+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 [<code>facets</code>](#facets)  
+**Returns**: <code>Array.&lt;string&gt;</code> - a list of media targets  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | the bundle of sampled rum events |
+
+<a name="facetFns"></a>
+
+## 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](#facetFns)
+    * [.checkpointSource(cp)](#facetFns.checkpointSource) ⇒ [<code>FacetFn</code>](#FacetFn)
+    * [.checkpointTarget(cp)](#facetFns.checkpointTarget) ⇒ [<code>FacetFn</code>](#FacetFn)
+
+<a name="facetFns.checkpointSource"></a>
+
+### facetFns.checkpointSource(cp) ⇒ [<code>FacetFn</code>](#FacetFn)
+Returns a function that creates a facet function for the source of the given
+checkpoint.
+
+**Kind**: static method of [<code>facetFns</code>](#facetFns)  
+**Returns**: [<code>FacetFn</code>](#FacetFn) - - a facet function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| cp | <code>string</code> | the checkpoint |
+
+<a name="facetFns.checkpointTarget"></a>
+
+### facetFns.checkpointTarget(cp) ⇒ [<code>FacetFn</code>](#FacetFn)
+Returns a function that creates a facet function for the target of the given
+checkpoint.
+
+**Kind**: static method of [<code>facetFns</code>](#facetFns)  
+**Returns**: [<code>FacetFn</code>](#FacetFn) - a facet function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| cp | <code>string</code> | the checkpoint |
+
 <a name="seriesValueFn"></a>
@@ -789,2 +981,14 @@
 **Extends**: <code>Object&lt;string,</code>  
+<a name="FacetFn"></a>
+
+## FacetFn ⇒ <code>Array.&lt;string&gt;</code>
+A facet function takes a bundle and returns an array of facet values.
+
+**Kind**: global typedef  
+**Returns**: <code>Array.&lt;string&gt;</code> - Array of facet values  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| bundle | [<code>Bundle</code>](#Bundle) | The bundle to process |
+
 <a name="Line"></a>
@@ -791,0 +995,0 @@

CHANGELOG.md

@@ -0,1 +1,14 @@
+# [1.7.0](https://github.com/adobe/rum-distiller/compare/v1.6.1...v1.7.0) (2024-11-18)
+
+
+### Bug Fixes
+
+* **referrer:** classify video referrers, tiktok isn't a social network ([7542981](https://github.com/adobe/rum-distiller/commit/754298175544cf9914f71c3b2822fc7ced761229))
+
+
+### Features
+
+* **facets:** add enterSource facet, which is based on the referrer classification ([6cbbf55](https://github.com/adobe/rum-distiller/commit/6cbbf55533e7c479cd241efa4fac96ab0978fa06))
+* **referrer:** add referrer classification ([ce704c3](https://github.com/adobe/rum-distiller/commit/ce704c361f1f4798d6ea30e9419fd8e362ceedf3))
+
 ## [1.6.1](https://github.com/adobe/rum-distiller/compare/v1.6.0...v1.6.1) (2024-11-14)
@@ -2,0 +15,0 @@

facets.js

@@ -13,2 +13,3 @@ /*
 import { reclassifyConsent, reclassifyAcquisition, scoreCWV } from './utils.js';
+import { classifyReferrer } from './referrer.js';
 /**
@@ -145,2 +146,25 @@ * @import {Bundle} from './distiller.js'
   /**
+   * Classifies the referrer page of the enter event.
+   * @param {Bundle} bundle the bundle of sampled rum events
+   * @returns {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`
+   */
+  enterSource: (bundle) => bundle.events
+    .filter((evt) => evt.checkpoint === 'enter')
+    .map((evt) => evt.source)
+    .filter((source) => source)
+    .map((source) => {
+      const referrerClass = classifyReferrer(source);
+      return referrerClass ? [
+        source,
+        `${referrerClass.type}:${referrerClass.vendor}`,
+        referrerClass.type,
+        `*:${referrerClass.vendor}`,
+      ] : source;
+    })
+    .flat(),
+  /**
    * Extracts the target of the media view event from the bundle. This
@@ -170,3 +194,11 @@ * is typically the URL of an image or video, and the URL is stripped
 };
+
 /**
+ * A facet function takes a bundle and returns an array of facet values.
+ * @typedef {function} FacetFn
+ * @param {Bundle} bundle The bundle to process
+ * @returns {string[]} Array of facet values
+ */
+
+/**
  * A collection of facet factory functions. Each function takes one or more
@@ -179,6 +211,4 @@ * parameters and returns a facet function according to the parameters.
    * checkpoint.
-   * @param {string} cp the checkpoint
-  * @returns {
-  function(bundle: Bundle): string[]
-} a facet function
+   * @return {FacetFn} - a facet function
+   * @param {string} cp - the checkpoint
    */
@@ -199,3 +229,3 @@ checkpointSource: (cp) => (bundle) => Array.from(
    * @param {string} cp the checkpoint
-   * @returns {function(bundle: Bundle): string[]} a facet function
+   * @returns {FacetFn} a facet function
    */
@@ -202,0 +232,0 @@ checkpointTarget: (cp) => (bundle) => Array.from(

package.json

 {
   "name": "@adobe/rum-distiller",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "scripts": {
@@ -5,0 +5,0 @@ "test": "node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=junit.xml",

test/facets.test.js

@@ -199,2 +199,22 @@ /*
 
+describe('facets:enterSource', () => {
+  it('enterSource:bare', () => {
+    assert.deepEqual(facets.enterSource({ events: [{ checkpoint: 'enter', source: 'https://www.example.com' }] }), ['https://www.example.com']);
+    assert.deepEqual(facets.enterSource({ events: [{ checkpoint: 'enter', source: 'https://www.google.com' }] }), ['https://www.google.com', 'search:google', 'search', '*:google']);
+  });
+
+  it('enterSource:DataChunks', () => {
+    const d = new DataChunks();
+    d.load(testChunks);
+    d.addSeries('pageViews', pageViews);
+    d.addFacet('enterSource', facets.enterSource);
+
+    assert.equal(d.facets.enterSource.length, 46);
+    assert.equal(d.facets.enterSource[2].value, 'search'); // all search engines
+    assert.equal(d.facets.enterSource[3].value, 'search:google'); // google search
+    assert.equal(d.facets.enterSource[4].value, '*:google'); // all google properties
+    assert.equal(d.facets.enterSource[5].value, 'https://www.google.com/'); // that one specific google page
+  });
+});
+
 describe('facets:mediaTarget', () => {
@@ -201,0 +221,0 @@ it('mediaTarget:bare', () => {

No alert changes

Improved metrics

Total package byte prevSize

2880300

increased by0.92%

Number of package files

28

increased by7.69%

Lines of code

90487

increased by0.66%

No dependency changes