analytics-event-v1.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schema.yext.com/api/analytics/event",
  "$version": "1",
  "type": "object",
  "title": "Analytics Event",
  "description": "Represents an event for analytics purposes.",
  "required": [
    "action"
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "const": "https://schema.yext.com/api/analytics/event/v1"
    },
    "action": {
      "description": "The action which caused the event.",
      "oneOf": [
        {
          "type": "string",
          "title": "Standard",
          "caseSensitive": false,
          "description": "The action which caused the event. `caseSensitive: false`",
          "enum": [
            "ADD_TO_CART",
            "ALL_TAB_NAVIGATION",
            "APPLY",
            "AUTO_COMPLETE_SELECTION",
            "BACKWARD_PAGINATE",
            "BOOK",
            "BRAND_ICON",
            "CALL_TO_ACTION",
            "CASE_START",
            "CASE_SUBMITTED",
            "CHAT_IMPRESSION",
            "CHAT_LINK_CLICK",
            "CHAT_RESPONSE",
            "COLLAPSE",
            "DIRECTIONS",
            "EVENT",
            "EXPAND",
            "FEATURED_MESSAGE",
            "FILTERING_WITHIN_SECTION",
            "FORWARD_PAGINATE",
            "HEADER_LINKS",
            "ITEM_IN_LIST",
            "MAP_CARD",
            "MAP_PIN",
            "MENU",
            "MESSAGE",
            "ORDER",
            "PAGINATE",
            "PHONE",
            "POST",
            "PRESET_PROMPT",
            "PRODUCT",
            "PROFILE",
            "QUESTION_FOCUS",
            "QUESTION_SUBMIT",
            "REMOVED_FILTER",
            "REVIEW",
            "SCROLL_TO_BOTTOM_OF_PAGE",
            "SEARCH_BAR_IMPRESSION",
            "SEARCH_CLEAR_BUTTON",
            "THUMBS_DOWN",
            "THUMBS_UP",
            "TICKET_URL",
            "TITLE",
            "VERTICAL_TAB_NAVIGATION",
            "VERTICAL_VIEW_ALL",
            "VOICE_START",
            "VOICE_STOP",
            "WEBSITE"
          ]
        },
        {
          "type": "string",
          "pattern": "^[Cc]_[a-zA-Z0-9_-]{1,30}$",
          "title": "Custom",
          "caseSensitive": false,
          "description": "Specifies a custom action for the event, which must start with \"`C_`\". `caseSensitive: false`, `pattern: \"^[Cc]_[a-zA-Z0-9_-]{1,30}$\"`"
        }
      ]
    },
    "authorization": {
      "type": "string",
      "description": "An alternative to using the Authorization HTTP header. If a value is provided, it will override any Authorization header. Api keys should be formatted like \"KEY <apiKey>\", access tokens should be formatted like \"Bearer <bearerToken>\"",
      "minLength": 1,
      "maxLength": 8192,
      "pattern": "^(KEY|Bearer)\\s.+$"
    },
    "bot": {
      "description": "Whether the event is the result of bot activity.",
      "default": "$auto",
      "oneOf": [
        {
          "type": "boolean",
          "description": "Specifies that the event should not be considered bot traffic."
        },
        {
          "const": "$auto",
          "title": "$auto",
          "description": "Indicates to automatically detect whether this event originates from a bot."
        }
      ]
    },
    "browserAgent": {
      "type": "object",
      "additionalProperties": false,
      "description": "Information about the visitors device and browser.",
      "default": {
        "browser": "$auto",
        "browserVersion": "$auto",
        "device": "$auto",
        "deviceClass": "$auto",
        "os": "$auto",
        "osVersion": "$auto",
        "userAgent" : "$auto"
      },
      "properties": {
        "browser": {
          "default": "$auto",
          "description": "The browser associated with the event.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "(?!\\$auto$)(^[\\x20-\\x7E]{1,128}$)",
              "title": "string",
              "description": "Specifies the browser for the event. `pattern: \"^[\\x20-\\x7E]{1,128}$\"`"
            },
            {
              "const": "$auto",
              "title": "$auto",
              "description": "Indicates to automatically determine the browser from request headers, or the value of the `userAgent` property if specified."
            },
            {
              "type": "null",
              "title": "null",
              "description": "Specifies that no browser should be stored with the event."
            }
          ]
        },
        "browserVersion": {
          "default": "$auto",
          "description": "The browser version associated with the event.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "(?!\\$auto$)(^[\\x20-\\x7E]{1,128}$)",
              "title": "string",
              "description": "Specifies the browser version for the event. `pattern: \"^[\\x20-\\x7E]{1,128}$\"`"
            },
            {
              "const": "$auto",
              "title": "$auto",
              "description": "Indicates to automatically determine the browser version from request headers, or the value of the `userAgent` property if specified."
            },
            {
              "type": "null",
              "title": "null",
              "description": "Specifies that no browser version should be stored with the event."
            }
          ]
        },
        "device": {
          "default": "$auto",
          "description": "The device associated with the event.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "(?!\\$auto$)(^[\\x20-\\x7E]{1,128}$)",
              "title": "string",
              "description": "Specifies the device for the event. `pattern: \"^[\\x20-\\x7E]{1,128}$\"`"
            },
            {
              "const": "$auto",
              "title": "$auto",
              "description": "Indicates to automatically determine the device from request headers, or the value of the `userAgent` property if specified."
            },
            {
              "type": "null",
              "title": "null",
              "description": "Specifies that no device should be stored with the event."
            }
          ]
        },
        "deviceClass": {
          "default": "$auto",
          "description": "The class of device associated with the event.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "(?!\\$auto$)(^[\\x20-\\x7E]{1,32}$)",
              "caseSensitive": false,
              "title": "string",
              "description": "Specifies the device class for the event. `caseSensitive: false`, `pattern: \"^[\\x20-\\x7E]{1,32}$\"`"
            },
            {
              "const": "$auto",
              "title": "$auto",
              "description": "Indicates to automatically determine the device class from request headers, or the value of the `userAgent` property if specified."
            },
            {
              "type": "null",
              "title": "null",
              "description": "Specifies that no device class should be stored with the event."
            }
          ]
        },
        "os": {
          "default": "$auto",
          "description": "The operating system associated with the event.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "(?!\\$auto$)(^[\\x20-\\x7E]{1,128}$)",
              "title": "string",
              "description": "Specifies the operating system for the event. `pattern: \"^[\\x20-\\x7E]{1,128}$\"`"
            },
            {
              "const": "$auto",
              "title": "$auto",
              "description": "Indicates to automatically determine the operating system from request headers, or the value of the `userAgent` property if specified."
            },
            {
              "type": "null",
              "title": "null",
              "description": "Specifies that no operating system should be stored with the event."
            }
          ]
        },
        "osVersion": {
          "default": "$auto",
          "description": "The operating system version associated with the event.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "(?!\\$auto$)(^[\\x20-\\x7E]{1,128}$)",
              "title": "string",
              "description": "Specifies the operating system version for the event. `pattern: \"^[\\x20-\\x7E]{1,128}$\"`"
            },
            {
              "const": "$auto",
              "title": "$auto",
              "description": "Indicates to automatically determine the operating system version from request headers, or the value of the `userAgent` property if specified."
            },
            {
              "type": "null",
              "title": "null",
              "description": "Specifies that no operating system version should be stored with the event."
            }
          ]
        },
        "userAgent": {
          "description": "The user agent string for the event.",
          "default": "$auto",
          "oneOf": [
            {
              "type": "string",
              "pattern": "(?!\\$auto$)(^[\\x20-\\x7E]{1,8192}$)",
              "title": "string",
              "description": "Specifies the user agent string for the event. `pattern: \"^[\\x20-\\x7E]{1,8192}$\"`"
            },
            {
              "const": "$auto",
              "title": "$auto",
              "description": "Indicates to use the `User-Agent` header of the request."
            },
            {
              "type": "null",
              "title": "null",
              "description": "Specifies that no user agent should be stored with the event."
            }
          ]
        }
      }
    },
    "chat": {
      "type": "object",
      "title": "Chat",
      "description": "The Yext Chat properties of the event.",
      "properties": {
        "botId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50,
          "description": "The ID of the chat bot an event was tied to."
        },
        "conversationId": {
          "type": "string",
          "minLength": 48,
          "maxLength": 48,
          "description": "The ID of a conversation an event was tied to. Not all events are tied to a specific conversation. For example, both impressions are registered before the conversation begins. Must be 48 chars long"
        },
        "responseId": {
          "type": "string",
          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
          "description": "The ID of the response an event was tied to. Not all events are tied to a specific response, but if present it must be a valid ULID. This is analogous to queryId in Search. `pattern: \"^[0-9A-HJKMNP-TV-Z]{26}$\"`"
        }
      },
      "required": [
        "botId"
      ],
      "additionalProperties": false
    },
    "clientSdk": {
      "type": "object",
      "description": "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.",
      "maxProperties": 10,
      "additionalProperties": {
        "type": "string",
        "maxLength": 32
      },
      "propertyNames": {
        "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,31}$"
      }
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000000,
      "default": 1,
      "description": "When one record summarizes multiple events, this is the number of events the record represents. The event is treated as if it is duplicated this many times."
    },
    "customTags": {
      "type": "object",
      "description": "Up to 10 pairs matching custom string keys to string values to associate with the event. Keys are case-insensitive; values are case-sensitive. Property Name`pattern: \"^[a-zA-Z][a-zA-Z0-9_]{0,31}$\"`",
      "maxProperties": 10,
      "additionalProperties": {
        "type": "string",
        "maxLength": 64
      },
      "propertyNames": {
        "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,31}$"
      }
    },
    "customValues": {
      "type": "object",
      "description": "Up to 10 pairs matching custom string keys to number values to associate with the event. Keys are case-insensitive. Property Name `pattern: \"^[a-zA-Z][a-zA-Z0-9_]{0,31}$\"`",
      "maxProperties": 10,
      "additionalProperties": {
        "type": "string",
        "maxLength": 64
      },
      "propertyNames": {
        "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,31}$"
      }
    },
    "destinationUrl": {
      "type": "string",
      "format": "uri",
      "title": "URL",
      "description": "The URL of the page the event is directing the visitor to. `format: uri`"
    },
    "entity": {
      "type": ["string","integer"],
      "oneOf": [
        {
          "type": "string",
          "title": "entityId",
          "minLength": 1,
          "maxLength": 38,
          "description": "The mutable, customer-settable entity ID for the entity associated with the event. "
        },
        {
          "type": "integer",
          "title": "entityUid",
          "minimum": 0,
          "description": "The immutable entity ID set by the system. This is an internal ID."
        }
      ]
    },
    "internalUser": {
      "type": "boolean",
      "default":false,
      "description": "Indicates whether the event is the result of internal activity."
    },
    "ip": {
      "type": ["object","null"],
      "description": "The IP address for the event.",
      "default": {
        "address": "$auto",
        "algorithm": "HASH"
      },
      "oneOf": [
        {
          "type": "object",
          "title": "IP",
          "properties": {
            "address": {
              "oneOf": [
                {
                  "type": "string",
                  "format": "ipv4",
                  "title": "IPv4",
                  "description": "Specifies the IPv4 address associated with the event. `format: \"ipv4\"`"
                },
                {
                  "const": "$auto",
                  "title": "$auto",
                  "description": "Indicates to use the Source IP address from the IP header of the request. This IP address is only used if the `Yext-Opt-In: ip` header is present."
                }
              ]
            },
            "algorithm": {
              "type": "string",
              "enum": [
                "HASH"
              ],
              "description": "The algorithm to use to anonymize the IP address after collection."
            }
          },
          "required": [
            "address",
            "algorithm"
          ],
          "additionalProperties": false
        },
        {
          "type": "null",
          "title": "null",
          "description": "Specifies that no IP address should be associated with the event."
        }
      ]
    },
    "label": {
      "type": "string",
      "description": "A label assigned to the event, e.g. a CTA label.",
      "minLength": 1,
      "maxLength": 16777216
    },
    "locale": {
      "default": "$auto",
      "description": "The locale of the user who generated the event.",
      "oneOf": [
        {
          "type": "string",
          "title": "Locale",
          "minLength": 1,
          "maxLength": 16,
          "pattern": "^(?!(\\$auto)$).*$",
          "description": "Specifies the locale of the visitor for the event, e.g. `en-US`."
        },
        {
          "const": "$auto",
          "title": "$auto",
          "description": "Indicates to automatically determine the locale from the Accept-Language header."
        },
        {
          "type": "null",
          "title": "null",
          "description": "Specifies that no locale information should be stored with the event."
        }
      ]
    },
    "location": {
      "default": "$auto",
      "description": "The location information of the visitor for the event.",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "title": "Location",
          "description": "Specifies the location information of visitor for the event.",
          "properties": {
            "coordinates": {
              "type": "object",
              "description": "The geographic coordinates of the visitor for the event.",
              "properties": {
                "latitude": {
                  "type": "number",
                  "minimum": -90,
                  "maximum": 90,
                  "description": "The latitude, in degrees North."
                },
                "longitude": {
                  "type": "number",
                  "minimum": -180,
                  "maximum": 180,
                  "description": "The longitude, in degrees East."
                }
              },
              "required": [
                "latitude",
                "longitude"
              ],
              "additionalProperties": false
            },
            "country": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "caseSensitive": false,
              "description": "The country of the visitor for the event, as a ISO 3166-1 alpha-2 country code. `caseSensitive: false`"
            }
          }
        },
        {
          "const": "$auto",
          "title": "$auto",
          "description": "Indicates to automatically determine all location information from the request's IP address, or the value of the `ip` property if specified."
        },
        {
          "type": "null",
          "title": "null",
          "description": "Specifies that no location information should be stored with the event."
        }
      ]
    },
    "nonce": {
      "type": "string",
      "pattern": "^[\\x20-\\x7E]{1,36}$",
      "description": "Deduplication ID for the event. Events from the same app for the same business with the same nonce will get de-duplicated. `pattern: \"^[\\x20-\\x7E]{1,36}$\"`"
    },
    "pageUrl": {
      "description": "The URL of the page the event occurred on.",
      "default": "$auto",
      "oneOf": [
        {
          "type": "string",
          "format": "uri",
          "title": "URL",
          "description": "Specifies the URL of the page the event occurred on. `format: uri`"
        },
        {
          "const": "$auto",
          "title": "$auto",
          "description": "Indicates to use the `Referer` header of the request."
        },
        {
          "type": "null",
          "title": "null",
          "description": "Specifies that no page URL should be stored with the event."
        }
      ]
    },
    "referrerUrl": {
      "type": "string",
      "format": "uri",
      "description": "The URL of the page which the visitor came from prior to the event."
    },
    "searchTerm": {
      "type": "string",
      "description": "The query entered by the user.",
      "minLength": 1,
      "maxLength": 16777216
    },
    "sessionId": {
      "type": "string",
      "pattern": "^[\\x20-\\x7E]{1,36}$",
      "description": "ID of the user session associated with event. `pattern: \"^[\\x20-\\x7E]{1,36}$\"`"
    },
    "timestamp": {
      "description": "The timestamp at which the event occurred.",
      "default": "$auto",
      "oneOf": [
        {
          "type": "string",
          "format": "date-time",
          "title": "ISO Timestamp",
          "description": "Specifies the timestamp at which the event occurred. `format: \"date-time\"`"
        },
        {
          "type": "number",
          "minimum": 0,
          "maximum": 3250091520000,
          "title": "Epoch millisecond",
          "description": "Specifies the timestamp at which the event occurred as the number of milliseconds since 1970-01-01T00:00:00Z UTC, ignoring leap seconds."
        },
        {
          "const": "$auto",
          "title": "$auto",
          "description": "Indicates to use the time when the request was received as the event timestamp."
        }
      ]
    },
    "value": {
      "type": "object",
      "title": "Value",
      "description": "The monetary value of the event",
      "properties": {
        "amount": {
          "type": "number",
          "multipleOf": 0.0001,
          "description": "The monetary value of the event."
        },
        "currency": {
          "type": "string",
          "minLength": 3,
          "maxLength": 3,
          "pattern": "^[A-Z]{3}$",
          "description": "The ISO 4217 currency code of the currency the value is expressed in. `pattern: \"^[A-Z]{3}$\"`"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "additionalProperties": false
    },
    "visitor": {
      "type": "object",
      "description": "The visitor related to the event. Keys are visitor methods and values are visitor IDs. PropertyName pattern: \"^[a-zA-Z0-9_-]{1,16}$\". Value pattern: \"^[\\x20-\\x7E]{1,64}$\"",
      "patternProperties": {
        "^[a-zA-Z0-9_-]{1,16}$": {
          "type": "string",
          "pattern": "^[\\x20-\\x7E]{1,64}$"
        }
      },
      "maxProperties": 1
    }
  },
  "if": {
    "properties": { "action": { "const": "CHAT_RESPONSE" } }
  },
  "then": {
    "properties": { "chat": { "required": ["botId", "responseId"] } },
    "required": ["chat"]
  }
}