Publisher Events API

Adverse reporting is built on events received from the ad client. These event types include zoneLoad, load, impression, click, and action.

Each event includes context that describes its origin. These include Adverse entity IDs like zoneId and channelId, visitor criteria like userAgent and geoRegion, and publisher-supplied criteria like s1 or other custom data-* attributes.

Here is an example of an action event. We can see relevant information about the conversion and the originating context:

{
  // The type of event, one of: `zoneLoad`, `load`, `impression`, `click`, and `action`
  "type": "action",

  // Unique values related to this event
  "eventId": "cjsapmee28j3i19150pa5yn82",
  "timestamp": "2019-02-18T18:06:41.696Z",

  // This is an "action" event and will have the conversion price and click Id
  "price": "0.248125",
  "adverseClickId": "cjsanbsbr8d3m1915w6d020ih",

  // Visitor information
  "device": "tablet",
  "userAgent": "Mozilla/5.0 (iPad; CPU OS 12_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/72.0.3626.74 Mobile/15E148 Safari/605.1",
  "ip": "75.134.135.1",
  "geoPostal": "55803",
  "geoRegion": "MN",
  "geoLoc": "46.8749, -92.0941",
  "geoCountry": "US",
  "geoCity": "Duluth",

  // Any publisher-supplied custom criteria will be available here
  // Note: if the label conflicts with any Adverse-supplied property (e.g. "eventId" or "type" it will not be available)
  "customCriteriaLabel": "some custom value",
  "anotherCustomCriteriaLabel": "another custom value",

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

  // Adverse entity information, ids and names
  "network": "Some Network",
  "networkId": "gzhqcm",
  "publisher": "Some Publisher",  
  "publisherId": "612clq",
  "channel": "Some Channel",
  "channelId": "7wulq6",
  "site": "Some Site",
  "siteId": "63mp1q",
  "zone": "Some Zone",
  "zoneId": "80dvhx",
  "advertiser": "Some Advertiser",
  "advertiserId": "6nq2hb",
  "campaign": "Some Campaign",
  "campaignId": "7hujq3",
  "adGroup": "Some Ad Group",
  "adGroupId": "5jqovw",
  "ad": "Some Ad",
  "adId": "ed69ow",
  "creative": "Some Creative",
  "creativeId": "6wdulf",
}

To pull all events for a particular publisher, use this API endpoint:

https://adverse.lincx.la/api/publishers/report/$publisherId?startDate=2019-02-18&endDate=2019-02-18

You must replace $publisherId, 2019-02-18, and 2019-02-18 with appropriate values.

Also, be aware that events are both numerous and large. It is best to work with small date ranges.

This endpoint is protected, and you must provide an authentication token in an authorization header. To get an authentication token, see below.

Examples

cURL

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

Node.js

var request = require("request");

var options = { method: 'GET',
  url: 'https://adverse.lincx.la/api/publishers/report/$publisherId',
  qs: { startDate: '2019-02-18', endDate: '2019-02-18' },
  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://adverse.lincx.la/api/publishers/report/$publisherId?startDate=2019-02-18&endDate=2019-02-18",
  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

The endpoint to receive an authentication token is:

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

To get a token, send an HTTP POST request with a JSON body containing your email and password. Here are some examples:

cURL

curl -X POST \
  https://ix-id.lincx.la/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "user@domain.com","password": "somepassword"}'

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: 'user@domain.com', password: 'somepassword' },
  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\": \"user@domain.com\",\"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 pull information about a Publisher, use the following endpoint:

https://adverse.lincx.la/api/publishers/:publisherId

You'll receive an object like the following:

{
    "data": {
        "name": "Some Network",
        "networkId": "abc123",
        "owner": "user@domain.com",
        "id": "xyz987",
        "dateCreated": "2019-01-11T11:46:49.701Z",
        "dateUpdated": "2019-02-01T19:29:45.066Z",
        "members": [
            "member@domain.com"
        ],
        "revShare": 0.9
    }
}