Creative Services Toolkit

Documentation

Universal Tracking (UT) Documentation

Get help with setup, functionality, and troubleshooting

Setup

To setup Universal Tracking simply copy the following code and paste it at the bottom of your HTML. A few options will need to be modified, so read below for an explanation of each option.

  • The tracking_options object tells UT how to setup and which project to associate the data with.
    • adType - Type of creative we are using.
      Value: Name of Adtype
      Conditions: Required
      Options: Bigbox, HalfPage, Filmstrip, Portrait, Sidekick, Brandscape, Sidescape, Pushdown, PushdownShowcase, MobilePushdown
    • creativeID - ID of project in the tracking tool where data should be stored.
      Value: Integer
      Conditions: Required. The creativeID can be found in http://report2.sni-dat.com after you setup a new creative.
    • debug - Switch to either show or hide console logs for tracking.
      Value: Boolean (true/false)
      Default: True
    • container - Define a limit to which part of the creative shold be tracked, if required
      Value: null or jQuery object
      Default: null, tracks entire ad.
    • disable - If true prevents any data from being sent to the server.
      Value: Boolean (true/false)
      Default: false

Fine Tuning the Tracking

UT with automatically scan your creative for known CS plugins like the video player or the slider, and will also find all jQuery based click events you have created in your javascript file.
UT will log warnings in your browser console if any errors are found, it will also show a table detailing which events it found and how they will be tracked.

1. Reading the Warnings

  • In Chrome, console warnings appears with a yellow background. In Firefox (not Firebug) they appear with a little warning icon to the left. **Firebug in Firefox does not show console warnings
  • The warnings will tell you that UT has found an issue with something that will need to be fixed before tracking can work correctly.
  • In the screenshot above there are 5 warnings.
    - The top 2 show that a carousel slide does not have a data-name attribute and so tracking will be based on the slide number instead (ex: slide1)
    - The last 3 show that an element does not have an ID or a data-name. It may have a class but UT won't use classes for tracking since they can be reused by multiple elements. To fix this simply add a data-name attribute to the element.

2. Reading the Event Table

  • The screenshot above is a console table in Chrome. Firefox will also show a table but it will look slightly different. **Firebug does not show console tables.
  • There are two tables shown in the console.
    1. Clicks table
    2. Modules table
  • Clicks Table
    Shows all the click events that UT found. It will automatically exclude click events on modules, like the Slider and the Video Player, otherwise they would be duplicates.
    Here's how the table works:
    • Element:
      The element that the click event is attached to. This represents an element in your HTML code. It shows the element type (div,span etc) and the selector (ID, class etc)
    • Type:
      Shows the type of event. Options are externalClick for opening new windows, click for interaction within the creative, and mouseover or mouseout.
    • Redirect:
      For externalClick this is the URL that will open in a new window. It should be a direct URL or a Third Party tag.
    • Description:
      This is the event that will be recorded in the database, so it's important this column shows something that makes sense.
      If NOT FOUND.. is shown that means you'll need to add either an ID or a data-name attribute to the element.
      If UT found something to use but it doesn't make sense you'll need to add a data-name attribute to the element
  • Modules Table
    Shows all the CS modules that UT found and data about them.
    Here's how the table works:
    • Type:
      The type of module
    • Name:
      The name that will be recorded in the database for all events associated with the module. For instance a video player when "play audio" is clicked would record video1_playAudio.
      If the module is a carousel, add a data-name attribute to the carousel ul in your HTML
      If the module is a video player, add a data-name attribute to the video container, which by default is videoWrapper
    • The rest of the columns are data that UT uses and you can ignore.

3. Reading the Events as they occur

  • The screenshot above show console logs in Chrome. Firefox will also show console logs but the coloring may look different.
  • As UT fires tags to record data in the database it will also log them in the browser console. This makes it easy for you to see which events are firing and the exact tag being used.
  • Here's how each log works:
    • Type:
      The first part of the log shows the type of tag that was fired. In the screenshot above the type is the first word, "view tag fired:" indicates that a View tag was fired
      Types of tags are: View, engage, and Jump. See the Tag Types section below if you're more interested in what each type means.
    • Tag:
      Show the specific URL that was sent to the database. In it you can see the description that was fired by looking at the name= property.
      Ex: name=video1_start_autoplay shows that video1_start_autoplay will be recorded in the database

Firing Tags Manually

UT will automatically assign tracking to most events in your creative. But there will be times when you will need to fire a tag manually when a specific event occurs.

Here's how:

  • UT.fireTag tells UT to go ahead a fire a tag with the parameters provided. It's the same way UT fires tags when it does it automatically
  • The code requires 2 parameters:
    First is a description of the tag that is being fired. Descriptions can be any string, but check out the Naming Conventions section below for more details about how we name descriptions.
    Second is the tag type. For the tag type the above code uses "engage", which will most likely be what is needed. For a full list of tag types and what they do see the Tag Types section below.

Third Party Tags

In many cases UT can automatically fire third party tags for you.
For clicktags you will implement them in your HTML or Javascript the same way we always have, nothing will change.
For impression tags follow the implementation methods below.

For Carousel Impressions:
For each slide add the data-thirdparty attribute.

For Video Impressions:
For each video fill out the tracking object only with 3rd party tags. Otherwise leave empty quotes.

Naming Conventions

Tags are fired using a "description". The description is what will show up in the tracking reports, so it's important that they are standardized and clear.
For automatically fired tags UT follows our standard naming convention. For tags that you fire manually you will need to follow the convention below (when possible):

  • For Carousels:
    For each slide CarouselName_SlideNumber_SlideDescription. For example "carousel1_slide2_porkRecipe"
    For carousel interaction CarouselName_engagement. For example "carousel1_engagement"
  • For Buttons:
    button_description. For example "button_exploreNow" or "button_cta"
  • For Hotspots:
    hotspot_roomName(optional)_description. For example "hotspot_kitchen_blender" or "hotspot_blender"
  • Anything Else:
    Simply name the tag something that makes sense and is descriptive.

NOTE: Do not use spaces. Instead, use underscores, dashes, or camel case to separate words.

Tag Types

UT utilizes 3 tag types to differentiate events.

  • Jump:
    Jump tags are reserved for external clicks, like launching a website or going to a page on the brand website.
  • View:
    View tags record useful data about the ad but are not considered engagements. Things like video impressions, carousel slide impressions, and time spent interacting with the creative use "view" tags.
  • Engage:
    Engage tags record user engagement. These tags will be used when calculating engagement rates. Thing like carousel interaction (changing from one slide to another), video interaction (playing with audio etc), and clicking on buttons that cause changes in the ad itself use the "engage" tag

NOTE: Tag types are important. If you are manually firing a tag you'll most likely use the Engage type but if you're unsure contact Mike or Ian first.