Skip to content

Event Specification Reference

Each part of an event within Orbee's Specification is detailed below.

Event Structure

When you fire events to Orbee, you must provide the data in a format our backend can understand and process. We work and translate many industry-standard formats both in and out of our systems and services. All fields are camel case, like 'camelCase'.

Events from Orbee's SDKs take the following fields:

Field Name Value Type Required Description
action text yes The action being performed, see below
object text yes The object type the action happened on
vendor text yes The vendor the event originated from, or on
product text yes The product the event originated from, or on
label text no (suggested yes) A readable label that is descriptive of the entire event
score number no The score of the action, left as interpretable by the implementation
instanceID text no The ID of the object instance from the vendor and/or product

All other parameters that are provided are specific to the event context, or entirely optional. You'll find suggested fields in the reference material below.

Event Actions

Event actions are the verb of the event. They describe the action being performed on whatever object is on the media. The current list of supported actions are:

  • View
  • Select
  • Change
  • Open
  • Close
  • Start
  • Cancel
  • Complete
  • Submit
  • Marker
  • Associate

Any other actions will be treated as custom events - they are not interpretable or applicable within Orbee's systems, but will appear in reporting dashboards and our API.

View

Requirements:

  • Use when: visible or viewable
  • Notes: certain % viewable, visible for a certain amount of time

The view event should be used to track what the shopper has viewed on the automotive media, like vehicles, widgets, pages, offers, etc. When the object is only on a small part of the page and isn't visible immediately, it could be more accurate to wait until:

  • it's completely visible
  • it's a certain % visible
  • it's been visible for a certain amount of time

This is a passive event used to track what is visible and has been seen, whether it's a page, widget, image, or any other media or object.

Select

Requirements:

  • Use when: something on the media was selected (clicked or touched)
  • Notes: the action is not better explained by related actions (opened, completed, closed, etc.)

The select event is the most basic interaction on automotive media. When something is touched, clicked or selected, you can trigger a select action on that object. This action may trigger other actions as well, depending on the result of the selection.

Change

Requirements:

  • Use when: the object already exists, and is now updated or changed
  • Notes: the object is not better explained by related actions (completed, closed, etc.)

The change event is used when existing items are updated or changed on automotive media. This is most useful on dynamic content on a site, which updates and changes over time.

Open

Requirements:

  • Use when: the action caused something to open or become viewable due to a shopper's interaction, without navigating away from the page
  • Notes: this should be used over the view action when the shopper triggers the viewing of something on the same page or view

The open event should be tracked when some object on the automotive media is opened within the same page or view. Unlike the view event, the viewing action that this time is caused by a shopper's action.

Close

Requirements:

  • Use when: the action caused something to close or not be viewable or available anymore
  • Notes: the object is not better explained by related actions (completed, canceled, etc.)

The close event should be tracked when some object on the automotive media is closed. Closing something means it's not viewable or available anymore, and it could have previously been opened. If cancel or complete is more descriptive for the action on the object, please use those actions instead.

Start

Requirements:

  • Use when: the action started some sort of process
  • Notes: the action could have opened something or made it viewable. The process started can be closed, completed, canceled, and can contain markers

The start event should mark the beginning of a process. This process will use other events to track completion, cancellation, and dropped markers in the process. This action is a more specific form of view or open, and should be used for processes that provide results and not just viewable or openable media.

Cancel

Requirements:

  • Use when: assumed the action is done during a process, preferably following a start action
  • Notes: the action can be something that inherently starts on the page and is canceled via some action by the shopper

The cancel event should mark the cancellation of some process that was started. Once a process is started, there are many outcomes of the process that can happen, and cancellation is one of them.

Complete and Submit

Requirements:

  • Use when: assumed the action is done during a process, preferably following a start action
  • Notes: the action can be something that inherently starts on the page and is completed via some action by the shopper

The complete and submit events should mark the completion of some process that was started. When shoppers complete or submit something on an object, the form of the object can be fully realized.

Marker

Requirements:

  • Use when: to mark some sort of position, either within something physically or conceptually

The marker event should mark any physical or conceptual position for an object. This can be the position on a page (73% scrolled), the position in a process (step 2 of 5), or even a time-mark in a video. These are usually passive checks performed against the state of an object but can follow other actions the shopper performs.

Associate

  • Use when: two or more objects should be associated with each other

The associate event should mark the connection between two or more objects. This can include two user ID's, two forms, multiple form inputs, etc., and does provide ways to match two or more things together so they're relatable.

Utilizing this feature means providing two or more objects and their relatable fields that can connect them together. You can provide these objects in an entities field, each with an object and association field used to tie them together.

Event Objects

Event objects are the noun of the event. They describe what the action is being performed on. The list of supported objects are a hierarchy, as follows:

  • Form
    • Contact
    • Financial
    • Search
  • Calculator
    • Payoff
    • Lease
    • TradeIn
    • Purchase
  • Recommendation
  • Review
  • Schedule
    • TestDrive
    • Service
  • Media
    • Image
    • Video
    • 360
  • Communication
    • Chat
    • Call
    • Text
    • Email
  • Sales
    • VehicleOffer
    • VehicleCoupon
    • ServiceCoupon
    • VehicleHistory
  • Visit
  • Vehicle
  • Page
  • Element
    • Input
  • Shopper/User
  • Other

Any other objects will be treated as custom object types - they are not interpretable or applicable within Orbee's systems, but will appear in reporting dashboards and our API.

Form

A form is something with fields, drop-downs, checkboxes, and other inputs that users can interact with and submit.

