The Adzerk Developer Hub

Welcome to the Adzerk developer hub. You'll find comprehensive guides and documentation to help you start working with Adzerk as quickly as possible, as well as support if you get stuck. Let's jump right in!

Custom Event Tracking

Custom Event Tracking requires using the Decision API.

Overview

With Adzerk 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.

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
  • Adzerk'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": "http://engine.adzerk.net/r?...",
  "impressionUrl": "http://engine.adzerk.net/i.gif?...",
  "events": [
        { id: 12,
          url: "http://engine.adzerk.net/e.gif?..."
        },
        { id: 13,
          url: "http://engine.adzerk.net/e.gif?..."
        },
        { id: 14,
          url: "http://engine.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 Adzerk'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.

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

Event ID Mapping - Named Events

There are two categories of custom events in Adzerk:

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

Adzerk has approximately 60 named events.

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

Adzerk'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.

Votes

10

Upvote

11

Downvote

12

Downvote: Uninteresting

13

Downvote: Misleading

14

Downvote: Offensive

15

Downvote: Repetitive

16

Downvote: Other

Interactions

17

Close Ad

20

Like

21

Share

22

Comment

31

Hover

32

Expand Div

101

Comment Reply

102

Comment Upvote

103

Comment Downvote

Viewability

If you are able to track viewability of an ad, you can send us that information as a Custom Event; however, Adzerk 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.

30

Visible

40

Viewable Impression

Social Shares

50

Share on Facebook

51

Share on Twitter

52

Share on Pinterest

53

Share on reddit

54

Share on Email

Video Metrics

70

Start

71

First Quartile

72

Mid Point

73

Third Quartile

74

Complete

75

Mute

76

Unmute

77

Pause

78

Rewind

79

Resume

80

Full Screen

81

Exit Full Screen

82

Expand

83

Collapse

84

Accept Invitation Linear

85

Close Linear

86

Skip

87

Progress

400

0 Seconds Viewed

401

1 Seconds Viewed

402

2 Seconds Viewed

403

3 Seconds Viewed

404

4 Seconds Viewed

405

5 Seconds Viewed

406

6 Seconds Viewed

407

7 Seconds Viewed

408

8 Seconds Viewed

409

9 Seconds Viewed

410

10 Seconds Viewed

415

15 Seconds Viewed

420

20 Seconds Viewed

425

25 Seconds Viewed

430

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

201

Custom1

202

Custom2

203

Custom3

204

Custom4

205

Custom5

206

Custom6

207

Custom7

208

Custom8

209

Custom9

210

Custom10

104-110

Custom

EventId Mapping - Unnamed Events

Adzerk 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. Adzerk will never create new named events that overlap with this range.

In reports, these events are named as their eventIds.

Custom Event Tracking