Publisher Events API

Publisher Events API

In order to work with the Publisher Events API it's important to understand that reporting is based on events received from the ad client. Events can have various event types including:

• zoneLoad
• load
• impression
• click
• action

An event doesn't just have a type- it has a lot more data that includes context about the event and info that describes it. An event will include IDs for any associated entities like zoneId and channelId, visitor criteria like userAgent and geoRegion, and publisher-supplied criteria like s1 or other custom data-* attributes.

An example event object can be found below:

{
 "type": "action",
 "eventId": "dktbmmndd39h2j2981250xa6yd22",
 "timestamp": "2019-06-30T12:12:31.456Z",

// This is an "action" event & will have the conversion price & click Id
 "price": "0.347135",
 "adverseClickId": "dgtbdrste4c2n2802w7d130rt",

// Visitor data
 "device": "tablet",
 "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/527.16 (KHTML, like Gecko) Chrome/70.0.2467.18 Mobile Safari/527.16",
 "ip": "12.123.456.7",
 "geoPostal": "12345",
 "geoRegion": "CA",
 "geoLoc": "16.7349, -81.0811",
 "geoCountry": "US",
 "geoCity": "Los Angeles",

// Any publisher-supplied custom criteria will be available here
// Note: if the label conflicts with any pre-defined property
// (i.e. "eventId" or "type") it won't be available
 "customLabel": "some value",
 "anotherLabel": "some other value",

// The position the ad displayed in the feed
 "rank": "1",
// If the Ad has a CPC set, it will show here
 "cpc": "0",

// Related Entity info
 "network": "My Network",
 "networkId": "hzgwdm",
 "publisher": "A Cool Publisher", 
 "publisherId": "724cdw",
 "channel": "Amazing Channel",
 "channelId": "ewtyq8",
 "site": "New Site",
 "siteId": "23msc4r",
 "zone": "My Zone",
 "zoneId": "12ehjx",
 "advertiser": "A Cool Advertiser",
 "advertiserId": "0ml5hb",
 "campaign": "Amazing Campaign",
 "campaignId": "6zpeq2",
 "adGroup": "New Ad Group",
 "adGroupId": "4lwpkw",
 "ad": "My Ad",
 "adId": "bv19it",
 "creative": "A Cool Creative",
 "creativeId": "3whyrf",
}

To collect all events for a given publisher the GET request would be to this address:

https://api.lincx.com/api/publishers/report/$publisherId?startDate=$startDate&endDate=$endDate

You must replace $publisherId, $startDate, and $endDate with appropriate values for your query as indicated below.

https://api.lincx.com/api/publishers/report/724cdw?startDate=2019-06-29&endDate=2019-06-30

Because of the sheer size of the response, it's important to work with small date ranges as there are numerous events and events are quite large response objects. Due to the sensitive nature of the data returned, this endpoint will require authentication via an authentication token in the authorization header.

Examples

cURL

curl -X GET \
 'https://api.lincx.com/api/publishers/report/$publisherId?startDate=$startDate&endDate=$endDate' \
 -H 'Authorization: Bearer $authorizationToken'

Node.js

var request = require("request");

var options = { method: 'GET',
 url: 'https://api.lincx.com/api/publishers/report/$publisherId',
 qs: { startDate: '2019-06-29', endDate: '2019-06-30' },
 headers: { 'cache-control': 'no-cache', Authorization: 'Bearer $authorizationToken' } };

request(options, function (error, response, body) {
 if (error) throw new Error(error);

console.log(body);
});

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
 CURLOPT_URL => "https://api.lincx.com/api/publishers/report/$publisherId?startDate=2019-06-29&endDate=2019-06-30",
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_ENCODING => "",
 CURLOPT_MAXREDIRS => 10,
 CURLOPT_TIMEOUT => 30,
 CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
 CURLOPT_CUSTOMREQUEST => "GET",
 CURLOPT_POSTFIELDS => "",
 CURLOPT_HTTPHEADER => array(
 "Authorization: Bearer $authorizationToken"
 ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
 echo "cURL Error #:" . $err;
} else {
 echo $response;
}

Authentication Tokens

To receive an authorization token, send an HTTP POST request to the URL below with a JSON body with your login credentials (email and password).

https://ix-id.lincx.la/auth/login

Examples

cURL

curl -X POST \
 https://ix-id.lincx.la/auth/login \
 -H 'Content-Type: application/json' \
 -d '{"email": "[e-mail]","password": "password"}'

Node.js

var request = require("request");

var options = { method: 'POST',
 url: 'https://ix-id.lincx.la/auth/login',
 headers:
 { 'Content-Type': 'application/json' },
 body: { email: '[e-mail]', password: 'password' },
 json: true };

request(options, function (error, response, body) {
 if (error) throw new Error(error);

console.log(body);
});

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
 CURLOPT_URL => "https://ix-id.lincx.la/auth/login",
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_ENCODING => "",
 CURLOPT_MAXREDIRS => 10,
 CURLOPT_TIMEOUT => 30,
 CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
 CURLOPT_CUSTOMREQUEST => "POST",
 CURLOPT_POSTFIELDS => "{\"email\": \"[e-mail]\",\"password\": \"somepassword\"}",
 CURLOPT_HTTPHEADER => array(
 "Content-Type: application/json"
 ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
 echo "cURL Error #:" . $err;
} else {
 echo $response;
}

Publisher Information

To gather information about a Publisher

https://api.lincx.com/api/publishers/$publisherId

Example response:

{
 "data": {
   "name": "Amazing Network",
   "networkId": "def456",
   "owner": "[e-mail]",
   "id": "abc123",
   "dateCreated": "2019-06-21T12:44:38.361Z",
   "dateUpdated": "2019-06-01T12:17:23.546Z",
   "members": [
     "[e-mail]"
    ],
   "revShare": 0.7
 }
}