Contentful Personalization & Analytics
    Preparing search index...

    Client for sending analytics and insights events to the Ninetailed Insights API.

    This client is optimized for sending batched events, optionally using a custom beacon-like sender for last-chance lifecycle delivery.

    const insightsClient = new InsightsApiClient({
    spaceId: 'space-id',
    environment: 'master',
    })

    await insightsClient.sendBatchEvents([
    {
    profile, // Complete profile snapshot returned by the Experience API
    events: [viewEvent],
    }
    ])

    Extends ApiClientBase.

    Hierarchy

    • ApiClientBase
      • InsightsApiClient
    Index

    Constructors

    Properties

    baseUrl: string

    Base URL used for Insights API requests.

    environment: string

    Contentful space environment associated with this client.

    Protected fetch method used by the client to perform HTTP requests.

    name: string

    Name of the API client, used in log messages and as the apiName for fetch.

    spaceId: string

    Contentful Space identifier used for authentication or tracking.

    Methods

    • Logs errors that occur during API requests with standardized messages.

      Parameters

      • error: unknown

        The error thrown by the underlying operation.

      • options: { requestName: string }

        Additional metadata about the request.

        • requestName: string

          Human-readable name of the request operation.

      Returns void

      Abort errors are logged at warn level and other errors at error level. The log message includes the client name for better debugging context.

    • Sends batches of insights events to the Ninetailed Insights API.

      Parameters

      • batches: {
            events: (
                | {
                    anonymousId?: string;
                    channel: "server"
                    | "mobile"
                    | "web";
                    context: {
                        app?: { name: string; version: string };
                        campaign: {
                            content?: string;
                            medium?: string;
                            name?: string;
                            source?: string;
                            term?: string;
                        };
                        gdpr?: { isConsentGiven: boolean };
                        library: { name: string; version: string };
                        locale?: string;
                        location?: {
                            city?: string;
                            continent?: string;
                            coordinates?: { latitude: number; longitude: number };
                            country?: string;
                            countryCode?: string;
                            postalCode?: string;
                            region?: string;
                            regionCode?: string;
                            timezone?: string;
                        };
                        page?: {
                            path: string;
                            query: Record<string, string | (...)[]>;
                            referrer: string;
                            search: string;
                            title?: string;
                            url: string;
                            [key: string]: JSONType;
                        };
                        screen?: { name: string; [key: string]: JSONType };
                        userAgent?: string;
                    };
                    entityId: string;
                    entityKind: "Experience"
                    | "ExperienceFragment";
                    entityKindId?: string;
                    entryIds?: string[];
                    messageId: string;
                    optimizationId?: string;
                    originalTimestamp: string;
                    parameters?: Record<string, JSONType>;
                    parentExperienceId?: string;
                    parentVariantId?: string;
                    sentAt: string;
                    timestamp: string;
                    type: "exo_node_view";
                    userId?: string;
                    variantId?: string;
                    variantIndex?: number;
                    viewDurationMs: number;
                    viewId: string;
                }
                | {
                    anonymousId?: string;
                    channel: "server"
                    | "mobile"
                    | "web";
                    componentId: string;
                    componentType?: "Entry" | "Variable";
                    context: {
                        app?: { name: string; version: string };
                        campaign: {
                            content?: string;
                            medium?: string;
                            name?: string;
                            source?: string;
                            term?: string;
                        };
                        gdpr?: { isConsentGiven: boolean };
                        library: { name: string; version: string };
                        locale?: string;
                        location?: {
                            city?: string;
                            continent?: string;
                            coordinates?: { latitude: number; longitude: number };
                            country?: string;
                            countryCode?: string;
                            postalCode?: string;
                            region?: string;
                            regionCode?: string;
                            timezone?: string;
                        };
                        page?: {
                            path: string;
                            query: Record<string, string | (...)[]>;
                            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;
                }
                | {
                    anonymousId?: string;
                    channel: "server"
                    | "mobile"
                    | "web";
                    componentId: string;
                    componentType?: "Entry" | "Variable";
                    context: {
                        app?: { name: string; version: string };
                        campaign: {
                            content?: string;
                            medium?: string;
                            name?: string;
                            source?: string;
                            term?: string;
                        };
                        gdpr?: { isConsentGiven: boolean };
                        library: { name: string; version: string };
                        locale?: string;
                        location?: {
                            city?: string;
                            continent?: string;
                            coordinates?: { latitude: number; longitude: number };
                            country?: string;
                            countryCode?: string;
                            postalCode?: string;
                            region?: string;
                            regionCode?: string;
                            timezone?: string;
                        };
                        page?: {
                            path: string;
                            query: Record<string, string | (...)[]>;
                            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;
                }
                | {
                    anonymousId?: string;
                    channel: "server"
                    | "mobile"
                    | "web";
                    context: {
                        app?: { name: string; version: string };
                        campaign: {
                            content?: string;
                            medium?: string;
                            name?: string;
                            source?: string;
                            term?: string;
                        };
                        gdpr?: { isConsentGiven: boolean };
                        library: { name: string; version: string };
                        locale?: string;
                        location?: {
                            city?: string;
                            continent?: string;
                            coordinates?: { latitude: number; longitude: number };
                            country?: string;
                            countryCode?: string;
                            postalCode?: string;
                            region?: string;
                            regionCode?: string;
                            timezone?: string;
                        };
                        page?: {
                            path: string;
                            query: Record<string, string | (...)[]>;
                            referrer: string;
                            search: string;
                            title?: string;
                            url: string;
                            [key: string]: JSONType;
                        };
                        screen?: { name: string; [key: string]: JSONType };
                        userAgent?: string;
                    };
                    entityId: string;
                    entityKind: "Experience"
                    | "ExperienceFragment";
                    entityKindId?: string;
                    entryIds?: string[];
                    messageId: string;
                    optimizationId?: string;
                    originalTimestamp: string;
                    parameters?: Record<string, JSONType>;
                    parentExperienceId?: string;
                    parentVariantId?: string;
                    sentAt: string;
                    timestamp: string;
                    type: "exo_node_click";
                    userId?: string;
                    variantId?: string;
                    variantIndex?: number;
                }
                | {
                    anonymousId?: string;
                    channel: "server"
                    | "mobile"
                    | "web";
                    context: {
                        app?: { name: string; version: string };
                        campaign: {
                            content?: string;
                            medium?: string;
                            name?: string;
                            source?: string;
                            term?: string;
                        };
                        gdpr?: { isConsentGiven: boolean };
                        library: { name: string; version: string };
                        locale?: string;
                        location?: {
                            city?: string;
                            continent?: string;
                            coordinates?: { latitude: number; longitude: number };
                            country?: string;
                            countryCode?: string;
                            postalCode?: string;
                            region?: string;
                            regionCode?: string;
                            timezone?: string;
                        };
                        page?: {
                            path: string;
                            query: Record<string, string | (...)[]>;
                            referrer: string;
                            search: string;
                            title?: string;
                            url: string;
                            [key: string]: JSONType;
                        };
                        screen?: { name: string; [key: string]: JSONType };
                        userAgent?: string;
                    };
                    entityId: string;
                    entityKind: "Experience"
                    | "ExperienceFragment";
                    entityKindId?: string;
                    entryIds?: string[];
                    hoverDurationMs: number;
                    hoverId: string;
                    messageId: string;
                    optimizationId?: string;
                    originalTimestamp: string;
                    parameters?: Record<string, JSONType>;
                    parentExperienceId?: string;
                    parentVariantId?: string;
                    sentAt: string;
                    timestamp: string;
                    type: "exo_node_hover";
                    userId?: string;
                    variantId?: string;
                    variantIndex?: number;
                }
                | {
                    anonymousId?: string;
                    channel: "server"
                    | "mobile"
                    | "web";
                    componentId: string;
                    componentType?: "Entry" | "Variable";
                    context: {
                        app?: { name: string; version: string };
                        campaign: {
                            content?: string;
                            medium?: string;
                            name?: string;
                            source?: string;
                            term?: string;
                        };
                        gdpr?: { isConsentGiven: boolean };
                        library: { name: string; version: string };
                        locale?: string;
                        location?: {
                            city?: string;
                            continent?: string;
                            coordinates?: { latitude: number; longitude: number };
                            country?: string;
                            countryCode?: string;
                            postalCode?: string;
                            region?: string;
                            regionCode?: string;
                            timezone?: string;
                        };
                        page?: {
                            path: string;
                            query: Record<string, string | (...)[]>;
                            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;
                }
            )[];
            profile: {
                audiences: string[];
                id: string;
                jurisdiction?: "US"
                | "EU";
                location: {
                    city?: string;
                    continent?: string;
                    coordinates?: { latitude: number; longitude: number };
                    country?: string;
                    countryCode?: string;
                    postalCode?: string;
                    region?: string;
                    regionCode?: string;
                    timezone?: string;
                };
                random: number;
                session: {
                    activeSessionLength: number;
                    averageSessionLength: number;
                    count: number;
                    id?: string;
                    isReturningVisitor: boolean;
                    landingPage: {
                        path: string;
                        query: Record<string, string | string[]>;
                        referrer: string;
                        search: string;
                        title?: string;
                        url: string;
                        [key: string]: JSONType;
                    };
                };
                stableId: string;
                traits: Record<string, JSONType>;
            };
        }[]

        Array of event batches to send.

        • events: (
              | {
                  anonymousId?: string;
                  channel: "server"
                  | "mobile"
                  | "web";
                  context: {
                      app?: { name: string; version: string };
                      campaign: {
                          content?: string;
                          medium?: string;
                          name?: string;
                          source?: string;
                          term?: string;
                      };
                      gdpr?: { isConsentGiven: boolean };
                      library: { name: string; version: string };
                      locale?: string;
                      location?: {
                          city?: string;
                          continent?: string;
                          coordinates?: { latitude: number; longitude: number };
                          country?: string;
                          countryCode?: string;
                          postalCode?: string;
                          region?: string;
                          regionCode?: string;
                          timezone?: string;
                      };
                      page?: {
                          path: string;
                          query: Record<string, string | (...)[]>;
                          referrer: string;
                          search: string;
                          title?: string;
                          url: string;
                          [key: string]: JSONType;
                      };
                      screen?: { name: string; [key: string]: JSONType };
                      userAgent?: string;
                  };
                  entityId: string;
                  entityKind: "Experience"
                  | "ExperienceFragment";
                  entityKindId?: string;
                  entryIds?: string[];
                  messageId: string;
                  optimizationId?: string;
                  originalTimestamp: string;
                  parameters?: Record<string, JSONType>;
                  parentExperienceId?: string;
                  parentVariantId?: string;
                  sentAt: string;
                  timestamp: string;
                  type: "exo_node_view";
                  userId?: string;
                  variantId?: string;
                  variantIndex?: number;
                  viewDurationMs: number;
                  viewId: string;
              }
              | {
                  anonymousId?: string;
                  channel: "server"
                  | "mobile"
                  | "web";
                  componentId: string;
                  componentType?: "Entry" | "Variable";
                  context: {
                      app?: { name: string; version: string };
                      campaign: {
                          content?: string;
                          medium?: string;
                          name?: string;
                          source?: string;
                          term?: string;
                      };
                      gdpr?: { isConsentGiven: boolean };
                      library: { name: string; version: string };
                      locale?: string;
                      location?: {
                          city?: string;
                          continent?: string;
                          coordinates?: { latitude: number; longitude: number };
                          country?: string;
                          countryCode?: string;
                          postalCode?: string;
                          region?: string;
                          regionCode?: string;
                          timezone?: string;
                      };
                      page?: {
                          path: string;
                          query: Record<string, string | (...)[]>;
                          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;
              }
              | {
                  anonymousId?: string;
                  channel: "server"
                  | "mobile"
                  | "web";
                  componentId: string;
                  componentType?: "Entry" | "Variable";
                  context: {
                      app?: { name: string; version: string };
                      campaign: {
                          content?: string;
                          medium?: string;
                          name?: string;
                          source?: string;
                          term?: string;
                      };
                      gdpr?: { isConsentGiven: boolean };
                      library: { name: string; version: string };
                      locale?: string;
                      location?: {
                          city?: string;
                          continent?: string;
                          coordinates?: { latitude: number; longitude: number };
                          country?: string;
                          countryCode?: string;
                          postalCode?: string;
                          region?: string;
                          regionCode?: string;
                          timezone?: string;
                      };
                      page?: {
                          path: string;
                          query: Record<string, string | (...)[]>;
                          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;
              }
              | {
                  anonymousId?: string;
                  channel: "server"
                  | "mobile"
                  | "web";
                  context: {
                      app?: { name: string; version: string };
                      campaign: {
                          content?: string;
                          medium?: string;
                          name?: string;
                          source?: string;
                          term?: string;
                      };
                      gdpr?: { isConsentGiven: boolean };
                      library: { name: string; version: string };
                      locale?: string;
                      location?: {
                          city?: string;
                          continent?: string;
                          coordinates?: { latitude: number; longitude: number };
                          country?: string;
                          countryCode?: string;
                          postalCode?: string;
                          region?: string;
                          regionCode?: string;
                          timezone?: string;
                      };
                      page?: {
                          path: string;
                          query: Record<string, string | (...)[]>;
                          referrer: string;
                          search: string;
                          title?: string;
                          url: string;
                          [key: string]: JSONType;
                      };
                      screen?: { name: string; [key: string]: JSONType };
                      userAgent?: string;
                  };
                  entityId: string;
                  entityKind: "Experience"
                  | "ExperienceFragment";
                  entityKindId?: string;
                  entryIds?: string[];
                  messageId: string;
                  optimizationId?: string;
                  originalTimestamp: string;
                  parameters?: Record<string, JSONType>;
                  parentExperienceId?: string;
                  parentVariantId?: string;
                  sentAt: string;
                  timestamp: string;
                  type: "exo_node_click";
                  userId?: string;
                  variantId?: string;
                  variantIndex?: number;
              }
              | {
                  anonymousId?: string;
                  channel: "server"
                  | "mobile"
                  | "web";
                  context: {
                      app?: { name: string; version: string };
                      campaign: {
                          content?: string;
                          medium?: string;
                          name?: string;
                          source?: string;
                          term?: string;
                      };
                      gdpr?: { isConsentGiven: boolean };
                      library: { name: string; version: string };
                      locale?: string;
                      location?: {
                          city?: string;
                          continent?: string;
                          coordinates?: { latitude: number; longitude: number };
                          country?: string;
                          countryCode?: string;
                          postalCode?: string;
                          region?: string;
                          regionCode?: string;
                          timezone?: string;
                      };
                      page?: {
                          path: string;
                          query: Record<string, string | (...)[]>;
                          referrer: string;
                          search: string;
                          title?: string;
                          url: string;
                          [key: string]: JSONType;
                      };
                      screen?: { name: string; [key: string]: JSONType };
                      userAgent?: string;
                  };
                  entityId: string;
                  entityKind: "Experience"
                  | "ExperienceFragment";
                  entityKindId?: string;
                  entryIds?: string[];
                  hoverDurationMs: number;
                  hoverId: string;
                  messageId: string;
                  optimizationId?: string;
                  originalTimestamp: string;
                  parameters?: Record<string, JSONType>;
                  parentExperienceId?: string;
                  parentVariantId?: string;
                  sentAt: string;
                  timestamp: string;
                  type: "exo_node_hover";
                  userId?: string;
                  variantId?: string;
                  variantIndex?: number;
              }
              | {
                  anonymousId?: string;
                  channel: "server"
                  | "mobile"
                  | "web";
                  componentId: string;
                  componentType?: "Entry" | "Variable";
                  context: {
                      app?: { name: string; version: string };
                      campaign: {
                          content?: string;
                          medium?: string;
                          name?: string;
                          source?: string;
                          term?: string;
                      };
                      gdpr?: { isConsentGiven: boolean };
                      library: { name: string; version: string };
                      locale?: string;
                      location?: {
                          city?: string;
                          continent?: string;
                          coordinates?: { latitude: number; longitude: number };
                          country?: string;
                          countryCode?: string;
                          postalCode?: string;
                          region?: string;
                          regionCode?: string;
                          timezone?: string;
                      };
                      page?: {
                          path: string;
                          query: Record<string, string | (...)[]>;
                          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;
              }
          )[]

          Insights events to record for this profile.

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

          Complete profile snapshot used to associate events with a user.

          • audiences: string[]

            List of audience identifiers that this profile belongs to.

          • id: string

            Primary identifier of the profile.

          • Optionaljurisdiction?: "US" | "EU"

            Data-residency jurisdiction of the profile's storage, when the Experience API reports it.

            Set by the Experience API host the profile was written through (experience.eu.ninetailed.co stores it in the EU).

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

            Geo-location information associated with the profile.

            • Optionalcity?: string

              City name associated with the location.

            • Optionalcontinent?: string

              Continent name associated with the location.

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

              Geographical coordinates for the location.

              • latitude: number

                Latitude component of the coordinates.

              • longitude: number

                Longitude component of the coordinates.

            • Optionalcountry?: string

              Country name associated with the location.

            • OptionalcountryCode?: string

              Country code associated with the location.

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

            • OptionalpostalCode?: string

              Postal or ZIP code associated with the location.

            • Optionalregion?: string

              Region or state name associated with the location.

            • OptionalregionCode?: string

              Region or state code associated with the location.

            • Optionaltimezone?: string

              Time zone identifier associated with the location.

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

          • random: number

            Random value associated with the profile.

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

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

            Aggregated session statistics for the profile.

            • activeSessionLength: number

              Duration of the active session.

            • averageSessionLength: number

              Average session duration across all sessions represented by this record.

              The unit must match SessionStatistics.activeSessionLength.

            • count: number

              Number of sessions associated with this profile or identifier.

              Often used in combination with SessionStatistics.averageSessionLength.

            • Optionalid?: string

              Session identifier, when supplied by the Experience API.

            • isReturningVisitor: boolean

              Indicates whether the visitor has been seen before.

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

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

              Landing page for the session.

              Represents the first page the user visited in this session.

              Page

              • path: string

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

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

                Parsed query parameters for the page.

                Query

              • referrer: string

                Referrer URL that led to the current page.

              • search: string

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

              • Optionaltitle?: string

                Title of the page as seen by the user.

              • url: string

                Full URL of the page.

          • stableId: string

            Stable, long-lived identifier of the profile.

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

          • traits: Record<string, JSONType>

            Traits describing the profile (user-level attributes).

            Traits

      • options: InsightsApiClientRequestOptions = {}

        Optional request options, including a per-call beacon sender.

      Returns Promise<boolean>

      true when the event batch is successfully queued by the beacon sender or a direct request is successfully sent, false otherwise.

      Each batch requires a complete Profile snapshot. An ID-only profile fails validation before either sender is invoked. Beacon acceptance does not confirm a successful Insights service response.

      If a beacon sender is provided, it will be invoked first with the serialized request body. When the sender returns true, the events are considered successfully queued and no network request is made by this method.

      If the sender is missing, returns false, or throws, the events are emitted immediately via fetch.

      const success = await insightsClient.sendBatchEvents(batches)
      
      // Use Beacon for a last-chance lifecycle flush
      const success = await insightsClient.sendBatchEvents(batches, {
      beacon: (url, body) => navigator.sendBeacon(url, body),
      })