Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 30 Next »

The Aniview Reporting API allows access to Aniview’s Ad Platform’s management functionality.

Login API

In order to use the API, it is required first to login into the publisher account with the account’s
credentials.

Request URL:
https://manage.aniview.com/api/token?format=json


Request Method:
POST

Headers:

Content-Type: application/json


Request payload (aka Body - Raw):

{
	"id": "<your@email.com>",
	"password": "<your_password>",
	"accountId": "<account_id>"
}

If your user is associated with multiple accounts, networks or publishers, specify the exact Id you would like to login to

Response Status Code:
401 Unauthorized - if you can’t log in
200 - success!!!


Response Body:
The Response will include a JSON object of data containing the returned token and the
accountId you are connected to.
Example:

{
	"data": {
		"token": "adadSodsaoSTdzQZUYi5IMdvadsRNCqs4tdaAvDSWTfNrxAsfeg5wzikAbE6NktCiYntw1KmhQ2A2v dvaNasdkg-JCmdPauDaddsGddadaaasd4Mi6EUUKbb2SWYIa3BGXTjeQrQIn53k9e94EuMjqRQ68PLEv8VZY3ie aRds_az2y3adCSq7mUCHg== ",
		"accountId": "5678fa70181f46dc32812345"
	}
}


Once you get a valid token, there are 2 alternative ways of using it:
Each API call should be sent with the token GET / POST / PUT / DELETE.

  1. Set the header:
    X-Bamboo-Token: <token>

  2. Set-Cookie:
    token=<token>

Logout API

The Logout API is called to clean your session cookie and logout from the session

Request URL:
https://manage.aniview.com/api/token/0?format=json


Request Method:
DELETE

Request payload (aka Body - Raw):

{
  “id”: 0
}

Status Code:
200 OK

Reporting API

Request URL:
https://manage.aniview.com/api/adserver/stats/report?startDate=1487548800&endDate=1487635199&dimensions=daily%2Chourly%2Ccou&metrics=inventory%2Cimpression%2Ccomplete&format=csv&query={}

https://manage.aniview.com/api/adserver/stats/report?format=csv&startDate=1582050453&endDate=1582136853&dimensions=daily%2Chourly%2Cncid&metrics=inventory%2CinventoryRequest%2Crequest%2Cbid%2Cimpression&query={"ncid":{"%24in":["56df1aba181f46c46f8b45af"]}}

