Custom Event Tracking

๐Ÿ“˜

Custom Event Tracking requires using the Decision API.

Overview

With Kevel you can track Custom Events beyond impressions, clicks, and conversions. For instance, you can track Likes, Saves, Comments, etc at the ad-level.

Offering custom event tracking can make your ad platform stand out from others, as well as provide better insight into how users are engaging with your ads.

777777

How It Works

  • You request the Custom Event URL(s) when making a Decision API Request
  • The Response will provide the URL(s)
  • You fire the URL(s) when the event happens
  • Kevel's system records that Custom Event happening for that ad

Custom Event Set-Up

  1. In the Decision API Request, there's an optional eventIDs field. If you would like to receive a URL endpoint for one or multiple IDs, put the IDs into the eventIDs array.

Please see the Event ID Mapping section for a list of accepted IDs.

In this example request, the client is asking for URLs for eventIDs of 12, 13, and 14.

{
  "placements": [
    {
      "divName": "homepage",
      "networkId": 123,
      "siteId": 456,
      "adTypes": [5],
      "eventIds": [12,13,14]
      }
  ]
}
  1. In the resulting Decision API Response, you'll see an events object that contains the id and url for each of the Events requested.

๐Ÿ“˜

The event URL is unique for each Response. For instance, if you do another Request for a different user, the URL will be different, even if the same Ad won the placement.

{
  "adId": 111,
  "creativeId": 222,
  "flightId": 333,
  "campaignId": 444,
  "clickUrl": "https://e-1234.adzerk.net/r?...",
  "impressionUrl": "https://e-1234.adzerk.net/i.gif?...",
  "events": [
        { id: 12,
          url: "https://e-1234.adzerk.net/e.gif?..."
        },
        { id: 13,
          url: "https://e-1234.adzerk.net/e.gif?..."
        },
        { id: 14,
          url: "https://e-1234.adzerk.net/e.gif?..."
        }
  ]
  ...
}
  1. Now that you have the URL, you'll want to fire it when the event happens. The implementation of this will depend on what the event is and how you'd like to trigger it.
  • Some events - like watching a video for 15+ seconds - will require you to record that information and then ping Kevel's system when it happens. Just GET the endpoint directly from your server.

  • Other events - like a "Like" button - can be triggered at time of click, and you could enable your system to automatically fire the URL when someone clicks. Or, you can GET the endpoint server-side once you've registered a click event.

  1. Track the # of events tied to the Ad/Flight/Campaign in Reporting!

Custom Events in Reporting

If you run a report for criteria that includes custom events, events will be present in the report. Each event type will have its own column.

If an event is named (see below), the event name will be used as the column name. Otherwise, the event ID will be used.

๐Ÿšง

By default, revenue is not associated with custom events. However, you can pass in revenue on the event URL.

Custom Events in Data Shipping

When using the Decision API, logEvents allows you to receive a custom event pixel in a data shipping log, rather than (or in addition to) in the decision API response.

"logEvents": 
{"impression": [20],
"click": [3]},

This will push a pixel for custom event 20 into the impression log, and custom event 3 into the Click log. See the Decision API Placement Body for more.

Event ID Mapping - Named Events

There are two categories of custom events in Kevel:

  • Named Events
  • Unnamed Events

Named events correspond to various common actions users can take. Each eventId has an assigned name, and these names are used in Reporting.

For instance, if you request a URL for Upvote (eventIDs = 10), then fire it, the "Upvote" column in the Reporting tab will show that an Upvote happened.

Kevel has approximately 60 named events.

Unnamed events are a range of eventIds reserved for Kevel customers to use for any other event they want to track. They do not have names associated with them in Reporting.

๐Ÿ“˜

Kevel's system doesn't "audit" the event that's fired. Meaning - if you request a URL for Upvote (eventIDs = 10), and then ping it when a Downvote happens (eventIDs = 11), our system will record the event as an Upvote.

Conversions

1View Conversion
2Click Conversion
3Server to Server Conversion

Votes

10Upvote
11Downvote
12Downvote: Uninteresting
13Downvote: Misleading
14Downvote: Offensive
15Downvote: Repetitive
16Downvote: Other

Interactions

17Close Ad
20Like
21Share
22Comment
31Hover
32Expand Div
101Comment Reply
102Comment Upvote
103Comment Downvote

Viewability

๐Ÿ“˜

If you are able to track viewability of an ad, you can send us that information as a Custom Event; however, Kevel doesn't "audit" this viewability. For instance, if you pinged the event URL when the ad wasn't actually viewable, we'd still report it in the "Viewable Impression" column.

30Visible
40Viewable Impression

Social Shares

50Share on Facebook
51Share on Twitter
52Share on Pinterest
53Share on reddit
54Share on Email

E-Commerce Actions

58Refund
59Purchase
60Add to Cart
61Remove from Cart
62Add to Cart from Details
63Add to Wishlist
64Add to Registry
65Expand Product
66Save
67Save for Later
68Notify
69Buy Now

Video Metrics

70Start
71First Quartile
72Mid Point
73Third Quartile
74Complete
75Mute
76Unmute
77Pause
78Rewind
79Resume
80Full Screen
81Exit Full Screen
82Expand
83Collapse
84Accept Invitation Linear
85Close Linear
86Skip
87Progress
4000 Seconds Viewed
4011 Seconds Viewed
4022 Seconds Viewed
4033 Seconds Viewed
4044 Seconds Viewed
4055 Seconds Viewed
4066 Seconds Viewed
4077 Seconds Viewed
4088 Seconds Viewed
4099 Seconds Viewed
41010 Seconds Viewed
41515 Seconds Viewed
42020 Seconds Viewed
42525 Seconds Viewed
43030 Seconds Viewed

Legacy Named Events

โ—๏ธ

These eventIds can be still used for custom event tracking, but with the addition of the new unnamed event range, they are deprecated. If you need custom events, we recommend starting at eventId 800.

201Custom1
202Custom2
203Custom3
204Custom4
205Custom5
206Custom6
207Custom7
208Custom8
209Custom9
210Custom10
104-110Custom

EventId Mapping - Unnamed Events

Kevel has reserved a large range of eventIds for customers to assign in any way they need. These eventIds are the range of 800 to 1000. Kevel will never create new named events that overlap with this range.

In reports, these events are named as their eventIds.