Contentful Personalization & Analytics

Optimization Web SDK

This SDK implements functionality specific to the Web environment, based on the Optimization Core Library. This SDK is part of the Contentful Optimization SDK Suite.

Getting Started

Install using an NPM-compatible package manager, pnpm for example:

pnpm install @contentful/optimization-web
Copy

Import the Optimization class; both CJS and ESM module systems are supported, ESM preferred:

import Optimization from '@contentful/optimization-web'
Copy

Configure and initialize the Optimization Node SDK:

const optimization = new Optimization({ clientId: 'abc123' })
Copy

Reference Implementations

• Web Vanilla: Example static Web page that renders and emits analytics events for personalized content using a vanilla JS drop-in build of the Web SDK

Configuration

Top-level Configuration Options

Configuration method signatures:

• getAnonymousId: () => string | undefined

Analytics Options

Configuration method signatures:

• beaconHandler: (url: string | URL, data: BatchInsightsEventArray) => boolean

Event Builder Options

Event builder options should only be supplied when building an SDK on top of Core or any of its descendent SDKs.

The channel option may contain one of the following values:

• web
• mobile
• server

Configuration method signatures:

• getLocale: () => string | undefined

• getPageProperties:

  () => {
    path: string,
    query: Record<string, string>,
    referrer: string,
    search: string,
    title?: string,
    url: string
  }
  Copy

• getUserAgent: () => string | undefined

Fetch Options

Fetch options allow for configuration of a Fetch API-compatible fetch method and the retry/timeout logic integrated into the Optimization API Client. Specify the fetchMethod when the host application environment does not offer a fetch method that is compatible with the standard Fetch API in its global scope.

Configuration method signatures:

• fetchMethod: (url: string | URL, init: RequestInit) => Promise<Response>
• onFailedAttempt and onRequestTimeout: (options: FetchMethodCallbackOptions) => void

Personalization Options

Optimization Properties

• states: Returns an object mapping of observables for all internal states

The following observables are exposed via the states property:

• consent: The current state of user consent
• eventStream: The latest event to be queued
• flags: All current resolved Custom Flags
• profile: The current user profile
• personalizations: The current collection of selected personalizations

Each state except consent and eventStream is updated internally whenever a response from the Experience API contains a new or updated respective state.

Optimization Methods

Arguments marked with an asterisk (*) are always required.

Top-level Methods

consent

Updates the user consent state.

Arguments:

• accept: A boolean value specifying whether the user has accepted (true) or denied (false). A value of undefined implies that the user has not yet explicitly chosen whether to consent.

reset

Resets all internal state except consent. This method expects no arguments and returns no value.

startAutoTrackingEntryViews

Starts the process of tracking entry views.

Arguments:

• options: Options to be passed to the element view observer:
  • dwellTimeMs: Required time before emitting the view event; default 1,000ms
  • minVisibleRatio: Minimum intersection ratio considered "visible"; default 0.1 (10%)
  • root: IntersectionObserver root; default null (viewport)
  • rootMargin: IntersectionObserver rootMargin; default 0px
  • maxRetries: Maximum callback retry attempts on failure; default 2
  • retryBackoffMs: Initial back-off delay in milliseconds for retries; default 300ms
  • backoffMultiplier: Exponential back-off multiplier; default 2

stopAutoTrackingEntryViews

Stops and cleans up the process of tracking entry views. This method expects no arguments and returns no value.

trackEntryViewForElement

Manually observes a given element for automatic entry/component tracking.

Arguments:

• element: A DOM element that directly contains the entry content to be tracked
• options*: Per-element options used to refine observation
  • data: Entry-specific data to send to the IntersectionObserver callback; see "Entry View Tracking"
  • dwellTimeMs: Per-element override of the required time before emitting the view event
  • maxRetries: Per-element override of the maximum callback retry attempts on failure
  • retryBackoffMs: Per-element override of the initial back-off delay in milliseconds for retries
  • backoffMultiplier: Per-element override of the exponential back-off multiplier

[!INFO]

This method does not need to be called if the given element is auto-observable as an entry; see "Entry View Tracking"

untrackEntryViewForElement

Manually stops observing a given element for automatic entry/component tracking.

Arguments:

• element: A DOM element that directly contains entry content that is already tracked

[!INFO]

This method does not need to be called if the given element is auto-observable as an entry; see "Entry View Tracking"

Personalization Data Resolution Methods

getCustomFlag

Get the specified Custom Flag's value from the provided changes array, or from the current internal state.

