Contentful Personalization & Analytics
    Preparing search index...

    Helper class for building optimization events.

    This class coordinates configuration and argument validation to produce strongly-typed event payloads compatible with @contentful/optimization-api-schemas.

    Index

    Constructors

    Properties

    app?: { name: string; version: string }

    Application metadata attached to each event.

    Type Declaration

    • name: string

      Name of the application.

    • version: string

      Version of the application.

    channel: "server" | "mobile" | "web"

    Channel value attached to each event.

    getConsent: () => boolean | undefined

    Function that provides the current event consent value.

    getLocale: () => string | undefined

    Function that provides the locale when available.

    getPageProperties: () => {
        path: string;
        query: Record<string, string | string[]>;
        referrer: string;
        search: string;
        title?: string;
        url: string;
        [key: string]: JSONType;
    }

    Function that provides baseline page properties.

    getUserAgent: () => string | undefined

    Function that provides the user agent string when available.

    library: { name: string; version: string }

    Library metadata attached to each event.

    Type Declaration

    • name: string

      Name of the SDK/library (e.g., "@contentful/optimization-web").

    • version: string

      Version of the analytics library.

    Methods

    • Builds a component_click payload for entry click tracking.

      Parameters

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          componentId: string;
          componentType?: "Entry" | "Variable";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          experienceId?: string;
          messageId: string;
          originalTimestamp: string;
          sentAt: string;
          timestamp: string;
          type: "component_click";
          userId?: string;
          variantIndex?: number;
      }

      A ClickEvent describing the click.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • componentId: string

        Contentful entry ID or flag key corresponding to the interaction.

      • OptionalcomponentType?: "Entry" | "Variable"

        Type of tracked optimization target for the interaction event.

        • 'Entry' — A content entry.
        • 'Variable' — A Custom Flag or other variable-backed optimization target.

        Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Context object carrying environment and client metadata.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • Optionalscreen?: { name: string; [key: string]: JSONType }
          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • OptionalexperienceId?: string

        Identifier of the experience that rendered this entry or flag.

        Optional; interactions can occur outside of a specific experiment/personalization.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • type: "component_click"

        Discriminator indicating that this is an entry click event.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      • OptionalvariantIndex?: number

        Index of the variant associated with this interaction.

        Typically corresponds to the index of the selected optimization entry. Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      const event = builder.buildClick({
      componentId: 'entry-123',
      experienceId: 'experience-123',
      variantIndex: 1,
      })
    • Builds a component view event payload for Custom Flag exposure tracking.

      Parameters

      • args: {
            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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
            variantIndex?: number;
            viewDurationMs?: number;
            viewId?: string;
        }

        FlagViewBuilderArgs arguments describing the Custom Flag view.

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          componentId: string;
          componentType?: "Entry" | "Variable";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          experienceId?: string;
          messageId: string;
          originalTimestamp: string;
          sentAt: string;
          timestamp: string;
          type: "component";
          userId?: string;
          variantIndex?: number;
          viewDurationMs?: number;
          viewId?: string;
      }

      A ViewEvent describing the view.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • componentId: string

        Contentful entry ID or flag key corresponding to the interaction.

      • OptionalcomponentType?: "Entry" | "Variable"

        Type of tracked optimization target for the interaction event.

        • 'Entry' — A content entry.
        • 'Variable' — A Custom Flag or other variable-backed optimization target.

        Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Context object carrying environment and client metadata.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • Optionalscreen?: { name: string; [key: string]: JSONType }
          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • OptionalexperienceId?: string

        Identifier of the experience that rendered this entry or flag.

        Optional; interactions can occur outside of a specific experiment/personalization.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • type: "component"

        Discriminator indicating that this is an entry or flag view event.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      • OptionalvariantIndex?: number

        Index of the variant associated with this interaction.

        Typically corresponds to the index of the selected optimization entry. Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      • OptionalviewDurationMs?: number

        Monotonically increasing visible duration for the active view.

        This value is updated and re-emitted while the same view remains active.

      • OptionalviewId?: string

        UUID identifying a single active view session.

        Multiple events emitted for the same active view share this identifier.

      This is a specialized variant of EventBuilder.buildView that sets componentType to 'Variable'.

      const event = builder.buildFlagView({
      componentId: 'feature-flag-key',
      viewId: crypto.randomUUID(),
      experienceId: 'experience-123',
      viewDurationMs: 1_000,
      })
    • Builds a component_hover payload for entry hover tracking.

      Parameters

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          componentId: string;
          componentType?: "Entry" | "Variable";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          experienceId?: string;
          hoverDurationMs: number;
          hoverId: string;
          messageId: string;
          originalTimestamp: string;
          sentAt: string;
          timestamp: string;
          type: "component_hover";
          userId?: string;
          variantIndex?: number;
      }

      A HoverEvent describing the hover.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • componentId: string

        Contentful entry ID or flag key corresponding to the interaction.

      • OptionalcomponentType?: "Entry" | "Variable"

        Type of tracked optimization target for the interaction event.

        • 'Entry' — A content entry.
        • 'Variable' — A Custom Flag or other variable-backed optimization target.

        Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Context object carrying environment and client metadata.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • Optionalscreen?: { name: string; [key: string]: JSONType }
          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • OptionalexperienceId?: string

        Identifier of the experience that rendered this entry or flag.

        Optional; interactions can occur outside of a specific experiment/personalization.

      • hoverDurationMs: number

        Monotonically increasing hover duration for the active hover.

        This value is updated and re-emitted while the same hover remains active.

      • hoverId: string

        UUID identifying a single active hover session.

        Multiple events emitted for the same active hover share this identifier.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • type: "component_hover"

        Discriminator indicating that this is an entry hover event.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      • OptionalvariantIndex?: number

        Index of the variant associated with this interaction.

        Typically corresponds to the index of the selected optimization entry. Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      const event = builder.buildHover({
      componentId: 'entry-123',
      hoverId: crypto.randomUUID(),
      experienceId: 'experience-123',
      hoverDurationMs: 1_000,
      variantIndex: 1,
      })
    • Builds an identify event payload to associate a user ID with traits.

      Parameters

      • args: {
            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 | 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;
        }

        IdentifyBuilderArgs arguments describing the identified user.

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          messageId: string;
          originalTimestamp: string;
          sentAt: string;
          timestamp: string;
          traits: Record<string, JSONType>;
          type: "identify";
          userId: string;
      }

      An IdentifyEvent payload.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Context object carrying environment and client metadata.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • Optionalscreen?: { name: string; [key: string]: JSONType }
          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • traits: Record<string, JSONType>

        Traits describing the user.

        Traits

      • type: "identify"

        Discriminator indicating that this event is an identify event.

      • userId: string

        Identifier of the user being identified.

        Required for identify events, as the Experience API requires it.

      • Traits are merged by the API; only specified properties can be overwritten.
      • The User ID is consumer-specified and must not contain the value of any ID generated by the Experience API.
      const event = builder.buildIdentify({
      userId: 'user-123',
      traits: { plan: 'pro' },
      })
    • Builds a page view event payload.

      Parameters

      • args: {
            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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            properties?: {
                path?: string;
                query?: Record<string, string | string[]>;
                referrer?: string;
                search?: string;
                title?: string;
                url?: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        } = {}

        Optional PageViewBuilderArgs overrides for the page view event.

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              userAgent?: string;
          };
          messageId: string;
          name?: string;
          originalTimestamp: string;
          properties: {
              path: string;
              query: Record<string, string | string[]>;
              referrer: string;
              search: string;
              title: string;
              url: string;
              [key: string]: JSONType;
          };
          sentAt: string;
          timestamp: string;
          type: "page";
          userId?: string;
      }

      A PageViewEvent payload.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            userAgent?: string;
        }

        Override the context property of UniversalEventProperties with a page-specific context.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

          Page context for events that occur within a web page.

          Optional, as the Experience API defaults it to an empty page. The Experience API reads the session landing page and page-based audience rules from it, so send it whenever the page is known.

          • path: string

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • Optionalname?: string

        Optional name for the page.

        Useful when the logical page name differs from the URL or title.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

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

        Page-level properties such as URL, path, and referrer.

        title is required here, as the Experience API rejects page events without it.

        • path: string

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

        • query: Record<string, string | string[]>

          Parsed query parameters for the page.

          Query

        • referrer: string

          Referrer URL that led to the current page.

        • search: string

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

        • title: string
        • url: string

          Full URL of the page.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • type: "page"

        Discriminator indicating that this event is a page view.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      Page properties are created by merging:

      1. The base page properties from EventBuilderConfig.getPageProperties, and
      2. The partial properties argument passed in.

      The title always falls back to DEFAULT_PAGE_PROPERTIES.title when undefined.

      const event = builder.buildPageView({
      properties: {
      title: 'Homepage',
      },
      })
    • Builds a screen view event payload.

      Parameters

      • args: {
            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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            properties: Record<string, JSONType>;
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        ScreenViewBuilderArgs arguments for the screen view event.

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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;
              };
              screen: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          messageId: string;
          name: string;
          originalTimestamp: string;
          properties?: Record<string, JSONType>;
          sentAt: string;
          timestamp: string;
          type: "screen";
          userId?: string;
      }

      A ScreenViewEvent payload.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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;
            };
            screen: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Override the context property of UniversalEventProperties with a screen-specific context.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

        • screen: { name: string; [key: string]: JSONType }

          Screen context for events that occur within a mobile or TV application.

          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • name: string

        Name of the screen being viewed.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • Optionalproperties?: Record<string, JSONType>

        Optional properties describing the screen context.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • type: "screen"

        Discriminator indicating that this event is a screen view.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      const event = builder.buildScreenView({
      name: 'home',
      properties: {
      title: 'Home Screen',
      },
      })
    • Builds a track event payload for arbitrary user actions.

      Parameters

      • args: {
            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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            properties?: Record<string, JSONType>;
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        TrackBuilderArgs arguments describing the tracked event.

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          event: string;
          messageId: string;
          originalTimestamp: string;
          properties: Record<string, JSONType>;
          sentAt: string;
          timestamp: string;
          type: "track";
          userId?: string;
      }

      A TrackEvent payload.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Context object carrying environment and client metadata.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • Optionalscreen?: { name: string; [key: string]: JSONType }
          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • event: string

        Name of the event being tracked.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • properties: Record<string, JSONType>

        Additional properties describing the event.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • type: "track"

        Discriminator indicating that this event is a track event.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      const event = builder.buildTrack({
      event: 'button_clicked',
      properties: { id: 'primary-cta', location: 'hero' },
      })
    • Builds the universal event properties shared across all event types.

      Parameters

      • args: {
            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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Arguments overriding the default context values.

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          messageId: string;
          originalTimestamp: string;
          sentAt: string;
          timestamp: string;
          userId?: string;
      }

      A fully populated UniversalEventProperties object.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Context object carrying environment and client metadata.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • Optionalscreen?: { name: string; [key: string]: JSONType }
          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      This method is used internally by the specific event-builder methods (e.g. EventBuilder.buildPageView).

    • Builds a component view event payload for entry exposure tracking.

      Parameters

      Returns {
          anonymousId?: string;
          channel: "server" | "mobile" | "web";
          componentId: string;
          componentType?: "Entry" | "Variable";
          context: {
              app?: { name: string; version: string };
              campaign: {
                  content?: string;
                  medium?: string;
                  name?: string;
                  source?: string;
                  term?: string;
              };
              gdpr?: { isConsentGiven: boolean };
              library: { name: string; version: 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 | string[]>;
                  referrer: string;
                  search: string;
                  title?: string;
                  url: string;
                  [key: string]: JSONType;
              };
              screen?: { name: string; [key: string]: JSONType };
              userAgent?: string;
          };
          experienceId?: string;
          messageId: string;
          originalTimestamp: string;
          sentAt: string;
          timestamp: string;
          type: "component";
          userId?: string;
          variantIndex?: number;
          viewDurationMs?: number;
          viewId?: string;
      }

      A ViewEvent describing the view.

      • OptionalanonymousId?: string

        Anonymous identifier of the visitor, if the caller supplies one.

        Optional. The Experience API profile endpoints derive it from the request route, and batch ingestion requires it (see BatchExperienceEvent).

      • channel: "server" | "mobile" | "web"

        Channel from which the event originated.

      • componentId: string

        Contentful entry ID or flag key corresponding to the interaction.

      • OptionalcomponentType?: "Entry" | "Variable"

        Type of tracked optimization target for the interaction event.

        • 'Entry' — A content entry.
        • 'Variable' — A Custom Flag or other variable-backed optimization target.

        Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      • context: {
            app?: { name: string; version: string };
            campaign: {
                content?: string;
                medium?: string;
                name?: string;
                source?: string;
                term?: string;
            };
            gdpr?: { isConsentGiven: boolean };
            library: { name: string; version: 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 | string[]>;
                referrer: string;
                search: string;
                title?: string;
                url: string;
                [key: string]: JSONType;
            };
            screen?: { name: string; [key: string]: JSONType };
            userAgent?: string;
        }

        Context object carrying environment and client metadata.

        • Optionalapp?: { name: string; version: string }

          Application-level metadata.

          • name: string

            Name of the application.

          • version: string

            Version of the application.

        • campaign: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          }

          Campaign attribution metadata.

          • Optionalcontent?: string

            Campaign content (e.g., utm_content).

          • Optionalmedium?: string

            Campaign medium (e.g., utm_medium).

          • Optionalname?: string

            Name of the campaign (e.g., utm_campaign).

          • Optionalsource?: string

            Campaign source (e.g., utm_source).

          • Optionalterm?: string

            Campaign term (e.g., utm_term).

        • Optionalgdpr?: { isConsentGiven: boolean }

          GDPR-related consent information.

          Optional and informational: the Experience and Insights APIs do not read it. Consent is enforced by the SDK before events are sent.

          • isConsentGiven: boolean

            Indicates whether the user has given consent.

        • library: { name: string; version: string }

          Analytics library metadata.

          • name: string

            Name of the SDK/library (e.g., "@contentful/optimization-web").

          • version: string

            Version of the analytics library.

        • Optionallocale?: string

          Locale identifier of the event (e.g., "en-US").

          "en-US"

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

          Optional geo-location information associated with the event.

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

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

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

          • query: Record<string, string | string[]>

            Parsed query parameters for the page.

            Query

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

        • Optionalscreen?: { name: string; [key: string]: JSONType }
          • name: string

            Name or label for the screen.

        • OptionaluserAgent?: string

          User agent string of the client, if available.

      • OptionalexperienceId?: string

        Identifier of the experience that rendered this entry or flag.

        Optional; interactions can occur outside of a specific experiment/personalization.

      • messageId: string

        Unique identifier for this message.

        Used to deduplicate events across retries and transports.

      • originalTimestamp: string

        Timestamp when the event originally occurred.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • sentAt: string

        Timestamp when the event payload was sent.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • timestamp: string

        Timestamp when the event was recorded or processed.

        Any date string the Experience API can parse; the SDK sends ISO 8601.

      • type: "component"

        Discriminator indicating that this is an entry or flag view event.

      • OptionaluserId?: string

        Identifier of the authenticated user, if known.

      • OptionalvariantIndex?: number

        Index of the variant associated with this interaction.

        Typically corresponds to the index of the selected optimization entry. Optional in the schema, as the Experience and Insights APIs accept events without it. The SDK always sends it.

      • OptionalviewDurationMs?: number

        Monotonically increasing visible duration for the active view.

        This value is updated and re-emitted while the same view remains active.

      • OptionalviewId?: string

        UUID identifying a single active view session.

        Multiple events emitted for the same active view share this identifier.

      const event = builder.buildView({
      componentId: 'entry-123',
      viewId: crypto.randomUUID(),
      experienceId: 'experience-123',
      variantIndex: 1,
      viewDurationMs: 1_000,
      })