Contentful Personalization & Analytics
    Preparing search index...

    Core runtime that constructs stateful product instances and exposes shared states, including consent and the event stream.

    • CoreBase
    • ConsentController

    Hierarchy

    • CoreBase
      • CoreStateful

    Implements

    • ConsentController
    Index

    Constructors

    Properties

    Stateful 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: PersonalizationStateful

    Stateful personalization product.

    Accessors

    Methods

    • Update consent state

      Parameters

      • accept: boolean

        true if the user has granted consent; false otherwise.

      Returns void

    • Flush the queues for both the analytics and personalization products.

      Returns Promise<void>

      The personalization queue is only populated if events have been triggered while a device is offline.

    • 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.

    • 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).

    • Register a preview panel compatible object to receive direct signal access. This enables the preview panel to modify SDK state for testing and simulation.

      Parameters

      Returns void

      This method is intended for use by the Preview Panel component. Direct signal access allows immediate state updates without API calls.

    • Reset internal state. Consent is intentionally preserved.

      Returns void

      Resetting personalization also resets analytics dependencies as a consequence of the current shared-state design.

    • 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.