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!

Data Shipping

Data Shipping requires the Business or Enterprise plan.

Overview

The data shipping feature delivers click, conversion, and impression data direct to an Amazon AWS S3 bucket. This enables you to ingest large amounts of data without making requests to the Adzerk reporting API. You can also perform advanced analytics on the raw data beyond what's available in the Adzerk platform.

Integration Steps

  1. Let your account manager know that you're interested in data shipping.
  2. Share the S3 bucket name and authorizing credentials (AWS access key, AWS secret key) with your account manager. Make sure that you are giving Adzerk write access.

Access key ID example: AKIAIOSFODNN7EXAMPLE Secret access key example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  1. We will enable data shipping on our end.

Data shipping will return a JSON object of an event (impression, click, or conversion). An example impression object is below.

For impressions, each ad serving engine will deliver a file approximately once per minute. The files are gzipped.

For clicks and events data, each file will be delivered once per day at the end of the day.

JSON Object

{
   "Id":"e1cf155248e541ba853b2ed482efd4ed",
   "CreatedOn":"/Date(1430156219349)/",
   "AdTypeId":5,
   "AuctionBids":1,
   "BrandId":15408,
   "CampaignId":22318,
   "Categories":[

   ],
   "ChannelId":7731,
   "CreativeId":57609,
   "CreativePassId":82224,
   "Datacenter":true,
   "DeliveryMode":2,
   "Device":{  
      "brandName":"Google",
      "modelName":"Chrome",
      "osRawVersion":"0",
      "osMajorVersion":0,
      "osMinorVersion":0,
      "browser":"Chrome Desktop",
      "browserRawVersion":"63.0",
      "browserMajorVersion":63,
      "browserMinorVersion":0,
      "formFactor":"desktop"
   },
   "Ecpm":0,
   "FirstChannelId":7731,
   "GdprComputed":false,
   "GdprIsEU":false,
   "GdprSource":"none",
   "ImpressionCount":1,
   "IsNoTrack":false,
   "IsTrackingCookieEvents":false,
   "IsPublisherPayoutExempt":false,
   "IsValidUA":true,
   "Keywords":"",
   "Location": {
      "CountryCode": "US",
      "CountryName": "United States",
      "Region": "VA",
      "City": "Ashburn",
      "PostalCode": "20147",
      "MetroCode": 511,
      "DmaCode": 511,
      "AreaCode": 703
    },
   "MatchingKeywords":[

   ],
   "NetworkId":4161,
   "PassId":41596,
   "PhantomCreativePassId":0,
   "PlacementName":"3423",
   "PhantomPassId":0,
   "PriorityId":19301,
   "Price":"0",
   "RateType":1,
   "Revenue":0,
   "RemoteIP":"0.0.0.0",
   "RtbBids": 4,
   "SiteId":22032,
   "User":{
      "Key":"ue1-9040e0cc7c6a45afbf2ca1f40a67b75c"
   },
   "UserAgent":"",
   "UserKey":"ue1-9040e0cc7c6a45afbf2ca1f40a67b75c",
   "ZoneId":0
}

Impression Events

Name
Description

Id

The unique Impression ID

CreatedOn

A time/date stamp (milliseconds since UNIX epoch) that indicates when the impression happened

AdTypeId

The numeric ID of an ad size. Sourced from the event shim

AuctionBids

The number of non-RTB ads competing for the impression in an Auction priority. If the ad served was selected outside of an Auction priority, for example from an AdChain or Lottery priority, then this AuctionsBids value will be zero. Note that this field is absent unless there is at least one auction bid in the event shim

BrandId

The numeric ID of the impression's advertiser. Sourced from the event shim

CampaignId

The numeric ID of the impression's campaign. Sourced from the event shim

Categories

An array of behavior targeting categories, set by the impression's flight. Sourced from the event shim, absent if absent in the shim

ChannelId

The numeric ID of the impression's channel. Sourced from the event shim

CreativeId

The numeric ID of the impression's creative. Sourced from the event shim

CreativePassId

The numeric ID of the impression's ad (creative mapped to flight). Sourced from the event shim

Datacenter

If true, the event originates from a TAG known datacenter.

DeliveryMode

1 = Web (served by JS tags)
2 = Static (served by HTML tags)
3 = API (served by REST call)
4 = Tracking pixel (served by GIF)

Device

WURFL derived data about the device that created the impression/event

Ecpm

Calculated ECPM of the impression/click/event

FirstChannelId

Deprecated

GdprComputed

If true, the request has GDPR consent (from the request itself, from a UserDB record, etc.)

GdprIsEU

If true, the request originates from the EU, the UK or Switzerland.

GdprSource

Where GDPR consent originates:

none - no consent
request - on the ad request
userdb - on the user record
both - on both

ImpressionCount

The number of impressions in the object. Default is 1

IsNoTrack

If true, the impression was served to a Do Not Track enabled user (boolean)

IsTrackingCookieEvents

If true, the impression is tracking conversions. Sourced from the event shim (boolean)

IsPublisherPayoutExempt

Deprecated (boolean)

IsValidUA

If true, the impression passed the bots and spiders filter (boolean)

Keywords

Keyword(s) sent on the request, converted into a comma separated string. Sourced from the event shim

Location

An array of location data from the request. Sourced from the ad request, NOT the event shim

Matching Keywords

Keyword(s) present in the ad. Sourced from the event shim

NetworkId

The numeric ID of the impression's network. Sourced from the event shim

PassId

The numeric ID of the impression's flight. Sourced from the event shim

PhantomCreativePassId

Internal - used during phantom mode for impression goal ads. Sourced from the event shim

PlacementName

The name of the Placement object or <div> that served the ad. Sourced from the event shim

PhantomPassId

Internal - used during phantom mode for impression goal ads. Sourced from the event shim

PriorityId

The numeric ID of the impression's priority. Sourced from the event shim

Price

The price per unit (CPA, CPM, CPC etc.) associated with the impression. Returned as a string. Sourced from the event shim

RateType

The rate used by the flight. Sourced from the event shim:

1 - Flat 2 = CPM 3 = CPC 4 = CPA View 5 = CPA Click 6 = CPA Both

ReferrerUrl

The URL that led to the page that hosted the ad request. Sourced from the event shim

Revenue

Revenue generated via the impression. Calculated by taking the revenue field in the event shim and multiplying by 1,000,000

RemoteIP

The IP of the user who viewed the ad. If Do Not Track is enabled, this is sanitized as 0.0.0.0 instead of the IP address. Sourced from the ad request

RtbBids

The number of RTB bids competing for the impression. Remember, RTB ads can be used in any priority type. Also, please note that some RTB partners provide more than one bid per request, but most only provide one. Sourced from the event shim

SiteId

The numeric ID of the impression's site. Sourced from the event shim

Url

The URL of the page the ad served on. This may be missing if there was no referrer header on the request. Sourced from the ad request

User

An array of user data (in UserDB) associated with the impression. Contains two fields: the Key, and whether or not this is a new user. Sourced from either the UserDB record or the user's azk cookie

UserAgent

Deprecated for privacy purposes. User agent data can now be found in the Device object

UserKey

The user Key (used by UserDB) associated with the impression. Sourced from the ad request

ZoneId

The numeric ID of the impression's zone (if applicable). Sourced from the event shim

Click Events

The JSON objects for other events use the same format as the impression object. Additional parameters for clicks (or parameters with differences):

Name
Description

ClickCount

The number of clicks in the object. Always set to 1

CreatedOn

(Deprecated) When the impression associated with the click occurred, as a UNIX timestamp

EventCreatedOn

When the click event occurred, as a UNIX timestamp

ImpressionCreatedOn

When the impression associated with the click occurred, as a UNIX timestamp

IsValidUA

If true, the impression passed the bots and spiders filter. Sourced from the click request (boolean)

Location

An array of location data from the request. Sourced from the click request, NOT the ad request

RemoteIP

The IP of the user who viewed the ad. If Do Not Track is enabled, this is sanitized as 0.0.0.0 instead of the IP address. Sourced from the click request

Url

The URL of the page the ad served on. This may be missing if there was no referrer header on the request. Sourced from the click request

User

An array of user data (in UserDB) associated with the impression. Contains two fields: the Key, and whether or not this is a new user. Sourced from the click request

UserAgent

The string of the user agent that created the impression. Sourced from the click request

UserKey

The user Key (used by UserDB) associated with the impression. Sourced from the click request

Conversion Events

The JSON objects for other events use the same format as the impression object. Additional parameters for conversions (or parameters with differences):

Name
Description

CreatedOn

(Deprecated) When the impression associated with the conversion occurred, as a UNIX timestamp

EventCreatedOn

When the conversion occurred, as a UNIX timestamp

ImpressionCreatedOn

When the impression associated with the conversion occurred, as a UNIX timestamp

IsValidUA

If true, the impression passed the bots and spiders filter. Sourced from the conversion request (boolean)

Location

An array of location data from the request. Sourced from the conversion request, NOT the ad request

RemoteIP

The IP of the user who viewed the ad. If Do Not Track is enabled, this is sanitized as 0.0.0.0 instead of the IP address. Sourced from the conversion request

Url

The URL of the page the ad served on. This may be missing if there was no referrer header on the request. Sourced from the conversion request

User

An array of user data (in UserDB) associated with the impression. Contains two fields: the Key, and whether or not this is a new user. Sourced from the conversion request

UserAgent

The string of the user agent that created the impression. Sourced from the conversion request

UserKey

The user Key (used by UserDB) associated with the impression. Sourced from the conversion request

Custom Events

The JSON objects for other events use the same format as the impression object. They have the same additional parameters as conversions, with one notable difference:

Custom event logs have an additional EventId field that is the ID of the custom event type. (For example, an EventId of 10 is an Upvote event.)

Data Shipping