Arguments:

• name*: The name/key of the Custom Flag
• changes: Changes array

Returns:

• The resolved value for the specified Custom Flag, or undefined if it cannot be found.

personalizeEntry

Resolve a baseline Contentful entry to a personalized variant using the provided selected personalizations, or from the current internal state.

Type arguments:

• S: Entry skeleton type
• M: Chain modifiers
• L: Locale code

Arguments:

• entry*: The entry to personalize
• personalizations: Selected personalizations

Returns:

• The resolved personalized entry variant, or the supplied baseline entry if baseline is the selected variant or a variant cannot be found.

getMergeTagValue

Resolve a "Merge Tag" to a value based on the current (or provided) profile. A "Merge Tag" is a special Rich Text fragment supported by Contentful that specifies a profile data member to be injected into the Rich Text when rendered.

Arguments:

• embeddedNodeEntryTarget*: The merge tag entry node to resolve
• profile: The user profile

Personalization and Analytics Event Methods

Each method except trackFlagView may return an OptimizationData object containing:

• changes: Currently used for Custom Flags
• personalizations: Selected personalizations for the profile
• profile: Profile associated with the evaluated events

identify

Identify the current profile/visitor to associate traits with a profile.

Arguments:

• payload*: Identify event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

page

Record a personalization page view.

Arguments:

• payload*: Page view event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

track

Record a personalization custom track event.

Arguments:

• payload*: Track event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

trackComponentView

Record an analytics component view event. When the payload marks the component as "sticky", an additional personalization component view is recorded. This method only returns OptimizationData when the component is marked as "sticky".

Arguments:

• payload*: Component view event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id
• duplicationScope: Arbitrary string that may be used to scope component view duplication

trackFlagView

Track a feature flag view via analytics. This is functionally the same as a non-sticky component view event.

Arguments:

• payload*: Component view event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id
• duplicationScope: Arbitrary string that may be used to scope component view duplication

Entry View Tracking

Tracking of entry/component views is based on the element that contains that entry's content. The Optimization Web SDK can automatically track observed entry elements for events such as "component views", and it can also automatically observe elements that are marked as entry-related elements.

Manual Entry View Tracking

To manually track entry views using custom tracking code, simply call trackComponentView with the necessary arguments when appropriate.

Example:

optimization.trackComponentView({ entryId: 'abc-123', ... })
Copy

Automatic Entry View Tracking

Entry/component views can be tracked automatically for observed entry-related elements by simply setting the autoTrackEntryViews configuration option to true, or by calling the startAutoTrackingEntryViews method if further setup is required depending on the consumer's SDK integration solution.

Manual Entry Element Observation

To track an element as an entry-related element, call the trackEntryViewForElement method with the element to be tracked, as well as the data option set with the following data members:

• duplicationScope: Key to differentiate between entry views when the same entry may be tracked in multiple locations
• entryId*: The ID of the content entry to be tracked; should be the selected variant if the entry is personalized
• personalizationId: The ID of the personalization/experience entry associated with the content entry; only required if the entry is personalized
• sticky: A boolean value that marks that the current user should always see this variant; ignored if the entry is not personalized
• variantIndex: The index of the selected variant; only required if the entry is personalized

Example:

optimization.trackEntryViewForElement(element, { data: { entryId: 'abc-123', ... } })
Copy

Automatic Entry Element Observation

Elements that are associated to entries using the following data attributes will be automatically detected for observation and view tracking:

• data-ctfl-duplication-scope: Key to differentiate between entry views when the same entry may be tracked in multiple locations
• data-ctfl-entry-id*: The ID of the content entry to be tracked; should be the selected variant if the entry is personalized
• data-ctfl-personalization-id: The ID of the personalization/experience entry associated with the content entry; only required if the entry is personalized
• data-ctfl-sticky: A boolean value that marks that the current user should always see this variant; ignored if the entry is not personalized
• data-ctfl-variant-index: The index of the selected variant; only required if the entry is personalized

Example:

<div data-ctfl-entry-id="abc-123">Entry Content</div>
Copy

Interceptors

Interceptors may be used to read and/or modify data flowing through the Core SDK.

Life-cycle Interceptors

• event: Intercepts an event's data before it is queued and/or emitted
• state: Intercepts state data retrieved from an Experience API call before updating the SDK's internal state

Example interceptor usage:

optimization.interceptors.event((event) => {
  event.properties.timestamp = new Date().toISOString()
})
Copy