Class EventBuilder

constructor

• new EventBuilder(config: EventBuilderConfig): EventBuilder
  Internal

  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

buildComponentView

• buildComponentView(
      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 };
          sticky?: boolean;
          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";
      userId?: string;
      variantIndex: number;
  }

  Builds a component view event payload for a Contentful entry-based component.

  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 };
        sticky?: boolean;
        userAgent?: string;
        variantIndex?: number;
    }

    ComponentViewBuilderArgs arguments describing the component 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;
  }

  A ComponentViewEvent describing the view.

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

    Channel from which the event originated.

    See

    Channel

  • componentId: string

    Contentful entry ID corresponding to the component that was viewed.

  • componentType: "Entry" | "Variable"

    Type of component that was viewed.

    • 'Entry' — A content entry component.
    • 'Variable' — A variable or inline value component.

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

    Remarks

    Optional; component views may occur outside of a specific experience/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 event is a component view.

  • OptionaluserId?: string

    Identifier of the authenticated user, if known.

  • variantIndex: number

    Index of the variant associated with this component view.

    Remarks

    Typically corresponds to the index of the selected personalization entry.

  Example

  const event = builder.buildComponentView({
    componentId: 'entry-123',
    experienceId: 'personalization-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 };
          sticky?: boolean;
          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";
      userId?: string;
      variantIndex: number;
  }

  Builds a component view event payload for a Custom Flag component.

  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 };
        sticky?: boolean;
        userAgent?: string;
        variantIndex?: number;
    }

    ComponentViewBuilderArgs 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;
  }

  A ComponentViewEvent describing the view.

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

    Channel from which the event originated.

    See

    Channel

  • componentId: string

    Contentful entry ID corresponding to the component that was viewed.

  • componentType: "Entry" | "Variable"

    Type of component that was viewed.

    • 'Entry' — A content entry component.
    • 'Variable' — A variable or inline value component.

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

    Remarks

    Optional; component views may occur outside of a specific experience/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 event is a component view.

  • OptionaluserId?: string

    Identifier of the authenticated user, if known.

  • variantIndex: number

    Index of the variant associated with this component view.

    Remarks

    Typically corresponds to the index of the selected personalization entry.

  Remarks

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

  Example

  const event = builder.buildFlagView({
    componentId: 'feature-flag-key',
    experienceId: 'personalization-123',
  })
  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;
    }

    • 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