@contentful/optimization-web 0.1.0-alpha → 0.1.0-alpha5

package/README.md

@@ -28,6 +28,7 @@ This SDK implements functionality specific to the Web environment, based on the
 <!-- mtoc-start -->
 
 - [Getting Started](#getting-started)
+  - [Usage in Vanilla JS Web Pages](#usage-in-vanilla-js-web-pages)
 - [Reference Implementations](#reference-implementations)
 - [Configuration](#configuration)
   - [Top-level Configuration Options](#top-level-configuration-options)
@@ -79,12 +80,25 @@ Import the Optimization class; both CJS and ESM module systems are supported, ES
 import Optimization from '@contentful/optimization-web'
 ```
 
-Configure and initialize the Optimization Node SDK:
+Configure and initialize the Optimization Web SDK:
 
 ```ts
 const optimization = new Optimization({ clientId: 'abc123' })
 ```
 
+### Usage in Vanilla JS Web Pages
+
+Alternatively, the Web SDK can be used directly within an HTML file:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@contentful/optimization-web@latest/dist/contentful-optimization-web.umd.js"></script>
+<script>
+  new Optimization({ clientId: 'abc123' })
+  // is equal to:
+  // window.optimization = new Optimization({ clientId: 'abc123' })
+</script>
+```
+
 ## Reference Implementations
 
 - [Web Vanilla](/implementations/web-vanilla/README.md): Example static Web page that renders and
@@ -134,7 +148,7 @@ descendent SDKs.
 | ------------------- | --------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | `app`               | No        | `undefined`                                          | The application definition used to attribute events to a specific consumer app     |
 | `channel`           | No        | `'web'`                                              | The channel that identifies where events originate from (e.g. `'web'`, `'mobile'`) |
-| `library`           | No        | `{ name: 'Optimization Web API', version: '0.0.0' }` | The client library metadata that is attached to all events                         |
+| `library`           | No        | `{ name: 'Optimization Web SDK', version: '0.0.0' }` | The client library metadata that is attached to all events                         |
 | `getLocale`         | No        | Built-in locale resolution                           | Function used to resolve the locale for outgoing events                            |
 | `getPageProperties` | No        | Built-in page properties resolution                  | Function that returns the current page properties                                  |
 | `getUserAgent`      | No        | Built-in user agent resolution                       | Function used to obtain the current user agent string when applicable              |

package/dist/AutoEntryViewTracking.d.ts

@@ -8,6 +8,8 @@ export type CtflDataset = DOMStringMap & {
     ctflEntryId: string;
     /** Optional duplication scope key for de-duplication across views. */
     ctflDuplicationScope?: string;
+    /** Optional baseline ID associated with the personalized entry. */
+    ctflBaselineId?: string;
     /** Optional personalization/experience ID associated with the entry. */
     ctflPersonalizationId?: string;
     /** Whether this component view should be treated as sticky. */

package/dist/AutoEntryViewTracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AutoEntryViewTracking.d.ts","sourceRoot":"","sources":["../src/AutoEntryViewTracking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,+BAA+B,CAAA;AACrF,OAAO,KAAK,EACV,+BAA+B,EAC/B,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,aAAa,CAAA;AAIpB;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG;IACvC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,wEAAwE;IACxE,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,WAAW,GAAG,UAAU,CAAC,GAAG;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAAA;AAEhF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,IAAI,YAAY,CAgBzE;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,kCAAkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,IAAI,SAAS,CAI7D;AAwBD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mCAAmC,GAC7C,MAAM,YAAY,MACZ,SAAS,OAAO,EAAE,MAAM,uBAAuB,KAAG,OAAO,CAAC,IAAI,CA8CpE,CAAA;AAgBH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wCAAwC,GACnD,mBAAmB,mBAAmB,EACtC,kCAAgC,KAC/B,+BAuBD,CAAA"}
+{"version":3,"file":"AutoEntryViewTracking.d.ts","sourceRoot":"","sources":["../src/AutoEntryViewTracking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,+BAA+B,CAAA;AACrF,OAAO,KAAK,EACV,+BAA+B,EAC/B,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,aAAa,CAAA;AAIpB;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG;IACvC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wEAAwE;IACxE,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,WAAW,GAAG,UAAU,CAAC,GAAG;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAAA;AAEhF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,IAAI,YAAY,CAgBzE;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,kCAAkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,IAAI,SAAS,CAI7D;AAwBD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mCAAmC,GAC7C,MAAM,YAAY,MACZ,SAAS,OAAO,EAAE,MAAM,uBAAuB,KAAG,OAAO,CAAC,IAAI,CA8CpE,CAAA;AAgBH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wCAAwC,GACnD,mBAAmB,mBAAmB,EACtC,kCAAgC,KAC/B,+BAuBD,CAAA"}

package/dist/Optimization.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Web SDK entrypoint for Contentful Optimization.
+ *
+ * @packageDocumentation
+ * @remarks
+ * Exposes a browser-wired {@link Optimization} class built on top of {@link CoreStateful}.
+ * When executed in a browser environment, the constructor attaches a singleton instance
+ * to `window.optimization` and the class constructor to `window.Optimization` for
+ * script-tag / global usage.
+ */
 import { type App, CoreStateful, type CoreStatefulConfig } from '@contentful/optimization-core';
 import { type ElementViewElementOptions, type ElementViewObserverOptions } from './observers';
 declare global {
@@ -8,7 +18,20 @@ declare global {
         optimization?: Optimization;
     }
 }
+/**
+ * Supported cookie attributes for the Web SDK.
+ *
+ * @public
+ * @remarks
+ * These options are passed to {@link Cookies.set} when persisting the anonymous ID.
+ */
 interface CookieAttributes {
+    /**
+     * Cookie domain attribute.
+     *
+     * @remarks
+     * If omitted, the browser will scope the cookie to the current host.
+     */
     domain?: string;
     /**
      * Determines the expiration date of the cookie as the number of days until the cookie expires.
@@ -35,6 +58,12 @@ export interface OptimizationWebConfig extends CoreStatefulConfig {
      * @defaultValue `false`
      */
     autoTrackEntryViews?: boolean;
+    /**
+     * Cookie configuration used for persisting the anonymous identifier.
+     *
+     * @remarks
+     * Use this to control the cookie domain and expiration.
+     */
     cookie?: CookieAttributes;
 }
 /**
@@ -53,9 +82,29 @@ export interface OptimizationWebConfig extends CoreStatefulConfig {
  * in a browser environment.
  */
 declare class Optimization extends CoreStateful {
+    /**
+     * Observer responsible for element view/dwell-time tracking.
+     *
+     * @internal
+     */
     private elementViewObserver?;
+    /**
+     * Observer responsible for detecting entry elements added/removed in the DOM.
+     *
+     * @internal
+     */
     private elementExistenceObserver?;
+    /**
+     * Whether automatic entry view tracking is enabled.
+     *
+     * @internal
+     */
     private autoTrackEntryViews;
+    /**
+     * Cookie attributes used when persisting the anonymous identifier.
+     *
+     * @internal
+     */
     private readonly cookieAttributes?;
     /**
      * Create a new Optimization Web SDK instance.
@@ -77,6 +126,23 @@ declare class Optimization extends CoreStateful {
      * ```
      */
     constructor(config: OptimizationWebConfig);
+    /**
+     * Initialize anonymous ID state from cookies.
+     *
+     * @internal
+     * @remarks
+     * Reads the legacy anonymous ID cookie (if present), migrates to the current cookie,
+     * and ensures SDK state is reset when the persisted anonymous ID differs from the
+     * in-memory value.
+     */
+    private initializeFromCookieValues;
+    /**
+     * Persist (or clear) the anonymous ID in both cookies and {@link LocalStore}.
+     *
+     * @param value - Anonymous identifier to persist. If omitted, clears persisted state.
+     *
+     * @internal
+     */
     private setAnonymousId;
     /**
      * Enable automatic entry view tracking for elements with `data-ctfl-*`
@@ -107,6 +173,10 @@ declare class Optimization extends CoreStateful {
      * @param element - Element to observe.
      * @param options - Per-element observer options and callback data.
      *
+     * @remarks
+     * This method relies on an initialized {@link ElementViewObserver}. If automatic
+     * tracking has not been started, the call is a no-op.
+     *
      * @example
      * ```ts
      * const element = document.querySelector('#hero')!
@@ -122,6 +192,10 @@ declare class Optimization extends CoreStateful {
      *
      * @param element - Element to stop observing.
      *
+     * @remarks
+     * This method relies on an initialized {@link ElementViewObserver}. If automatic
+     * tracking has not been started, the call is a no-op.
+     *
      * @example
      * ```ts
      * optimization.untrackEntryViewForElement(element)

package/dist/Optimization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Optimization.d.ts","sourceRoot":"","sources":["../src/Optimization.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,GAAG,EACR,YAAY,EACZ,KAAK,kBAAkB,EAIxB,MAAM,+BAA+B,CAAA;AAetC,OAAO,EAEL,KAAK,yBAAyB,EAE9B,KAAK,0BAA0B,EAChC,MAAM,aAAa,CAAA;AAKpB,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,qEAAqE;QACrE,YAAY,CAAC,EAAE,OAAO,YAAY,CAAA;QAClC,6DAA6D;QAC7D,YAAY,CAAC,EAAE,YAAY,CAAA;KAC5B;CACF;AAED,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D;;OAEG;IACH,GAAG,CAAC,EAAE,GAAG,CAAA;IAET;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAE7B,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAC1B;AAsDD;;;;;;;;;;;;;;GAcG;AACH,cAAM,YAAa,SAAQ,YAAY;IACrC,OAAO,CAAC,mBAAmB,CAAC,CAAiC;IAC7D,OAAO,CAAC,wBAAwB,CAAC,CAAsC;IACvE,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAA8B;IAEhE;;;;;;;;;;;;;;;;;;OAkBG;gBACS,MAAM,EAAE,qBAAqB;IAwEzC,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;;OAWG;IACH,2BAA2B,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,IAAI;IAuBvE;;;;;;;OAOG;IACH,0BAA0B,IAAI,IAAI;IAKlC;;;;;;;;;;;;;;;OAeG;IACH,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI;IAKpF;;;;;;;;;OASG;IACH,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKlD;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,IAAI;CAMd;AAID,eAAe,YAAY,CAAA"}
+{"version":3,"file":"Optimization.d.ts","sourceRoot":"","sources":["../src/Optimization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAEL,KAAK,GAAG,EACR,YAAY,EACZ,KAAK,kBAAkB,EAIxB,MAAM,+BAA+B,CAAA;AAetC,OAAO,EAEL,KAAK,yBAAyB,EAE9B,KAAK,0BAA0B,EAChC,MAAM,aAAa,CAAA;AAUpB,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,qEAAqE;QACrE,YAAY,CAAC,EAAE,OAAO,YAAY,CAAA;QAClC,6DAA6D;QAC7D,YAAY,CAAC,EAAE,YAAY,CAAA;KAC5B;CACF;AAED;;;;;;GAMG;AACH,UAAU,gBAAgB;IACxB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AASD;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D;;OAEG;IACH,GAAG,CAAC,EAAE,GAAG,CAAA;IAET;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAE7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAC1B;AAsDD;;;;;;;;;;;;;;GAcG;AACH,cAAM,YAAa,SAAQ,YAAY;IACrC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAAiC;IAE7D;;;;OAIG;IACH,OAAO,CAAC,wBAAwB,CAAC,CAAsC;IAEvE;;;;OAIG;IACH,OAAO,CAAC,mBAAmB,CAAQ;IAEnC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAA8B;IAEhE;;;;;;;;;;;;;;;;;;OAkBG;gBACS,MAAM,EAAE,qBAAqB;IAsEzC;;;;;;;;OAQG;IACH,OAAO,CAAC,0BAA0B;IASlC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;;OAWG;IACH,2BAA2B,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,IAAI;IAuBvE;;;;;;;OAOG;IACH,0BAA0B,IAAI,IAAI;IAKlC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI;IAKpF;;;;;;;;;;;;;OAaG;IACH,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKlD;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,IAAI;CAMd;AAED,eAAe,YAAY,CAAA"}