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
- 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 |
| 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