InnovidXP Collector API User Guide

Description: This guide lists and describes the API calls used to obtain page view, event, and visit data for the measurement and optimization of TV campaigns.

This document is intended for Innovid partners who use or want to use the Collector API.


Overview

Innovid uses a modified version of the popular piwik tracker as our data collector.

The full documentation for piwik’s tracking URLs can be found at http://developer.piwik.org/api-reference/tracking-api

Innovid uses a particular syntax for custom variables (_cvar and cvar) as described in this document.

Note: Currently, some domains are still tvsquared.com and are referenced as such.

Collector API

The Innovid Collector API provides flexible access to automate the acquisition of page views, events, and visits from InnovidXP at a desired granularity. 

This section lists the InnovidXP endpoints and associated information.

Setup

The Innovid Collector API is a standard RESTful HTTP API based on GET, POST requests with JSON formatted responses.

The Collector API exclusively uses the HTTPS protocol for encryption and data security - plain HTTP requests are blocked and will not be successful. 

All Attribution API endpoints share the same base URL, accessed at the partner level:

https://CLIENTHOST/tv2track.php?idsite=<IDSITE>&rec=1&rand=<RAND>&_id=<VISITORID>
&ua=<UA>&lang=<LANG>&servertrack=t&_cvar=...

 

Parameters

The Innovid Collector API follows several conventions for parameters passed and returned in API calls. All date and time parameters are formatted in the ISO standard as follows, unless otherwise stated:

  • Date: YYYY-MM-DD
  • Datetime: YYYY-MM-DDThh:mm:ss

Site ID and visitor ID are used in Collector API endpoints, identified by <IDSITE> and <VISITORID> respectively. 

URL Parameters

Key Example Type Description
clienthost Collector-1233.tvsquared.com String Customer-specific collector hostname.
A static value supplied by Innovid.
idsite TV1234-1 String Customer-specific collector site ID. A static value supplied by Innovid.
rand 587589345 String A random number on each request, to defeat intervening network caching.
visitorid 0123456789ABCDE String Unique ID for the visitor.
servertrack t String Set this when calling from a backend server with its own IP address (rather than directly from a customer’s web browser).
_cvar See _cvar parameters section --- A URL-encoded JSON string of session-level parameters.
cvar See cvar section --- A URL-encoded JSON string of per-action parameters.
ua Mozilla String User agent, if applicable (optional).
lang en String Browser language, if applicable (optional).

 

_cvar:

This contains the fine-grained session-level tracking information. Due to the way the piwik API works, it is an URL encoded JSON string containing another JSON string.

Raw example:

_cvar%3D%7B%225%22%3A%20%5B%22session%22%2C%20%22%7B%5C%22source%5C%22%3A%20%
5C%22partnername%5C%22%2C%20%5C%22medium%5C%22%3A%20%5C%22app%5C%22%2C%20%5C%
22user%5C%22%3A%20%5C%22%3CUSERREF%3E%5C%22%2C%20%5C%22ip%5C%22%3A%20%5C%22%3
CDEVICEIPADDRESS%3E%5C%22%2C%20%5C%22deviceid%5C%22%3A%20%5C%22%3CDEVICEID%3E
%5C%22%2C%20%5C%22appid%5C%22%3A%20%5C%22%3CAPPID%3E%5C%22%7D%22%5D%7D

 

URL decoding the first layer (i.e., a JSON object with an entry for '5' with a two-item list) results in the following:

{"5": ["session", "{\"source\": \"<PARTNERNAME>\", \"medium\": \"<MEDIUM>\", 
\"user\": \"<USERREF>\", \"ip\": \"<DEVICEIPADDRESS>\", \"deviceid\":
\"<DEVICEID>\", \"appid\": \"<APPID>\"}"]}

 

Decoding the inner JSON (a plain JSON object) results in the following:

{"source": "<SOURCE>", 
"medium": "<MEDIUM>", 
"user": "<USER>", 
"ip": "<IP>", 
"appid": "<APPID>", 
"appname": "<APPNAME>", 
"deviceidtype": "AAID|IDFA",
"deviceid": "<DEVICEID>",
"os": "<OS>",
"country": "<COUNTRY>",
"lang": "<LANG>",
"ua": "<UA>",
}

 

_cvar parameters

