@yext/analytics

/** * The action types accepted by the Analytics Events API. * * @public */ export declare type Action = `C_${string}` | 'ADD_TO_CART' | 'ALL_TAB_NAVIGATION' | 'APPLY' | 'AUTO_COMPLETE_SELECTION' | 'BACKWARD_PAGINATE' | 'BOOK' | 'BRAND_ICON' | 'CASE_START' | 'CASE_SUBMITTED' | 'CHAT_IMPRESSION' | 'CHAT_LINK_CLICK' | 'CHAT_RESPONSE' | 'CITATION_CLICK' | 'COLLAPSE' | 'CTA_CLICK' | 'DRIVING_DIRECTIONS' | 'EVENT' | 'EXPAND' | 'FEATURED_MESSAGE' | 'FILTERING_WITHIN_SECTION' | 'FORWARD_PAGINATE' | 'HEADER_LINKS' | 'ITEM_IN_LIST' | 'LINK' | 'MAP_CARD' | 'MAP_PIN' | 'MENU' | 'MESSAGE' | 'ORDER' | 'PAGE_VIEW' | 'PAGINATE' | 'POST' | 'PRESET_PROMPT' | 'PRODUCT' | 'PROFILE' | 'QUESTION_FOCUS' | 'QUESTION_SUBMIT' | 'REMOVED_FILTER' | 'REVIEW' | 'SCROLL_TO_BOTTOM_OF_PAGE' | 'SEARCH_BAR_IMPRESSION' | 'SEARCH_CLEAR_BUTTON' | 'TAP_TO_CALL' | 'THUMBS_DOWN' | 'THUMBS_UP' | 'TICKET_URL' | 'TITLE' | 'VERTICAL_TAB_NAVIGATION' | 'VERTICAL_VIEW_ALL' | 'VOICE_START' | 'VOICE_STOP' | 'WEBSITE'; /** * The Yext Analytics Events SDK. * Returns an AnalyticsEventService given an AnalyticsConfig. * @public */ export declare function analytics(config: AnalyticsConfig): AnalyticsEventService; /** * The main configuration options for Analytics Events. * * @public */ export declare interface AnalyticsConfig { /** Used for specifying if an API Key or Bearer Token is used for the authorization property. */ authorizationType: 'apiKey' | 'bearer'; /** The API Key, OAuth, or bearer token for accessing the Analytics Events API. */ authorization: string; /** The Yext environment to send requests to. Defaults to 'PRODUCTION'. */ env?: Environment; /** The region to send requests to. Defaults to 'US'. */ region?: Region; /** * Whether to enable session tracking for analytics events. * Defaults to true for both environments. If set to false, sessionId will automatically * be set to undefined in the event payload. * @remarks * This generates a ULID to tie together events in a single browsing session. */ sessionTrackingEnabled?: boolean; /** * Used to force sending the request with fetch even if the browser * does not support fetch with the keepalive flag (like Firefox). * If the browser does support it, fetch is used by default. */ forceFetch?: boolean; /** * Used to enable debug mode, which is false by default. * When enabled the SDK will not send requests to the Events API, but will log the request * with other useful debug information instead. */ debug?: boolean; } /** * A service for reporting Yext analytics events * * @public */ export declare interface AnalyticsEventService { /** * Creates a new AnalyticsEventService with the following values defined * as the default when making a report. * * @param payload - desired values to be applied. The new payload will * override any overlapping values. */ with(payload: EventPayload): AnalyticsEventService; /** * Reports an analytics event. Operand will throw an error if the request * fails. The request will default to being sent via fetch, with keepalive set to true, * if supported by the browser, and a Promise of an EventAPIResponse will be returned. * Otherwise, the request will be sent via the Beacon API, unless the forceFetch flag is * toggled, and a boolean will be returned. * * @param payload - desired values to be applied. The new payload will * override any overlapping values. */ report(payload?: EventPayload): Promise<string>; } declare type Coordinates = { coordinates: { latitude: number; longitude: number; }; }; /** * The Yext Environments * * @remarks * Affects the domain the requests are sent to. * * @public */ export declare type Environment = 'PRODUCTION' | 'SANDBOX'; /** * The payload accepted by the Analytics Events API. * * @public */ export declare interface EventPayload { /** The user action which caused the event, e.g. ADD_TO_CART, THUMBS_UP, C_CUSTOM_ACTION */ action?: Action; /** The authorization token for the request. This will be setup from the Key or Bearer in the config. */ authorization?: string; /** Whether the event is the result of bot activity. * * If not specified the system will automatically detect whether * this event originates from a bot. */ bot?: boolean; /** Information about the visitors device and browser. * * If not specified the system will automatically detect * the values from request headers or `userAgent` property. */ browserAgent?: { /** The browser associated with the event. */ browser?: string; /** The browser version associated with the event. */ browserVersion?: string; /** The device associated with the event. */ device?: string; /** The device class associated with the event. */ deviceClass?: string; /** The operating system associated with the event. */ os?: string; /** The operating system version associated with the event. */ osVersion?: string; /** The user agent associated with the event. */ userAgent?: string; }; /** Fields specific to reporting Chat Analytics Events */ chat?: { /** The ID of the bot that generated the event. */ botId: string; /** The ID of the conversation in which the event occurred. */ conversationId?: string; /** The ID of the individual response in which the event occurred. */ responseId?: string; }; /** * For the Yext client SDKs involved in the event, this is an object mapping * the names of those SDKs to the version labels of those SDKs. */ clientSdk?: Record<string, string>; /** * When the record summarizes multiple events, the number of events the record represents. * The event is treated as if it is duplicated this many times. */ count?: number; /** * Up to 10 pairs matching custom string keys to string values to associate with the event. * Keys are case-insensitive; values are case-sensitive. */ customTags?: Record<string, string>; /** * Up to 10 pairs matching custom string keys to number values to associate with the event. * Keys are case-insensitive. */ customValues?: Record<string, number>; /** The URL of the page the event is directing the visitor to. */ destinationUrl?: string; /** The Yext entity to which the event corresponds. If passed as a string, the value is * the mutable, customer-settable entity ID for the entity associated with the event. * If passed as a number, it is the immutable entity ID (UID) set by the system. This is an internal ID. */ entity?: string | number; /** Indicates whether the event is the result of internal activity. */ internalUser?: boolean; /** The IP address for the event.*/ ip?: { /** The IPv4 address associated with the event. * * If not specified the system will use the Source IP address * from the autogenerated IP header of the request. */ address: string; /** The algorithm to use to anonymize the IP address after collection. */ algorithm: string; }; /** A label assigned to the event, e.g. a CTA label. */ label?: string; /** The locale of the user who generated the event. * * If not specified the system will automatically * determine the locale from the autogenerated Accept-Language header. */ locale?: string; /** The location information of the visitor for the event. * Either a Coordinates object with both latitude and longitude or a string * with the country of the visitor for the event, as a ISO 3166-1 alpha-2 country code. * For more information see https://www.iso.org/iso-3166-country-codes.html. * * If not specified the system will automatically * determine all location information from the request's IP address, * or the value of the `ip` property if specified. */ location?: Coordinates | string; /** Fields specific to reporting Yext Pages Analytics Events */ pages?: { /** The scope of an action. Applies to Pages events. */ scope?: string; /** The Event name as it was used in previous analytics implementations. */ originalEventName?: string; siteUid?: number; template?: string; }; /** The URL of the page where the event occurred. * * If not specified the system will automatically use document.URL */ pageUrl?: string; /** The URL of the page which the visitor came from prior to the event. * * If not specified the system will automatically use document.referrer */ referrerUrl?: string; /** Fields specific to reporting Yext Search Analytics Events */ search?: { /** Unique identifier of the search */ searchId?: string; /** Unique identifier for a single query across pagination */ queryId?: string; /** The vertical key on which the event occurred, if any */ verticalKey?: string; /** Whether or not the event occurred on a direct answer card */ isDirectAnswer?: boolean; /** The label of the version number of the search config. Either "PRODUCTION" or "STAGING" */ versionLabel?: VersionLabel; /** The version number of the search config */ versionNumber?: number; /** The identifier of the search experience. */ experienceKey: string; /** Whether or not the event occurred on a generative direct answer card */ isGenerativeDirectAnswer?: boolean; }; /** The query entered by the user. */ searchTerm?: string; /** Unique identifier to tie together events in a single browsing session */ sessionId?: string | null; /** The timestamp at which the event occurred, in ISO format. * For example, September 27, 2022 at 6 p.m. is represented as * 2022-09-27 18:00:00.000. * For more information, see https://www.iso.org/iso-8601-date-and-time-format.html. * * If not specified the system will automatically * use the time when the request was received in UTC as the event timestamp. */ timestamp?: Date | string; /** The monetary value of the event. */ value?: { /** The monetary value. */ amount: number; /** The ISO 4217 currency code of the currency the value is expressed in. * For example, "USD" for US dollars. * * For more information see https://www.iso.org/iso-4217-currency-codes.html. */ currency: string; }; /** * Information used to associate analytics with a particular user. * * @remarks * Keys are visitor methods and values are visitor IDs. * Key pattern: `^[a-zA-Z0-9_-]{1,16}$`. * Value pattern: `^[\x20-\x7E]{1,64}$` * * @public */ visitor?: Record<string, string>; } /** * The physical region of the Yext account * * @remarks * Affects the domain the requests are sent to. * * @public */ export declare type Region = 'US' | 'EU'; /** * An alternative entry point for the Yext Analytics Events SDK, currently used by Google Tag Manager. * This method reads the config and payload from the variable analyticsEventPayload stored * in the global window object. The config and payload are then passed to the report function to be sent * to the Yext Analytics Events API. * @public */ export declare function reportBrowserAnalytics(): Promise<string>; /** * An enum for the Search Version Labels * * @remarks * Affects the contents of the versionLabel field in the search object field in the event payload. * * @public */ export declare type VersionLabel = 'PRODUCTION' | 'STAGING'; export { }