Event Specifications

[#1]

Event specifications are a way to organize and validate the quality of incoming data. Specifications define the attributes required for types of events and provide code examples for your installation. Once created, specifications allow the data quality of your events to be validated in real-time using Live Events.

This article covers the following topics:

Table of Contents Placeholder

How It Works

Event specifications represent your data layer in the Customer Data Hub . Events entering the Customer Data Hub are identified by the tealium_event attribute. The value of this attribute represents the name of the event and the specification associated with it. The specification also indicates which event attributes are required to be populated in the event.

Example Specification

Let's look at an example of an event specification for the event named video_complete which occurs upon the completion of watching a video.

• Event Data Object
  

  {
      "tealium_event"  : "video_complete", // name of event and specification
      "video_id"       : "xWlEk2i9r5Q",
      "video_length"   : 300,
      "video_name"     : "How to track videos in Tealium",
      "video_platform" : "YouTube",
  }

  The  tealium_event attribute identifies the type of event, in this case video_complete. The additional attributes provide contextual information about the event and the corresponding event specification defines the required attributes and their expected data types, as shown in the following example.

• Event Specification
  

• Specification Code Sample
  Tracking code for the cart_add event for an iQ Tag Management data source named "My iOS App"
  
• Event specifications provide two primary benefits for data management:
  • To standardize the implementation of events across all platforms.
  • To evaluate the data quality of incoming events.

Live Events and Feeds

Each event specification automatically creates a matching event feed. This feed can be configured for data storage via DataAccess, or linked to connector actions.

Feeds linked to an event specification cannot be deleted and their names cannot be changed.

Example:

Once an event specification is created and the tracking code is implemented, use Live Events to view incoming events in real-time to evaluate their data quality. As events arrive in the Customer Data Hub, when the tealium_event attribute matches an event specification, the incoming attributes are compared against the requirements of the specification and marked as valid or invalid.

• Example: Valid cart_empty event
  
• Example: Invalid cart_empty event due to lack of matching event specification
  

Using Event Specifications

The following sections describe the steps required to add custom event specifications or add events from the event specification marketplace or live events.

Event specifications can be added as custom events or added from the marketplace of built-in events. Custom events can use any event name and any attribute requirements.

Creating a Custom Event Specification

Custom specifications use a tealium_event value that you determine.

Once you create a custom event specification, the name of the event cannot be changed.

Use the following steps to add a custom event specification:

1. In the sidebar, select EventStream > Event Specs.
2. Click + Add Event Specification and select Add Custom Specification from the drop-down list.
3. Enter the name of the event (value of  tealium_event).
4. Optional. In the Notes field, enter notes to describe the event, such as how the event is triggered and what the event is to accomplish.
5. Click Add Label to apply labels.
   This step is optional.
6. From the drop-down list, select an event attribute and mark the attribute as required or not required.
   • Click + Define New Attribute to create a new attribute for this specification.
   • Remove an attribute clicking the (-) button.
7. You can add additional attributes by clicking + Add Attribute and then repeating Step 6.
8. Click Finish.
   The following example shows a custom event specification named gallery_view.
   
9. Click Save and Publish to save and publish to your account.

Adding a Marketplace Specification

The event specification marketplace contains commonly used pre-built events. Once an event is added, the only change that can be made to a marketplace specification is the addition of attributes to the definition.

When adding an event specification from the marketplace, the original event name and attribute list cannot be changed.

Use the following steps to add a marketplace specification:

1. In the sidebar, select EventStream > Event Specs.
   
2. Click Add Event Specification > Add From Marketplace.
   
3. Click an event name to preview the specification.
4. Click Select All or select one or more specifications by ticking the box next to the event name.
   
5. Click Finish.
6. Click Save and Publish to save and publish to your account.

Creating Event Specification from Live Events

Event specifications can be added directly from the event details view of Live Events. Live events detect events that match a marketplace specification and provide a preview of the requirements to make it easy to add the specification without leaving the screen.

Events that are unknown can be defined as custom specifications directly from the event details view. The event attributes from the event will be pre-filled in the Add Event Specification modal. 

Learn more about using Live Events.

Tealium Events Extension

For users of iQ Tag Management, use the Tealium Events extension to populate the tealium_event variable to match your event specifications.

Getting Event Specification Code

Creating event specifications is the first step in defining and standardizing your data layer. The second step is implementing the event tracking code on your platform of choice. While each platform has different code syntax, the event and attribute names implemented should be consistent across each of them.

Event specifications combine the event definitions with each of your data sources to provide a full installation guide, complete with the base code and examples for each specification. The resulting installation guide can be downloaded as a PDF and shared with your development team.

Use the following steps to get the code for your event specifications:

1. In the sidebar, select EventStream > Event Specs.
2. Click Get Code.
3. From the drop-down menu, select a data source.
   The base code for the selected data source displays.
4. Click Event Tracking Code to preview the sample code for each event specification.
5. Click Download as PDF to generate a full installation guide for the selected data source.
   
6. Click Close.