## Overview

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

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

custom event tracking

## How It Works

- Request the Custom Event URL(s) when making a [Decision API Request](https://dev.kevel.co/v1.0/reference#request)
- The [Response](https://dev.kevel.co/v1.0/reference#response) provides the URL(s)
- 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](https://dev.kevel.co/docs/custom-event-tracking#section-event-id-mapping-named-events) section for a list of accepted IDs.

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

```json
{
  "placements": [
    {
      "divName": "homepage",
      "networkId": 123,
      "siteId": 456,
      "adTypes": [5],
      "eventIds": [12,13,14]
      }
  ]
}
```

2. In the resulting Decision API Response, you'll see an `events` object that contains the `id` and `url` for each of the Events requested.

Decision API Response

```json
{
  "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?..."
        }
  ]
  ...
}
```

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

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

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

JSON

```json
"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](https://dev.kevel.co/reference/placement-body-parameters) 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 a URL for Upvote (`eventIDs` = 10) is requested, 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.

**Conversions**

|  |  |
| --- | --- |
| 1 | View Conversion |
| 2 | Click Conversion |
| 3 | Server to Server Conversion |

**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 the viewability of an ad can be tracked, send that information as a Custom Event; however, Kevel does not "audit" this viewability. For instance, if the event URL is pinged when the ad was not actually viewable, Kevel will 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 |

**E-Commerce Actions**

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

**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. If custom events are needed, start 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

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

Updated10 months ago

* * *