Contentful Personalization & Analytics
    Preparing search index...

    Class default

    Node-specific Optimization SDK built on CoreStateless.

    This class adapts the stateless Optimization Core for Node runtimes by applying environment-appropriate defaults (e.g., server channel, Node SDK library metadata). No analytics or personalization behavior is modified— only configuration defaults differ.

    import Optimization from '@contentful/optimization-node'

    const sdk = new Optimization({
      clientId: 'abc-123',
      environment: 'main',
      logLevel: 'info',
    })

    await sdk.track({ event: 'server_event', properties: { id: 1 } })

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    analytics api config eventBuilder interceptors personalization

    Methods

    getCustomFlag getMergeTagValue identify page personalizeEntry screen track trackComponentView trackFlagView

    Constructors

    Properties

    analytics: AnalyticsStateless

    Stateless analytics product.

    api: default

    Shared Optimization API client instance.

    config: Omit<CoreConfig, "name">

    Resolved core configuration (minus any name metadata).

    eventBuilder: EventBuilder

    Shared event builder instance.

    interceptors: LifecycleInterceptors = ...
    personalization: PersonalizationStateless

    Stateless personalization product.

    Methods

    • Get the value of a custom flag derived from a set of optimization changes.

      Parameters

      • name: string

        The flag key to resolve.

      • Optionalchanges: {
            key: string;
            meta: { experienceId: string; variantIndex: number };
            type: "Variable";
            value: null | string | number | boolean | Record<string, JSONType>;
        }[]

        Optional change list to resolve from

        • key: string

          Key identifying the subject of the change.

        • meta: { experienceId: string; variantIndex: number }

          Metadata describing the originating experience and variant index.

          • experienceId: string

            Identifier of the personalization or experiment experience.

          • variantIndex: number

            Index of the variant within the experience configuration.

            Typically corresponds to the array index in the experience's distribution.

        • type: "Variable"

          Discriminator for a variable change.

        • value: null | string | number | boolean | Record<string, JSONType>

          New value for the variable identified by ChangeBase.key.

      Returns unknown

      The resolved JSON value for the flag if available.

      This is a convenience wrapper around personalization’s flag resolution.

    • Resolve a merge-tag value from the given entry node and profile.

      Parameters

      • embeddedEntryNodeTarget: {
            fields: {
                nt_fallback?: string;
                nt_mergetag_id: string;
                nt_name: string;
            };
            metadata: {
                tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
                [key: string]: JSONType;
            };
            sys: {
                contentType: {
                    sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
                };
                createdAt: any;
                environment: {
                    sys: { id: string; linkType: "Environment"; type: "Link" };
                };
                id: string;
                locale?: string;
                publishedVersion: number;
                revision: number;
                space: { sys: { id: string; linkType: "Space"; type: "Link" } };
                type: "Entry";
                updatedAt: any;
            };
        }

        The merge-tag entry node to resolve.

        • fields: { nt_fallback?: string; nt_mergetag_id: string; nt_name: string }
          • Optionalnt_fallback?: string

            Fallback value to use when the merge tag cannot be resolved.

          • nt_mergetag_id: string

            Internal identifier of the merge tag.

          • nt_name: string

            Human-readable name of the merge tag.

        • metadata: {
              tags: { sys: { id: string; linkType: "Tag"; type: "Link" } }[];
              [key: string]: JSONType;
          }

          Contentful metadata, including tags.

        • sys: {
              contentType: {
                  sys: { id: "nt_mergetag"; linkType: "ContentType"; type: "Link" };
              };
              createdAt: any;
              environment: { sys: { id: string; linkType: "Environment"; type: "Link" } };
              id: string;
              locale?: string;
              publishedVersion: number;
              revision: number;
              space: { sys: { id: string; linkType: "Space"; type: "Link" } };
              type: "Entry";
              updatedAt: any;
          }

          System fields extended to constrain the content type to nt_mergetag.

      • Optionalprofile: {
            audiences: string[];
            id: string;
            location: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            random: number;
            session: {
                activeSessionLength: number;
                averageSessionLength: number;
                count: number;
                id: string;
                isReturningVisitor: boolean;
                landingPage: {
                    path: string;
                    query: Record<string, string>;
                    referrer: string;
                    search: string;
                    title?: string;
                    url: string;
                    [key: string]: JSONType;
                };
            };
            stableId: string;
            traits: Record<string, JSONType>;
        }

        Optional profile used for value lookup.

        • audiences: string[]

          List of audience identifiers that this profile currently belongs to.

        • id: string

          Primary identifier of the profile.

        • location: {
              city?: string;
              continent?: string;
              coordinates?: { latitude: number; longitude: number };
              country?: string;
              countryCode?: string;
              postalCode?: string;
              region?: string;
              regionCode?: string;
              timezone?: string;
          }

          Geo-location information associated with the profile.

          GeoLocation

          • Optionalcity?: string

            City name associated with the location.

          • Optionalcontinent?: string

            Continent name associated with the location.

          • Optionalcoordinates?: { latitude: number; longitude: number }

            Geographical coordinates for the location.

            • latitude: number

              Latitude component of the coordinates.

            • longitude: number

              Longitude component of the coordinates.

          • Optionalcountry?: string

            Country name associated with the location.

          • OptionalcountryCode?: string

            Country code associated with the location.

            Validated to exactly COUNTRY_CODE_LENGTH characters, typically an ISO 3166-1 alpha-2 code.

          • OptionalpostalCode?: string

            Postal or ZIP code associated with the location.

          • Optionalregion?: string

            Region or state name associated with the location.

          • OptionalregionCode?: string

            Region or state code associated with the location.

          • Optionaltimezone?: string

            Time zone identifier associated with the location.

            Typically an IANA time zone string (e.g., "Europe/Berlin").

        • random: number

          Random value associated with the profile.

          Often used for deterministic bucketing (e.g., in experiments).

        • session: {
              activeSessionLength: number;
              averageSessionLength: number;
              count: number;
              id: string;
              isReturningVisitor: boolean;
              landingPage: {
                  path: string;
                  query: Record<string, string>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
          }

          Aggregated session statistics for the profile.

          SessionStatistics

          • activeSessionLength: number

            Duration of the active session.

          • averageSessionLength: number

            Average session duration across all sessions represented by this record.

            The unit should match SessionStatistics.activeSessionLength.

          • count: number

            Number of sessions associated with this profile or identifier.

            Often used in combination with SessionStatistics.averageSessionLength.

          • id: string

            Unique identifier for this session statistics record.

          • isReturningVisitor: boolean

            Indicates whether the visitor has been seen before.

            true typically means the visitor has at least one prior session.

          • landingPage: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            }

            Landing page for the session.

            Represents the first page the user visited in this session.

            Page

            • path: string

              Path component of the page URL (e.g., /products/123).

            • query: Record<string, string>

              Parsed query parameters for the page.

            • referrer: string

              Referrer URL that led to the current page.

            • search: string

              Raw search string including the leading ? (e.g., "?q=test").

            • Optionaltitle?: string

              Title of the page as seen by the user.

            • url: string

              Full URL of the page.

        • stableId: string

          Stable, long-lived identifier of the profile.

          Intended to remain constant across sessions and devices when possible. Usually equal to id.

        • traits: Record<string, JSONType>

          Traits describing the profile (user-level attributes).

          Traits

      Returns unknown

      The resolved value (typically a string) or undefined if not found.

    • Convenience wrapper for sending an identify event via personalization.

      Parameters

      • payload: {
            campaign?: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            locale?: string;
            location?: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            page?: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            traits?: Record<string, JSONType>;
            userAgent?: string;
            userId: string;
        } & { profile?: { id: string; [key: string]: JSONType } }

        Identify builder arguments.

      Returns Promise<undefined | OptimizationData>

      The resulting OptimizationData for the identified user.

    page

    • page(
          payload: {
              campaign?: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              locale?: string;
              location?: {
                  city?: string;
                  continent?: string;
                  coordinates?: { latitude: number; longitude: number };
                  country?: string;
                  countryCode?: string;
                  postalCode?: string;
                  region?: string;
                  regionCode?: string;
                  timezone?: string;
              };
              page?: {
                  path: string;
                  query: Record<string, string>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              properties?: {
                  path?: string;
                  query?: Record<string, string>;
                  referrer?: string;
                  search?: string;
                  title?: string;
                  url?: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          } & { profile?: { id: string; [key: string]: JSONType } },
      ): Promise<undefined | OptimizationData>

      Convenience wrapper for sending a page event via personalization.

      Parameters

      • payload: {
            campaign?: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            locale?: string;
            location?: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            page?: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            properties?: {
                path?: string;
                query?: Record<string, string>;
                referrer?: string;
                search?: string;
                title?: string;
                url?: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        } & { profile?: { id: string; [key: string]: JSONType } }

        Page view builder arguments.

      Returns Promise<undefined | OptimizationData>

      The evaluated OptimizationData for this page view.

    • Resolve a Contentful entry to the appropriate personalized variant (or return the baseline entry if no matching variant is selected).

      Type Parameters

      • S extends EntrySkeletonType

        Entry skeleton type.

      • M extends ChainModifiers = ChainModifiers

        Chain modifiers.

      • L extends string = string

        Locale code.

      Parameters

      • entry: Entry<S, M, L>

        The baseline entry to resolve.

      • Optionalpersonalizations: {
            experienceId: string;
            sticky?: boolean;
            variantIndex: number;
            variants: Record<string, string>;
        }[]

        Optional selection array for the current profile.

        • experienceId: string

          Identifier of the personalization or experiment experience.

        • Optionalsticky?: boolean

          Indicates whether this personalization selection is sticky for the user.

          false

          Sticky selections should be reused on subsequent requests for the same user, rather than re-allocating a new variant.

        • variantIndex: number

          Index of the selected variant within the experience configuration.

          Typically corresponds to the index of the selected PersonalizationConfig entry.

        • variants: Record<string, string>

          Mapping of baseline entry IDs to their selected variant entry IDs.

          The keys are component identifiers and the values are the identifiers of the selected variant for that component.

      Returns ResolvedData<S, M, L>

      ResolvedData containing the resolved entry and personalization metadata (if any).

    • Convenience wrapper for sending a screen event via personalization.

      Parameters

      • payload: {
            campaign?: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            locale?: string;
            location?: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            name: string;
            page?: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            properties: Record<string, JSONType>;
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        } & { profile?: { id: string; [key: string]: JSONType } }

        Screen view builder arguments.

      Returns Promise<undefined | OptimizationData>

      The evaluated OptimizationData for this screen view.

    • Convenience wrapper for sending a custom track event via personalization.

      Parameters

      • payload: {
            campaign?: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            event: string;
            locale?: string;
            location?: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            page?: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            properties?: Record<string, JSONType>;
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        } & { profile?: { id: string; [key: string]: JSONType } }

        Track builder arguments.

      Returns Promise<undefined | OptimizationData>

      The evaluated OptimizationData for this event.

    • Track a component view in both personalization and analytics.

      Parameters

      • payload: {
            campaign?: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            componentId: string;
            experienceId?: string;
            locale?: string;
            location?: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            page?: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            sticky?: boolean;
            userAgent?: string;
            variantIndex?: number;
        } & { profile?: { id: string; [key: string]: JSONType } }

        Component view builder arguments. When payload.sticky is true, the event will also be sent via personalization as a sticky component view.

      • OptionalduplicationScope: string

        Optional string used to scope duplication used in Stateful implementations

      Returns Promise<undefined | OptimizationData>

      A promise that resolves when all delegated calls complete.

      The sticky behavior is delegated to personalization; analytics is always invoked regardless of sticky.

    • Track a feature flag view via analytics.

      Parameters

      • payload: {
            campaign?: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            componentId: string;
            experienceId?: string;
            locale?: string;
            location?: {
                city?: string;
                continent?: string;
                coordinates?: { latitude: number; longitude: number };
                country?: string;
                countryCode?: string;
                postalCode?: string;
                region?: string;
                regionCode?: string;
                timezone?: string;
            };
            page?: {
                path: string;
                query: Record<string, string>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            sticky?: boolean;
            userAgent?: string;
            variantIndex?: number;
        }

        Component view builder arguments used to build the flag view event.

      • OptionalduplicationScope: string

        Optional string used to scope duplication used in Stateful implementations

      Returns Promise<void>

      A promise that resolves when processing completes.

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods