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

Adzerk's CloudFormation template for data shipping will create:

  • An S3 bucket for your Adzerk data shipping logs
  • A bucket policy authorizing Adzerk to create objects in the bucket and list the objects the bucket contains. ListBucket permission is required to ensure that all data shipping files are uploaded correctly.
  1. Let your account manager know that you're interested in data shipping. Your account should be on the Business or Enterprise plan.
  2. Choose a name for the CloudFormation stack: STACK_NAME, and a name for the new S3 bucket: BUCKET_NAME.
  3. Use the AWS CLI to create the CloudFormation stack:
$ aws cloudformation create-stack \
--stack-name $STACK_NAME \
--parameters ParameterKey=BucketName,ParameterValue=$BUCKET_NAME \
--template-body https://static.adzerk.net/docs/cloudformation-templates/create-datashipping-s3-bucket.yaml
  1. Let Adzerk support know when the bucket has been successfully created, or if you have run into any issues.

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 ados.js tags)
2 = Email (served by HTML tags)
3 = API (served by REST call)
4 = Static Tracking Link (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.)

GdprConsentRequired

If true, the gdprConsentRequired parameter was provided on the request, indicating that the user was subject to GDPR regulation (even if they didn't use an EU IP address).

GdprConsentString

The IAB consent string provided with the request if the string was used when computing GDPR consent.

GdprIsEU

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

GdprSource

Where GDPR consent data originates:

none - no consent
request - on the ad request
userdb - on the user record
both - both user record and request
str - from an IAB consent string + allowed vendor ID

GdprVendorId

The vendor ID provided in the request (if available).

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

This is sanitized as 0.0.0.0 instead of the IP address

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

This is sanitized as 0.0.0.0 instead of the IP address

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

This is sanitized as 0.0.0.0 instead of the IP address

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