Key Example Type Description
source mytracker String Identifies the name of the partner who is supplying the data.
A static value supplied by Innovid.
medium app String Set this to “app” for mobile app. If including anything else, contact Innovid.
ip 8.8.8.8 String The IP address of the mobile device.
user U123 String

Private, unique, user identifier, for example, an internal ID from a billing system. 

Supplied by the customer.

appid com.tvsquared.my-app String ID of the app (optional).
appname My Application String Name of the app (optional).
deviceidtype AAID String The device ID type; either AAID or IDFA (optional).
deviceid e3f5536a141811db40efd6400f1d0a4e String The device ID (optional).
os Android String Operating system (optional).
country US String Country (optional).
lang en String User language (optional).
ua Mozilla String User agent (optional).

 

cvar:

This contains the fine-grained per-action tracking information. Due to the way the piwik API works, it is an URL encoded JSON string containing another JSON string.

Raw example:

cvar=%7B%225%22%3A+%5B%22%3CACTIONNAME%3E%22%2C+%22%7B%5C%22source%5C%22%3A+%5C%22adjust
%5C%22%2C+%5C%22medium%5C%22%3A+%5C%22app%5C%22%2C+%5C%22promo%5C%22%3A+%5C%22%3CPROMOCODE
%3E%5C%22%2C+%5C%22ref%5C%22%3A+%5C%22%3CREFERER%3E%5C%22%2C+%5C%22prod%5C%22%3A+%5C%22%3
CPRODUCT%3E%5C%22%2C+%5C%22rev%5C%22%3A+1234%2C+%5C%22id%5C%22%3A+%5C%22%3CACTIONID%3E%5C
%22%2C+%5C%22dev%5C%22%3A+%5C%22%3CDEVICETYPE%3E%5C%22%7D%22%5D%7D

 

URL decoding the first layer (i.e., a JSON object with an entry for '5' with a two-item list) results in the following:

{"5": ["<ACTIONNAME>", "{\"source\": \"adjust\", \"medium\": \"app\", \"promo\": 
\"<PROMOCODE>\", \"ref\": \"<REFERER>\", \"prod\": \"<PRODUCT>\", \"rev\": 1234,
\"id\": \"<ACTIONID>\", \"dev\": \"<DEVICETYPE>\"}"]}

 

Decoding the inner JSON (a plain JSON object) results in the following:

{"promo": "<PROMOCODE>",
"ref": "<REFERER>", 
"prod": "<PRODUCT>", 
"rev": <REVENUE>, 
"currency": "<CURRENCY>",
"id": "<ACTIONID>", 
"adchannel": "<ADCHANNEL>", 
"campaign": "<CAMPAIGN>", 
}

 

cvar parameters:

Key Example Type Description
<ACTIONNAME> purchase String

Name of the action being performed.

Note: this is supplied outside the JSON.

promo ABCD String The promo code if the user entered one (optional).
prod Angry birds String Area of the product (optional).
rev 12 Float Revenue amount or “0” if none (optional).
currency USD Float Currency of revenue (optional).
id 12341 String If there is a method to identify individual user actions, e.g., an order ID, place the ID here (optional).
adchannel Click String Advertising channel name (optional).
campaign JAN21 String Campaign name (optional).
ts 2021-01-14T12:06:32 String Exact timestamp of event (optional).
country US String Country (optional).
lang en String User language (optional).
preattributed true String Displays whether this event was already attributed (optional).

 

Example URL:

https://CLIENTHOST/piwik/piwik.php?idsite=TV1234-1&rec=1&rand=534534&_id=0123456789ABCDEF&
cvar={"5": ["<ACTIONNAME>", "{\"source\": \"mytracker\", \"medium\": \"app\", \"promo\":
\"<PROMOCODE>\", \"ref\": \"<REFERER>\", \"prod\": \"<PRODUCT>\", \"rev\": 1234, \"id\":
\"<ACTIONID>\", \"dev\": \"<DEVICETYPE>\"}"]}&_cvar={"5": ["session", "{\"source\":
\"adjust\", \"medium\": \"app\", \"user\": \"U1234\", \"ip\": \"8.8.8.8\", \"deviceid\":
\"e3f5536a141811db40efd6400f1d0a4e\", \"appid\": \"wibble\"}"]}
Was this article helpful?
0 out of 0 found this helpful