Event Specifications

Event Specifications

by Community Manager ‎09-12-2017 02:16 PM - edited ‎06-06-2018 01:23 PM (4,004 Views)

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 Universal Data Hub (UDH). Events entering the UDH 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
    event-spec-video-complete-definitions.png
  • Specification Code Sample
    Tracking code for the "video_complete" event for an iQ Tag Management data source named "Sandbox"
    event-spec-view-code.png

Event specifications provide two primary benefits for data management: (1) to standardize the implementation of events across all platforms, and (2) 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.

event-spec-event-feed.png

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 UDH, 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 "video_complete" event
    event-spec-live-events-valid.png
  • Example
    Invalid "video_complete" event due to the"video_length" required attribute not being populated
    event-spec-live-events-invalid.png

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. Navigate to EventStream > Event Specs.
  2. Click Add Event Specification > Add Custom Specification.
  3. Enter the name of the event (value of tealium_event).
  4. In the Notes field, enter notes to describe the event, such as how the event is triggered and what the event is to accomplish.
    This step is optional.
  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 additonal attributes by clicking + Add Attribute and then repeating Step 6.
  8. Click Finish.
    The following example shows a custom event specification named "gallery_view".

    add-custom-event-specification.png

  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. Navigate to EventStream > Event Specs.
  2. Click Add Event Specification > Add From Marketplace.
  3. Click an event name to preview the specification.
  4. Select one or more specifications by ticking the box next to the event name.
  5. Click Finish.
    add-specification-from-marketplace.png
  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. Navigate to 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.
    event-specifications-get-code.png