Forms have three types so far:

Name Definition
Contact fill out personal info to get in contact with the dealership
Financial fill out personal information for financial checks and calculations
Search search for something on the site

Forms can also have additional fields:

Name Description Examples
formName the name of the form itself 'Searchbar'
valid whether or not the form is valid true, false

Calculator

A calculator is used to calculate the value or result of something based on user input. This is similar to a form, except for the fact that it calculates some result and usually doesn't save or submit any information without a goal or returning a result.

The calculator has five types:

Name Definition
Payoff looking to payoff a vehicle and find out how much is owed
Lease looking to lease a vehicle and find out what the lease payments might be
Loan looking to get a loan and find out what the payments and interest are
TradeIn looking to trade-in a vehicle and find out what the value of the vehicle is
Purchase looking to purchase a car and find out how much it might actually cost

Recommendation

A recommendation is some object that is recommended to the user through some means that isn't a random display of the product.

Review

A review is a review of some product displayed on the site.

Schedule

A schedule object is used to schedule some interaction between the dealership and the customer.

The schedule has two types:

Name Definition
TestDrive schedule a test drive of vehicle(s)
Service schedule a service appointment on a vehicle

Scheduled visits can also have additional fields:

Name Description Examples
appointment the timestamp of the scheduled visit 2018-02-01 05:30:00

Media

A media is some viewable item that is available on the website or automotive media.

Media has three types:

Name Definition
Image a viewable image
Video a viewable video
360 a 360 viewer

Media also can have additional fields:

Name Description Examples
mime the mime type of the media mp4, jpg, png, etc.
width the width of the media 640px
height the height of the media 480px
length the length of the media 20:46

Communication

A communication is something the shopper can use to communicate directly with the dealership.

Communication has four types:

Name Definition
Chat a chat within some chat app on the website
Call a phone call
Text a texting SMS conversation
Email an email conversation

Vehicle

A vehicle is just what it is - what dealerships are selling (new, used, certified).

Additional fields are allowed:

Name Description Examples
vin the VIN of the vehicle ...
stockNumber the stock number of the vehicle fhk2435

Additional fields can also be provided; check out the suggested fields below.

Sales

Sales objects are something the dealership provides as an incentive to purchase.

Sales has four types:

Name Definition
VehicleOffer an offer on a vehicle
VehicleCoupon a coupon to be used on vehicle purchase
ServiceCoupon a coupon to be used on service
VehicleHistory the history of the vehicle

Visit

A visit is the visit of the current shopper.

Page

The page is a special object, that represents the website or automotive media being viewed.

Element

The element is a general use term for an element on a page, or any other automotive media these events are tracking.

Elements have a sub-type, approved for forms:

Name Definition
Input an element that provides shopper input in a form

User

The user is a special object, used to denote a user on the page. This object is usually used when associating user ID's between vendors and services, or when tagging properties related directly to the user (name, email, credit, etc.).

Event Vendor, Product, and Instance ID

The event vendor, product, and instance ID can be used by vendors to track and categorize their different services to dealerships. This also provides the basis for how vendors can integrate through events with Orbee. For more information, contact Orbee!

Event Score

The event score can be used by vendors and dealerships to track the effectiveness of what the events are tracking on their website or automotive media. The numerical values can be manipulated for different values, such as min, max, average, sum, and many other operations.

Suggested Fields (not core to spec)

Below are some suggested fields that need to be adopted by a wider audience before joining the above event spec.

Tracking Type

Tracking Type is a form of explaining how an event came about. For example, we track clicks in many different ways - clicks on certain elements, jquery click tracking, and a mousedown fallback. For this case, Orbee describes this as:

  • mousedown:link,
  • click,
  • mousedown:global,
  • jquery:click,
  • etc.

to identify how we ended up tracking that click. This might be helpful to deduplicate events that may be the same event on the same element.

Element

For many events, it might be useful to provide attributes tied to an element the action is happening to. The element is a place to provide that. Some keys for this sub-object are as follows:

classes

The classes of the element (use an array of strings, or a space-delimited string)

spec.element.classes = element.className;

id

The id of the element

spec.element.id = element.id;

href

The href of the element (usually a band)

spec.element.href = element.href;

innerText

The inner-text of the element

spec.element.innerText = element.innerText;

title

The title of the element

spec.element.title = element.title;

src

The src of the element

spec.element.src = element.src;

alt

The alternate text for the element

spec.element.alt = element.alt;

node

The node type of the element

spec.element.node = element.nodeName;

value

The value of the node (e.g. input)

spec.element.value = element.value;

type

The type of input the node is

spec.element.type = element.type;

Elements

Elements is a greater set of the element object. Elements is an array of event-objects, each with their own event structure that applies to the overall event. Each object in the array should have an element object in it as well. Examples include providing all input objects in a form.

Vehicles

Vehicles is the standard vehicle object for an event. It is an array of vehicles that are relevant or display on a webpage. This is mainly used when sending in the microdata info on a VDP. The syntax and nomenclature follow the https://schema.org/Car definitions, which is ubiquitous to most websites.

A list of suggested fields are below:

  • name
  • title
  • brand
  • manufacturer
  • model
  • vehicleModelDate
  • releaseDate
  • mileageFromOdometer
  • color
  • vehicleInteriorColor
  • vehicleEngine
  • vehicleTransmission
  • vehicleSeatingCapacity
  • itemCondition
  • availability
  • price
  • priceCurrency
  • images
  • vehicleIdentificationNumber
  • serialNumber
  • sku
  • productID
  • description
  • url

Last update: 2023-04-13