Collector API Reference

Introduction

The Collector receives data sent from web plugins, native sdks or custom integrations and forwards it to our backend processing systems.

This is the shared transport layer used by:

Ad server pixels — deployed as 3rd party trackers in FreeWheel, GAM, or SpringServe ad responses
Video player plugins — pre-built for Brightcove, JW Player, VideoJS, Bitmovin, and Akamai AMP
Custom integrations — server-side proxies, native SDKs, or any bespoke implementation pushing data to the endpoint

For pre-built integrations, see the relevant vendor page. This reference is for teams building custom implementations or needing to understand the underlying protocol.

Authentication

Requests to the Collector endpoint must all be sent with an authorization header:

X-Api-Key: <apiKey>

You can find your api key in your Watching That account. Failing to set this header or setting it to an invalid value will result in a 401 Unauthorized response.

Endpoints

POST https://collector.watchingthat.com/v5/in
POST https://c.p2r14.com/v5/in

NOTE: We periodically change the latter endpoint domain to prevent ad blocker interference. For server environments use the former — it runs from a stable domain.

Data must be sent as JSON with Content-Type: application/json:

[
  { "<field1>": "<value>", "<field2>": "<value>" },
  { "<field1>": "<value>", "<field2>": "<value>" }
]

Curl Example

curl -X POST \
  'https://collector.watchingthat.com/v5/in' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: 12345' \
  -d '[ { "type": "init", "rid": "123-abc", "cst": 0 }, { "type": "play", "rid": "123-abc", "cst": 1000 } ]'

Concepts

Content Sessions

A content session groups all events from a single video playback, identified by the rid field. All events in the same session share the same rid. Create a unique rid at the beginning of each session.

[
  { "rid": "abc123", "type": "init" },
  { "rid": "abc123", "type": "play" },
  { "rid": "foobar-qqq", "type": "imp" }
]

NOTE: If sending from both server-side and client-side for the same session, use the same rid in both contexts.

Content Session Time

The cst field records milliseconds since session start (not wall clock time):

const startTime = Date.now();
const eventPayload = { cst: Date.now() - startTime };

Ad Sessions

The adGid field groups all events for a single ad (request, load, start, impression, quartiles, complete, errors). Each ad in a session needs a unique adGid.

Type

The type field identifies the event. See Event Types below.

Event Fields

Field	Type	Required	Possible Values	Description

Field	Type	Required	Possible Values	Description
`aBl`	int		-1, 0, 1	Ad Blocker detected. -1 = undetermined.
`adAN`	string			Ad: Advertiser Name
`adBreak`	int	yes, for ad events	-1, 0, 1, ...	Break index: 0=PREROLL, 1/2/3=MIDROLL, -1=POSTROLL
`adBreakPos`	int	yes, for ad events		Position of ad in break, starting from 0
`adCId`	string			Ad: Creative Id
`adDID`	string			Ad: First deal ID in wrapper chain
`adGid`	string	yes, for ad events		Unique identifier linking all events of an ad
`adId`	string			Ad: Ad ID
`adMgV`	string			Ad Manager SDK Version
`adMU`	string			Ad: Media URL
`adSys`	string			Ad: Ad System
`adType`	string		PREROLL, MIDROLL, POSTROLL	Ad break type
`adURL`	string			Ad: Tag URL after macro replacements
`adWCId`	string[]			Ad: Wrapper creative IDs
`adWId`	string[]			Ad: Wrapper IDs
`adWSys`	string[]			Ad: Wrapper ad system names
`autoplay`	boolean			Is player autoplaying?
`browser`	string			Browser name. Skip if sending from browser.
`country`	string		UK, US, DE, ...	2 letter country code. Skip if sending from browser.
`cst`	int	yes		Milliseconds since session start (init = 0)
`custom`	object			Custom data object for analysis
`debug`	string			Extra data for finding clusters in the app
`device`	string			Device name. Skip if sending from browser.
`deviceType`	string		desktop, phone, tablet, tv	Device type
`err`	string	yes if error		Outer error code
`err2`	string			Inner error code for more context
`fif`	int		0, 1	Friendly Iframe
`h`	int			Player height
`idx`	int			Video index in playlist (starts at 1)
`ip`	string			IP address — used to resolve country, then removed
`isLive`	int		0, 1	Live (1) or VOD (0)
`mediaId`	string			Unique video code/name
`originalAdURL`	string			Ad Tag URL before macro replacements
`os`	string			Operating system name
`pageTags`	string			Comma delimited video tags
`per`	int			Ad area visibility percentage
`playerId`	string			Unique player code/name
`plGid`	string			Playlist ID linking all sessions in a playlist
`plV`	string			Video player version
`pu`	string			Page URL
`pVisible`	int		0, 1	Page visible indicator
`rid`	string	yes		Unique video session ID
`src`	string			Short code for app or plugin
`st`	string			Event subtype
`streamId`	string			Video stream ID from IMA DAI SDK
`type`	string	yes	init, play, ...	Event type (see below)
`v`	string			App/plugin version
`w`	int			Player width
`wh`	int			Window/Screen height
`ww`	int			Window/Screen width

Event Types

Value	Description

Value	Description
`init`	Start of session. Send static values (pu, src, v, idx) here.
`play`	Video Play
`serve`	Ad requested
`adBreak`	Ad break started
`adClick`	Ad Click
`al`	Ad Loaded
`sa`	Ad Started
`imp`	Impression
`efq`	Ad First Quartile
`esq`	Ad Second Quartile (midpoint)
`etq`	Ad Third Quartile
`ecp`	Ad Complete
`skip`	Skip ad
`vready`	Video Ready
`vview`	Video View
`error`	Error
`c0`	Content started playing
`c25`	Content First Quartile
`c50`	Content Second Quartile
`c75`	Content Third Quartile
`c95`	Content 95% playthrough
`mute`	User muted audio
`unmute`	User unmuted audio

Custom event types can also be sent — see the Plugin Configuration Reference for details.