Link parameters:

  1. Base URL: https://manage.aniview.com/api/adserver/stats/report

  2. startDate, endDate: Required parameters - Linux date of the start and end time of the report
    The following link can be used for the date conversion - https://www.epochconverter.com/
    E.g. startDate Sun, 21 Aug 2022 00:00:00 and endDate Mon, 22 Aug 23:59:59 would look as follows:

  3. tzo: -2 : Time zone offset in hours (optional)

  4. type: X (optional) - by default it’s Ad Server report, otherwise use:

    1. 6 for Content

    2. 2 for CDN

    3. 10 for SSAI

    4. 8 for Ads.txt

  5. dimensions: list of dimensions separated with an encoded comma (“,”) - you can use an encoder like https://meyerweb.com/eric/tools/dencoder/

  6. metrics: list of metrics separated with an encoded comma (“,”) - you can use an encoder like https://meyerweb.com/eric/tools/dencoder/

  7. format: csv or json

  8. query: HTML encoded query filter - you can use an encoder like https://meyerweb.com/eric/tools/dencoder/
    Sample query (before encoding): &query={"ncid":{"$in":[Vb9fea5181f46d4388b5555"]}}
    In this sample, it filters the report to include data only from the specified network channel

Request Method:
GET

Status Code:
Should download the report in CSV format. The JSON format is also supported.

Notes:

  1. By using startDate and endDate parameters, It is possible to retrieve hourly data
    between specific hours.

  2. If any dimension or metric does not exist – the value in the report will be “-“

Dimensions

Dimension

Description

Available for account

daily

Row per Day (date - linux format)

all

monthly

Row per month

all

weekday

The day of the week

all

weekly

Row per days of the week, Monday to Sunday (configurable)

all

hourly

Row per hour

all

nasid

Ad Source ID

network

nasidName

Ad Source Name

network

nasidEnv

Ad Source Environment

network

nasidDesc

Ad Source Description

network

nasidCreatedAt

Ad Source Creation Time

all

nasidStatus

Ad Source Status

all

nasidProvider

Ad Source Provider

network

nasidType

Ad Source Type

network

nasidOwnerType

Ad Source Demand Owner

network

ncid

Channel ID

all

ncidName

Channel Name

all

ncidPublisher

Channel Publisher *(for publisher represents App/Site ID)

network

ncidPublisherName

Channel Publisher Name *(for publisher represents App/Site)

network

ncidCreatedAt

Channel Created At

all

ncidStatus

Channel Status

all

ncidEnv

Channel Environment

all

coasid

Partner Connection ID

network

coasidName

Partner Connection Name

network

pcid

Publisher Channel ID

network

pcidName

Publisher Channel Name

network

pasid

Publisher Connection ID

network

pasidName

Publisher Connection Name

network

nid/iid

Network/Publisher ID

network

nName/iname

Network/Publisher Name

network

cou

Country

all

coun

Country Name

all

cos

OS

osv

Operation system version

all

r

Domain/Bundle ID

all

grR

Grouped Domain/Bundle ID

all

sn

Sub Id

all

brn

Browser Name

all

adType

Ad Type

all

proto

Protocol (http/https)

all

mc

Media Creative

all

tgt

Tag Type

all

viewability

Viewability

all

he

App Name

all

wi

Player Dimensions

all

viewabilityQuarters

Viewability Quarters

all

piv

Player in View

all

sellerID

The ID of the Network/Publisher/App/site/etc. - needed for ads.txt/supply chain

network

sellerType

Intermediary, Publisher or Both - needed for ads.txt/supply chain

network

stk

Sticky

all

fv

Player Position

all

AV_D1

Creative Type

all

AV_D6

City

all

AV_D7

Region

all

aid

Advertiser

network

aidid

Advertiser ID

network

cd1

Custom1

all

cd2

Custom2

all

cd3

Custom3

all

cd4

Custom4

all

cd5

Custom5

all

cd6

Custom6

all

cd7

Custom7

all

cd8

Custom8

all

cd9

Custom9

all

cd10

Custom10

all

impressionCapLimit

network

impressionCapFrequency

network

impressionCapMode

network

requestCapLimit

network

requestCapMode

network

AV_D35

AV_D17

AV_D18

sTagName

sTagType

sTplName

sTplType

Studio player tag ID

AV_D17

all

Device Type

AV_D32

all

AV_D51-64

Reserved for SSAI

network

Metrics

Event

Metric

Description

Available for account

playerLoaded

PlayerLoaded

Pixel should be implemented in player tag in order to support the metric: fired every time the player is loaded

all

playerStarted

PlayerStarted

Pixel fired once aniview.js is loaded

all

inventory

Inventory

Once there is the first serving request

all

inventoryRequest

InventoryRequest

The first serving call (when the waterfall is called)

all

request

Request

Every request to a Third-Party Ad Source

all

bid

Bid

When the Ad Source returns a valid response

all

bidRate

Bid Rate

= Bids/Requests*100

all

initAd

initAd ()

initAd

all

AdLoaded

AdLoaded

AdLoaded

all

startAd

startAd ()

startAd

all

impression

Impression

Impression (fired on AdImpression)

all

start

Start

Start event (fired on AdVideoStart)

all

adViImpression

Viewable Impression

When the player is viewable for at least 2 consecutive seconds

firstQuartile

First Quartile (25%)

First Quartile (25%)

all

midpoint

Mid Point (50%)

Midpoint (50%)

all

thirdQuartile

Third Quartile (75%)

Third Quartile (75%)

all

complete

Complete (100%)

Complete (100%)

all

completionRate

Completion Rate

=Complete/Impressions*100

all

fillRate

Fill Rate

= Impression/Inventory

 or

= impression/request (if Ad Source is a dimension)

all

opportunity

Opportunity

Fired once a Partner Connection is checked to see if any Ad Source within it can pass Optimization

network

tAvailable

Tags Available

Fired once one or more of the Ad Sources within a Partner Connection succeeded to be in the Waterfall

network

AdError

AdError

There was a VPAID Error

all

mediaPlayError

Media Play Error

There was an error while trying to play the media file

all

mediaTimeout

Media Timeout

While trying to play the media file there was a time error

all

AV_M1

Empty Waterfall

all

vpaidGeneralError

Vpaid General Error

General error of the player

all

vpaidLoadError

Vpaid Load Error

There was an error while trying to load the VPAID

all

vpaidLoadTimeout

Vpaid Load Timeout

There was a Timeout error while trying to load the VPAID JS.

all

vpaidInitAdError

Vpaid initAd Error

We called initAd () and the VPAID returned an AdError event

all

vpaidInitAdTimeout

Vpaid initAd Timeout

In the case that the VPAID does not respond with AdLoaded in the specified time, we will be an initAdTimeout error

all

vpaidStartAdError

Vpaid startAd Error

We called start ad startAd() there was and the VPAID returned AdError event

all

vpaidStartAdTimeout

Vpaid startAd Timeout

In the case that the VPAID does not respond with Ad Impression in the specified time, we will return a StartAdTimeout error

all

vpaidPlayError

Vpaid Play Error

There was an error while playing the ad

all

sec3

3 Sec

Pixel fired after the ad has played for 3 seconds

sec10

10 Sec

Pixel fired after the ad has played for 10 seconds

avr

AdsViewedRate

Ads Viewed Rate

all

aavt

AVGAdsViewedTime

AVG Ads Viewed Rate

all

dtavt

TotalAdsViewedTime

Total Ads Viewed Time

all

dtadt

TotalAdsDurationTime

Total Ads Duration Time

all

mute

Mute

Mute event

all

unmute

Unmute

Unmute

all

pause

Pause

Pause

all

resume

Resume

Resume

all

fullscreen

Full Screen

Full screen

all

rewind

Rewind

Rewind

all

click

Click

Click

all

ctr

CTR (Click-through-rate)

Click Through Rate

all

revenue

Revenue

Revenue

all

rwf

Revenue Without Fees

=Revenue - Accounting Fees

network

fee

Accounting Fees

Calculation of Fees based on Rules (See Acounting Fees Feature)

network

ncpm

Gross CPM ($)

Revenue CPM (Gross CPM)

all

rpm

RPM

Revenue by Inventory

all

rf

Request Fees

Request Fees

network

iccpm

Inventory Cost CPM

Inventory Cost (requires AV_IC to be passed in ref1)

network

ic

Inventory Cost

Inventory Cost CPM

network

chcost

Channel Cost

Channel Cost

network

chCpm

Channel Cost CPM

Channel Cost CPM

network

cost

Publisher/Partner Cost

Publisher/Partner Cost

network

costCpm

Publisher/Partner Cost CPM

Publisher/Partner Cost CPM

network

totalCost

Total Cost

=Publisher/Partner Cost + Channel Cost

network

totalCostCpm

Total Cost CPM

=Publisher/Partner Cost + Channel Cost

  CPM

network

profit

Profit

=Revenue - Total Cost

network

netCpm

Net CPM

= Revenue - Total Cost CPM

 

network

AV_M11 - AV_M20

Custom Events

Sum of Custom Event

network

avgViewability

Average viewability

Average viewability

all

viewabilityErr

Viewability Error

Sum of impression generated by undetected viewability (-1)

all

requestFillRate

Request FIll Rate

Impression/Request

all

AV_M41-43

in development

Reserved for SSAI

network

AV_M49

VIewavle Inventory

When the player is viewable for at least 2 consecutive seconds

Filters

Filter Name

Description

Possible Values

cd1-cd10

Custom Dimensions

Any Value

sn

Sub ID

any Value

PHP Code Snippet:

<?php

global $apiEp;
$apiEp = 'https://manage.aniview.com/api';

function login($id, $password, $accountId)
{
    global $apiEp;
    $tokenEp = $apiEp . '/token?format=json';
    $ch = curl_init($tokenEp);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");

    $data = array("id" => $id, "password" => $password, "accountId" => $accountId);
    $data_string = json_encode($data);

    curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $headers = array();
    $headers[] = 'Content-Type: application/json';
    $headers[] = 'Cache-Control: no-cache';
    $headers[] = 'Content-Length: ' . strlen($data_string);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POST, 1);


    $result = curl_exec($ch);
    $result = json_decode($result);

    curl_close($ch);

    return $result;
}

function fetchReport($tokenString, $startDate, $endDate, $dimensions, $metrics, $filtersJsonString, $format = 'csv', $polling = false)
{
    global $apiEp;
    
    $reportEP = $apiEp . '/adserver/stats/report?format=' . $format;
    $queryParams = "&startDate=$startDate&endDate=$endDate"
        . "&dimensions=" . urlencode(implode(",", $dimensions))
        . "&metrics=" . urlencode(implode(",", $metrics))
        . "&query=" . $filtersJsonString;

    $url = $reportEP . $queryParams;
    var_dump($url);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $headers = array();
    if ($format == 'json') {
        $headers[] = 'Content-Type: application/json';
    }
    $headers[] = 'Cache-Control: no-cache';
    $headers[] = "X-Bamboo-Token: $tokenString";
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    $output = curl_exec($ch);
    $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    var_dump($httpcode);
    if ($format == 'json') {
        $result = json_decode($output);
    } else {
        $result = $output;
    }

    curl_close($ch);

    return $result;
}

function getReportById($tokenString, $reportId)
{
    global $apiEp;

    $reportEP = $apiEp . "/adserver/report/$reportId?format=json";
    $url = $reportEP;
    var_dump($url);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $headers = array();
    $headers[] = 'Content-Type: application/json';
    $headers[] = 'Cache-Control: no-cache';
    $headers[] = "X-Bamboo-Token: $tokenString";
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    $output = curl_exec($ch);
    $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    var_dump($httpcode);
    $result = json_decode($output);
    curl_close($ch);

    return $result;
}

function getReportObjectForPolling($tokenString, $startDate, $endDate, $dimensions, $metrics, $filtersJsonString)
{
    global $apiEp;

    $reportEP = $apiEp . '/adserver/stats/report?format=json&reportFormat=csv';
    $queryParams = "&startDate=$startDate&endDate=$endDate"
        . "&returnReport=true" // Will return the report object for polling
        . "&dimensions=" . urlencode(implode(",", $dimensions))
        . "&metrics=" . urlencode(implode(",", $metrics))
        . "&query=" . $filtersJsonString;

    $url = $reportEP . $queryParams;
    var_dump($url);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $headers = array();
    $headers[] = 'Content-Type: application/json';
    $headers[] = 'Cache-Control: no-cache';
    $headers[] = "X-Bamboo-Token: $tokenString";
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    $output = curl_exec($ch);
    $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    var_dump($httpcode);
    $result = json_decode($output);
    curl_close($ch);

    return $result;
}


/**
 * Example for getting report as JSON
 * 
 * @param string $id
 * @param string $password
 * @param string $accountId
 * @return string|null
 */
function csvReportDataExample($id, $password, $accountId) {
    $tokenData = login($id, $password, $accountId);
    var_dump($tokenData);

    $tokenString = $tokenData->data->token;

// Start - now
    $endDate = time();
// End - One day back
    $startDate = $endDate - 60*60*24;
// Dimensions - Date, Hour, Channel ID
    $dimensions = array('daily', 'hourly', 'ncid');
// Metrics - inventory, inventoryRequest, request, bid, impression
    $metrics = array('inventory', 'inventoryRequest', 'request', 'bid', 'impression');
// Filter of channel example..
    $filterJsonString = '{"ncid":{"$in":["56df1aba181f4ccccf8b45af"]}}';
    $filterJsonString = '';

    $reportData = fetchReport($tokenString, $startDate, $endDate, $dimensions, $metrics, $filterJsonString);

    return $reportData;
}

/**
 * Example for polling report and getting reportObject when ready.
 * 
 * @param string $id
 * @param string $password
 * @param string $accountId
 * @return object
 * @throws Exception
 */
function pollingReportExample($id, $password, $accountId) {
    $tokenData = login($id, $password, $accountId);
    var_dump($tokenData);

    $tokenString = $tokenData->data->token;

// Start - now
    $endDate = time();
// End - One day back
    $startDate = $endDate - 60*60*24;
// Dimensions - Date, Hour, Channel ID
    $dimensions = array('daily', 'hourly', 'ncid');
// Metrics - inventory, inventoryRequest, request, bid, impression
    $metrics = array('inventory', 'inventoryRequest', 'request', 'bid', 'impression');
// Filter of channel example..
    $filterJsonString = '{"ncid":{"$in":["56df1aba181f4ccccf8b45af"]}}';
    $filterJsonString = '';

    $reportData = getReportObjectForPolling($tokenString, $startDate, $endDate, $dimensions, $metrics, $filterJsonString);
    $reportObj = $reportData->data;

    $pollingCount = 0;
    $pollingInterval = 15;
    $maxPollingAmount = 50;
    while($reportObj->status !== 7 && $pollingCount < $maxPollingAmount) {
        $pollingCount++;
        sleep($pollingInterval);

        // Get Report Again
        $reportData = getReportById($tokenString, $reportObj->_id['$oid']);
        $reportObj = $reportData->data;
    }

    if ($reportObj->status !== 7 || $reportObj->reportUrl === null) {
        throw new Exception("Failed to poll report", 500);
    }


    return $reportObj;
}

$id = 'av_report_example@aniview.com';
$password ='abcdEFG2010';
$accountId = '561e599e181f46b1328b4568';


/**
 * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
$reportData = csvReportDataExample($id, $password, $accountId);
var_dump($reportData);

try {
    $reportObj = pollingReportExample($id, $password, $accountId);
    if ($reportObj->status === 7 && $reportObj->reportUrl) {
        // Report Ready.
        // Download Report and handle result

    }
} catch (Exception $e) {
    log("Failed to get report");
}

 

Related articles

  • No labels