Class EventBuilder

constructor

• new EventBuilder(config: EventBuilderConfig): EventBuilder

  Creates a new EventBuilder instance.

  Parameters

  • config: EventBuilderConfig

    Configuration used to customize event payloads.

  Returns EventBuilder

  Remarks

  Callers are expected to reuse a single instance when possible to avoid repeatedly reconfiguring the builder.

  Example

  const builder = new EventBuilder({
    channel: 'web',
    library: { name: '@contentful/optimization-sdk', version: '1.0.0' },
  })
  Copy

Optional Internalapp

Internalchannel

InternalgetLocale

InternalgetPageProperties

InternalgetUserAgent

Internallibrary

buildClick

• buildClick(
      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>;
              referrer: string;
              search: string;
              title?: string;
              url: string;
              [key: string]: JSONType;
          };
          screen?: { name: string; [key: string]: JSONType };
          userAgent?: string;
          variantIndex?: number;
      },
  ): {
      channel: "mobile"
      | "server"
      | "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>;
              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;
  }

  Builds a component_click payload for entry click 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>;
            referrer: string;
            search: string;
            title?: string;
            url: string;
            [key: string]: JSONType;
        };
        screen?: { name: string; [key: string]: JSONType };
        userAgent?: string;
        variantIndex?: number;
    }

    ClickBuilderArgs arguments describing the entry click.

  Returns {
      channel: "mobile" | "server" | "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>;
              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.

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

    Channel from which the event originated.

    See

    Channel

  • componentId: string

    Contentful entry ID or flag key corresponding to the interaction.

  • componentType: "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.

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

    • gdpr: { isConsentGiven: boolean }

      GDPR-related consent information.

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

    • locale: string

      Locale identifier of the event (e.g., "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.

        Remarks

        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.

        Remarks

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

    • Optionalpage?: {
          path: string;
          query: Record<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>

        Parsed query parameters for the page.

      • referrer: string

        Referrer URL that led to the current page.

      • search: string

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

      • Optionaltitle?: string

        Title of the page as seen by the user.

      • url: string

        Full URL of the page.

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

    Remarks

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

  • messageId: string

    Unique identifier for this message.

    Remarks

    Used to deduplicate events across retries and transports.

  • originalTimestamp: string

    Timestamp when the event originally occurred.

    Remarks

    ISO 8601 datetime string.

  • sentAt: string

    Timestamp when the event payload was sent.

    Remarks

    ISO 8601 datetime string.

  • timestamp: string

    Timestamp when the event was recorded or processed.

    Remarks

    ISO 8601 datetime string.

  • type: "component_click"

    Discriminator indicating that this is an entry click event.

  • OptionaluserId?: string

    Identifier of the authenticated user, if known.

  • variantIndex: number

    Index of the variant associated with this interaction.

    Remarks

    Typically corresponds to the index of the selected optimization entry.

  Example

  const event = builder.buildClick({
    componentId: 'entry-123',
    experienceId: 'experience-123',
    variantIndex: 1,
  })
  Copy

buildFlagView

• buildFlagView(
      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>;
              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;
      },
  ): {
      channel: "mobile"
      | "server"
      | "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>;
              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;
  }

  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>;
            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 {
      channel: "mobile" | "server" | "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>;
              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.

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

    Channel from which the event originated.

    See

    Channel

  • componentId: string

    Contentful entry ID or flag key corresponding to the interaction.

  • componentType: "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.

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

    • gdpr: { isConsentGiven: boolean }

      GDPR-related consent information.

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

    • locale: string

      Locale identifier of the event (e.g., "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.

        Remarks

        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.

        Remarks

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

    • Optionalpage?: {
          path: string;
          query: Record<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>

        Parsed query parameters for the page.

      • referrer: string

        Referrer URL that led to the current page.

      • search: string

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

      • Optionaltitle?: string

        Title of the page as seen by the user.

      • url: string

        Full URL of the page.

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

    Remarks

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

  • messageId: string

    Unique identifier for this message.

    Remarks

    Used to deduplicate events across retries and transports.

  • originalTimestamp: string

    Timestamp when the event originally occurred.

    Remarks

    ISO 8601 datetime string.

  • sentAt: string

    Timestamp when the event payload was sent.

    Remarks

    ISO 8601 datetime string.

  • timestamp: string

    Timestamp when the event was recorded or processed.

    Remarks

    ISO 8601 datetime string.

  • type: "component"

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

  • OptionaluserId?: string

    Identifier of the authenticated user, if known.

  • variantIndex: number

    Index of the variant associated with this interaction.

    Remarks

    Typically corresponds to the index of the selected optimization entry.

  • OptionalviewDurationMs?: number

    Monotonically increasing visible duration for the active view.

    Remarks

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

  • OptionalviewId?: string

    UUID identifying a single active view session.

    Remarks

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

  Remarks

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

  Example

  const event = builder.buildFlagView({
    componentId: 'feature-flag-key',
    viewId: crypto.randomUUID(),
    experienceId: 'experience-123',
    viewDurationMs: 1_000,
  })
  Copy

buildHover

• buildHover(
      args: {
          campaign?: {
              content?: string;
              medium?: string;
              name?: string;
              source?: string;
              term?: string;
          };
          componentId: string;
          experienceId?: string;
          hoverDurationMs: number;
          hoverId: string;
          locale?: string;
          location?: {
              city?: string;
              continent?: string;
              coordinates?: { latitude: number; longitude: number };
              country?: string;
              countryCode?: string;
              postalCode?: string;
              region?: string;
              regionCode?: string;
              timezone?: string;
          };
          page?: {
              path: string;
              query: Record<string, string>;
              referrer: string;
              search: string;
              title?: string;
              url: string;
              [key: string]: JSONType;
          };
          screen?: { name: string; [key: string]: JSONType };
          userAgent?: string;
          variantIndex?: number;
      },
  ): {
      channel: "mobile"
      | "server"
      | "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>;
              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;
  }

  Builds a component_hover payload for entry hover tracking.

  Parameters

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

    HoverBuilderArgs arguments describing the entry hover.

  Returns {
      channel: "mobile" | "server" | "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>;
              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.

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

    Channel from which the event originated.

    See

    Channel

  • componentId: string

    Contentful entry ID or flag key corresponding to the interaction.

  • componentType: "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.

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

    • gdpr: { isConsentGiven: boolean }

      GDPR-related consent information.

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

    • locale: string

      Locale identifier of the event (e.g., "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.

        Remarks

        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.

        Remarks

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

    • Optionalpage?: {
          path: string;
          query: Record<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>

        Parsed query parameters for the page.

      • referrer: string

        Referrer URL that led to the current page.

      • search: string

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

      • Optionaltitle?: string

        Title of the page as seen by the user.

      • url: string

        Full URL of the page.

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

    Remarks

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

  • hoverDurationMs: number

    Monotonically increasing hover duration for the active hover.

    Remarks

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

  • hoverId: string

    UUID identifying a single active hover session.

    Remarks

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

  • messageId: string

    Unique identifier for this message.

    Remarks

    Used to deduplicate events across retries and transports.

  • originalTimestamp: string

    Timestamp when the event originally occurred.

    Remarks

    ISO 8601 datetime string.

  • sentAt: string

    Timestamp when the event payload was sent.

    Remarks

    ISO 8601 datetime string.

  • timestamp: string

    Timestamp when the event was recorded or processed.

    Remarks

    ISO 8601 datetime string.

  • type: "component_hover"

    Discriminator indicating that this is an entry hover event.

  • OptionaluserId?: string

    Identifier of the authenticated user, if known.

  • variantIndex: number

    Index of the variant associated with this interaction.

    Remarks

    Typically corresponds to the index of the selected optimization entry.

  Example

  const event = builder.buildHover({
    componentId: 'entry-123',
    hoverId: crypto.randomUUID(),
    experienceId: 'experience-123',
    hoverDurationMs: 1_000,
    variantIndex: 1,
  })
  Copy

buildIdentify

• buildIdentify(
      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>;
              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;
      },
  ): {
      channel: "mobile"
      | "server"
      | "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>;
              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;
  }

  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>;
            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 {
      channel: "mobile" | "server" | "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>;
              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.

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

    Channel from which the event originated.

    See

    Channel

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

    • gdpr: { isConsentGiven: boolean }

      GDPR-related consent information.

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

    • locale: string

      Locale identifier of the event (e.g., "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.

        Remarks

        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.

        Remarks

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

    • Optionalpage?: {
          path: string;
          query: Record<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>

        Parsed query parameters for the page.

      • referrer: string

        Referrer URL that led to the current page.

      • search: string

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

      • Optionaltitle?: string

        Title of the page as seen by the user.

      • url: string

        Full URL of the page.

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

    Remarks

    Used to deduplicate events across retries and transports.

  • originalTimestamp: string

    Timestamp when the event originally occurred.

    Remarks

    ISO 8601 datetime string.

  • sentAt: string

    Timestamp when the event payload was sent.

    Remarks

    ISO 8601 datetime string.

  • timestamp: string

    Timestamp when the event was recorded or processed.

    Remarks

    ISO 8601 datetime string.

  • traits: Record<string, JSONType>

    Traits describing the user.

    See

    Traits

  • type: "identify"

    Discriminator indicating that this event is an identify event.

  • OptionaluserId?: string

    Identifier of the authenticated user, if known.

  Remarks

  • Traits are merged by the API; only specified properties may be overwritten.
  • The User ID is consumer-specified and should not contain the value of any ID generated by the Experience API.

  Example

  const event = builder.buildIdentify({
    userId: 'user-123',
    traits: { plan: 'pro' },
  })
  Copy

buildPageView

• buildPageView(
      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>;
              referrer: string;
              search: string;
              title?: string;
              url: string;
              [key: string]: JSONType;
          };
          properties?: {
              path?: string;
              query?: Record<string, string>;
              referrer?: string;
              search?: string;
              title?: string;
              url?: string;
              [key: string]: JSONType;
          };
          screen?: { name: string; [key: string]: JSONType };
          userAgent?: string;
      },
  ): {
      channel: "mobile"
      | "server"
      | "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>;
              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>;
          referrer: string;
          search: string;
          title?: string;
          url: string;
          [key: string]: JSONType;
      };
      sentAt: string;
      timestamp: string;
      type: "page";
      userId?: string;
  }

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

    Optional PageViewBuilderArgs overrides for the page view event.

  Returns {
      channel: "mobile" | "server" | "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>;
              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>;
          referrer: string;
          search: string;
          title?: string;
          url: string;
          [key: string]: JSONType;
      };
      sentAt: string;
      timestamp: string;
      type: "page";
      userId?: string;
  }

  A PageViewEvent payload.

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

    Channel from which the event originated.

    See

    Channel

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

    • gdpr: { isConsentGiven: boolean }

      GDPR-related consent information.

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

    • locale: string

      Locale identifier of the event (e.g., "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.

        Remarks

        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.

        Remarks

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

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

      Page context for events that occur within a web page.

      • path: string

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

      • query: Record<string, string>

        Parsed query parameters for the page.

      • referrer: string

        Referrer URL that led to the current page.

      • search: string

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

      • Optionaltitle?: string

        Title of the page as seen by the user.

      • url: string

        Full URL of the page.

    • OptionaluserAgent?: string

      User agent string of the client, if available.

  • messageId: string

    Unique identifier for this message.

    Remarks

    Used to deduplicate events across retries and transports.

  • Optionalname?: string

    Optional name for the page.

    Remarks

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

  • originalTimestamp: string

    Timestamp when the event originally occurred.

    Remarks

    ISO 8601 datetime string.

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

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

    • path: string

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

    • query: Record<string, string>

      Parsed query parameters for the page.

    • referrer: string

      Referrer URL that led to the current page.

    • search: string

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

    • Optionaltitle?: string

      Title of the page as seen by the user.

    • url: string

      Full URL of the page.

  • sentAt: string

    Timestamp when the event payload was sent.

    Remarks

    ISO 8601 datetime string.

  • timestamp: string

    Timestamp when the event was recorded or processed.

    Remarks

    ISO 8601 datetime string.

  • type: "page"

    Discriminator indicating that this event is a page view.

  • OptionaluserId?: string

    Identifier of the authenticated user, if known.

  Remarks

  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.

  Example

  const event = builder.buildPageView({
    properties: {
      title: 'Homepage',
    },
  })
  Copy