NAV
javascript php python json

Introduction

Welcome to the Chartboost S2S, Mediation, and Ad Exchange API documentation!

This site is divided into three sections: Chartboost S2S API, Chartboost Publisher Mediation, and Chartboost Exchange.

How to Read These Docs

These docs demonstrate how to make the requests to send to our API endpoints, with each endpoint’s required and optional parameters described in detail.

You’ll also find information about which HTTP method to use, which headers to include, etc.

We provide code examples where appropriate in Node.js, Python, and PHP. You can view these code examples in the dark area to the right and use the tabs at the top of that section to switch programming languages.

While this documentation and the code examples were designed to eliminate ambiguity about our endpoints, we’re more than happy to answer any remaining questions you might have – just contact our Integrations Support Team for assistance.

(Note: At some points in these docs, we will use double curly braces to signify a variable that should be replaced at a certain point. For example, we might notate {{api token}} in one parameter. When sending requests of your own, you should replace it with a value. So in practice, {{api token}} may become "my_network_api_token".)

Chartboost S2S API v2

S2S Install Attribution Overview

Looking for S2S API v1 documentation?

Chartboost’s S2S Install Tracking program allows advertisers to use attribution data from approved third parties and run CPI campaigns on the Chartboost network.

After an app has Requested S2S Install Tracking and Chartboost approves it, the app’s CPI campaigns will begin listening only to install postbacks sent to our S2S endpoint and will stop using the Chartboost SDK (if applicable) for install attribution.

Requirements

Attributed Installs

Installs attributed via clicks (and completed views if you support view-through attribution) should be sent to this endpoint. For click-through attributions, include the click_id parameter; for view-through attributions, include the completed_view_id parameter.

For click-through attribution, you must enforce a minimum 7-day attribution window. Chartboost will honor up to a maximum 21-day attribution window.

For view-through attribution, there is no minimum attribution window. Chartboost supports a maximum 3-day attribution window, and recommends a 24-hour default window.

Global Postback URL

https://live.chartboost.com/api/v2/attributed_install

This endpoint receives only attributed install postbacks. Installs will be processed for conversion, stored, and used in reporting.

<?php

const CB_ATTRIBUTION_ENDPOINT = "https://live.chartboost.com/api/v2/attributed_install";
const CB_API_TOKEN = "{{your API token}}"; 

$click_id = "{{the click id}}"; # e.g. "178660e204b0166e0364e637"
$completed_view_id = "{{completed view id}}"; # e.g. "178660e204b0166e0364e638", only required in case of view-through attribution

$data = json_encode(array(
  "token"               => CB_API_TOKEN,
  "click_id"            => $click_id,
  # "completed_view_id" => $completed_view_id
));


$headers = array(
  "Content-Type" => "application/json"
);


Requests::post(CB_ATTRIBUTION_ENDPOINT, $headers, $data);
?>
import json
import hashlib
import requests


CB_ATTRIBUTION_ENDPOINT = 'https://live.chartboost.com/api/v2/attributed_install'
CB_API_TOKEN = '{{your_api_token}}'

click_id = '{{click id}}'  # e.g. "178660e204b0166e0364e637"
completed_view_id = '{{completed view id}}' # e.g. "178660e204b0166e0364e638". only required in case of view-through attribution

data = json.dumps({
  'token'               : CB_API_TOKEN,
  'click_id'            : click_id,
  # 'completed_view_id' : completed_view_id
})

headers = {
  'Content-Type': 'application/json'
}

requests.post(CB_ATTRIBUTION_ENDPOINT, data=data, headers=headers)
var https = require('https');
var crypto = require('crypto');

var data, 
    options, 
    req,
    txn_id_key,
    txn_id_value,
    request_json = {};

const CB_API_TOKEN = "{{your_api_token}}",
      CB_ATTRIBUTION_HOST = "live.chartboost.com",
      CB_ATTRIBUTION_PATH = "/api/v2/attributed_install",
      CB_ATTRIBUTION_PORT = "443";

var click_id = "{{click id}}";  // e.g. "178660e204b0166e0364e637"
var completed_view_id = "{{completed view id}}"; // e.g. "178660e204b0166e0364e638, only required in case of view-through attribution

// if click_id is present, send click_id, else send completed_view_id for view-through attribution
txn_id_key               = (typeof click_id !== "undefined") ? "click_id" : "completed_view_id";
txn_id_value             = (typeof click_id !== "undefined") ? click_id : completed_view_id;
request_json['token']    = CB_API_TOKEN;
request_json[txn_id_key] = txn_id_value;


function sendInstall(callback) {
    data = JSON.stringify(request_json);
    console.log(data)
    options = {
        host: CB_ATTRIBUTION_HOST,
        path: CB_ATTRIBUTION_PATH,
        port: CB_ATTRIBUTION_PORT,
        method: 'POST',
        agent: false,
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': data.length
        }
    };
    // Build the request using node https module
    req = https.request(options, function(res) {
        res.setEncoding('utf8');
        console.log("statusCode: ", res.statusCode);
        res.on('data', function(chunk) {
            console.log('Response: ' + chunk);
        });
    });
    req.write(data);
    req.end();
    callback();
}

// Send it!
sendInstall( function() {
    console.log("  POST request sent to: " + CB_ATTRIBUTION_HOST + CB_ATTRIBUTION_PATH);
  } 
);

// Valid Request Response
// {"message":"Install request received!","status":200}

Authentication

All API endpoints require a token parameter included in the request, which is your public S2S API token.

Headers

Each request must contain the following headers:

Header Value
Content-Type application/json

Request Parameters

Each request must use these parameters:

Name Required Type Description
token true string Your Chartboost S2S API token
click_id true* string Required if click-through attribution
completed_view_id true* string Required if view-through attribution

Method: POST

POST https://live.chartboost.com/api/v2/attributed_install

See code examples of POST requests to the right.

Method: GET

Click-through attribution: GET https://live.chartboost.com/api/v2/attributed_install?token={your API token}&click_id={click id}

View-through attribution: GET https://live.chartboost.com/api/v2/attributed_install?token={your API token}&completed_view_id={completed view id}

Opens (Bootups)

Each time a user (both attributed and non-attributed) opens the app, a postback should be sent to this endpoint. Chartboost uses this data to track player retention and negatively target existing devices.

If you do not send app open events for non-attributed users, Chartboost cannot avoid showing ads to them. This may negatively impact campaign performance, and will also prevent the automated S2S approval of new apps.

Global Postback URL

https://live.chartboost.com/api/v2/open

This endpoint receives only app open (bootup) postbacks.

<?php

const CB_ATTRIBUTION_ENDPOINT = "https://live.chartboost.com/api/v2/open";
const CB_API_TOKEN = "{{your API token}}"; 

$app_id       = "{{Chartboost app id}}"; 
$idfa         = "{{device IDFA}}";
$gaid         = "{{device GAID}}";
$uuid         = "{{Android ID}}";
$tracking_id  = "{{tracking URL identifier}}";
$version      = "{{app bundle version}}";

$data = json_encode(array(
  "token"       => CB_API_TOKEN,
  "app_id"      => $app_id,
  "idfa"        => $idfa,
  # "gaid"      => $gaid,
  # "uuid"      => $uuid,
  "tracking_id" => $tracking_id,
  "version"     => $version
));


$headers = array(
  "Content-Type" => "application/json",
);


Requests::post(CB_ATTRIBUTION_ENDPOINT, $headers, $data);
?>
import json
import hashlib
import requests


CB_ATTRIBUTION_ENDPOINT = 'https://live.chartboost.com/api/v2/open'
CB_API_TOKEN = '{{your_api_token}}'

app_id        = '{{Chartboost app id}}'
idfa          = '{{IDFA}}'
gaid          = '{{GAID}}'
uuid          = '{{Android ID}}'
tracking_id   = '{{tracking URL identifier}}'
version       = '{{app bundle version}}'

data = json.dumps({
  'token'       : CB_API_TOKEN,
  'app_id'      : app_id,
  'idfa'        : idfa,
  # 'gaid'      : gaid,
  # 'uuid'      : uuid,
  'tracking_id' : tracking_id,
  'version'      : version
})

headers = {
  'Content-Type': 'application/json',
}

requests.post(CB_ATTRIBUTION_ENDPOINT, data=data, headers=headers)
var https = require('https');
var crypto = require('crypto');

var data, 
    options, 
    req,
    transaction_id_type,
    transaction_id_value,
    request_json = {};

const CB_API_TOKEN = "{{your_api_token}}",
      CB_ATTRIBUTION_HOST = "live.chartboost.com",
      CB_ATTRIBUTION_PATH = "/api/v2/open",
      CB_ATTRIBUTION_PORT = "443";

var app_id        = "{{Chartboost app id}}", 
    idfa          = "{{IDFA}}", 
    gaid          = "{{GAID}}", 
    uuid          = "{{Android ID}}", 
    tracking_id   = "{{tracking URL identifier}}", 
    version       = "{{app bundle version}}";


function sendInstall(callback) {
    data = JSON.stringify(request_json);
    console.log(data)
    options = {
        host: CB_ATTRIBUTION_HOST,
        path: CB_ATTRIBUTION_PATH,
        port: CB_ATTRIBUTION_PORT,
        method: 'POST',
        agent: false,
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': data.length
        }
    };
    // Build the request using node https module
    req = https.request(options, function(res) {
        res.setEncoding('utf8');
        console.log("statusCode: ", res.statusCode);
        res.on('data', function(chunk) {
            console.log('Response: ' + chunk);
        });
    });
    req.write(data);
    req.end();
    callback();
}

// Send it!
sendInstall( function() {
    console.log("  POST request sent to: " + CB_ATTRIBUTION_HOST + CB_ATTRIBUTION_PATH);
  } 
);

// Valid Request Response
// {"message":"Install request received!","status":200}

Authentication

All API endpoints require a token parameter included in the request, which is your public S2S API token.

Headers

Each request must contain the following headers:

Header Value
Content-Type application/json

Request Parameters

Each request must use these parameters:

Name Required Type Description
token true string Your Chartboost S2S API token
app_id true string Chartboost app id
idfa true* string Device Identifier For Advertising if iOS app
gaid true* string Device Google Advertising Identifier if Google Play app
uuid true* string Device Android Identifier if Amazon app
tracking_id false string A value used to verify the correct tracking URL is in use for the app, necessary for automated S2S approval of the app.†
version false string The app’s package version, necessary for automated S2S approval of the app.†

† Please contact integrations@chartboost.com for more information on our automated S2S approval process and why we highly recommend you take advantage of this new feature.

Method: POST

POST https://live.chartboost.com/api/v2/open

See code examples of POST requests to the right.

Method: GET

iOS:

GET https://live.chartboost.com/api/v2/open?token={your API token}&app_id={Chartboost app id}&idfa={device IDFA}&tracking_id={TRACKING ID}&version={APP VERSION}

Android:

GET https://live.chartboost.com/api/v2/open?token={your API token}&app_id={Chartboost app id}&gaid={device GAID}&tracking_id={TRACKING ID}&version={APP VERSION}

Amazon:

GET https://live.chartboost.com/api/v2/open?token={your API token}&app_id={Chartboost app id}&uuid={device Android ID}&tracking_id={TRACKING ID}&version={APP VERSION}

Post-Install Events

For a more complete analysis of player profiles across platforms or networks, Chartboost customers can configure third-party tracking services to send their in-app purchase event data to Chartboost. Third-party tracking services can use the instructions on this page to build their initial event tracking integration.

Overview

The Post-Install Analytics (PIA) integration lets Chartboost customers view IAP data – payer %, ARPU, purchase counts, ARPPU and more – in the Chartboost dashboard. They can then use this data to build custom player segments to power retargeting campaigns and optimize user acquisition efforts. Developers can also send custom in-app events for tracking level progression or events like Tutorial Completion, Player Registration, etc.. These events can then be used to set up User Segments and applied to campaign targeting efforts.

PIA Requirements

Purchases

<?php

const CB_PIA_ENDPOINT = "https://live.chartboost.com/event_service/v3/track";
const CB_API_TOKEN = "{{your_api_token}}"; 
const CB_API_SECRET = "{{your_api_secret}}";

$app_id = "54ecc0535beacdc1e1eff778";  # replace this with your app id
$app_signature = "601be68e3bb4e7eb953024eb4f2ac03376e2c2fb";  # replace this with your app signature
$gaid = "8df6c9bf-d647-4400-bc13-7ff317ff0003";  # example Google Advertising ID
$ifa = "8df6c9bf-d647-4400-bc13-7ff317ff0004";  # example iOS Identifier For Advertising
$product_id = "bag_of_gems";  # example `product_id`
$currency = "USD";  # example `currency` code
$price = 1.99;  # example `price`
$localized_title = "bolsa de gemas";  # optional, used for translating product name from English to another language
$localized_description = "un bolsa de gemas";  # optional, used for translating product description from English to another language

$data = json_encode(array(
    "app_id" = > $app_id,
    "gaid" => $gaid,
    # "ifa" = $ifa,
    "iap" => array(
            "product_id": $product_id, 
            "currency": $currency, 
            "price": $price, 
            "localized_title": $localized_title, 
            "localized_description": $localized_description
    ),
));

# Create the header signature
$descriptor = "action:pia\n" + CB_API_SECRET + "\n" + app_signature + "\n" + data;
$signature = crypto.createHash('sha256').update(descriptor).digest('hex');

$headers = array(
  "Content-Type" => "application/json",
  "X-Chartboost-Token" => CB_API_TOKEN,
  "X-Chartboost-Signature" => $signature
);

# Send the postback
Requests::post(CB_PIA_ENDPOINT, $headers, $data);
?>
import json
import hashlib
import requests

CB_PIA_ENDPOINT = 'https://live.chartboost.com/event_service/v3/track'
CB_API_TOKEN = '{{your_api_token}}'
CB_API_SECRET = '{{your_api_secret}}'

app_id = '54ecc0535beacdc1e1eff778'  # replace this with your app id
app_signature = '601be68e3bb4e7eb953024eb4f2ac03376e2c2fb'  # replace this with your app signature
gaid = '8df6c9bf-d647-4400-bc13-7ff317ff0003'  # example Google Advertising ID
ifa = '8df6c9bf-d647-4400-bc13-7ff317ff0004'  # example iOS Identifier For Advertising
product_id = 'bag_of_gems'  # example `product_id`
currency = 'USD'  # example `currency` code
price = 1.99  # example `price`
localized_title = 'bolsa de gemas'  # optional, used if translating product title from English to another language
localized_description = 'un bolsa de gemas'  # optional, used if translating product description from English to another language

data = json.dumps({
    'app_id': app_id,
    'gaid': gaid,
    #'ifa': ifa,
    'iap': {
        'product_id': product_id,
        'currency': currency,
        'price': price,
        'localized_title': localized_title,
        'localized_description': localized_description
    }
})

# Create the header signature
descriptor_template = 'action:pia\n{}\n{}\n{}'
descriptor = descriptor_template.format(CB_API_SECRET, app_signature, data)
signature = hashlib.sha256(descriptor).hexdigest()

headers = {
  'Content-Type': 'application/json',
  'X-Chartboost-Token': CB_API_TOKEN,
  'X-Chartboost-Signature': signature
}

# Send the postback
requests.post(CB_PIA_ENDPOINT, data=data, headers=headers)
var https = require('https');
var crypto = require('crypto');

var data, descriptor, signature, options, req;
const CB_PIA_HOST = "live.chartboost.com";
const CB_PIA_PATH = "/event_service/v3/track"; 
const CB_PIA_PORT = "443";
const CB_API_SECRET = "{{your_api_secret}}"; 
const CB_API_TOKEN = "{{your_api_token}}"; 


var app_id = "54ecc0535beacdc1e1eff778";  // replace this with your app id
var app_signature = "601be68e3bb4e7eb953024eb4f2ac03376e2c2fb";  // replace this with your app signature
var gaid = "8df6c9bf-d647-4400-bc13-7ff317f046f3";  // example Google Advertising ID
var ifa = "8df6c9bf-d647-4400-bc13-7ff317ff0004"  // example iOS Identifier For Advertising
var product_id = "bag_of_gems";  // example `product_id`
var currency = "USD";  // example `currency` code
var price = 1.99;  // example `price`
var localized_title = "bolsa de gemas";  // optional, used if translating product title from English to another language
var localized_description = "un bolsa de gemas"  // optional, used if translating product description from English to another language


function sendEvent(callback) {
    data = JSON.stringify({
        "app_id": app_id, 
        "gaid": gaid,
        // "ifa": ifa,
        "iap": {
            "product_id": product_id,
            "currency": currency,
            "price": price,
            "localized_title": localized_title,
            "localized_description": localized_description
        }
    });

    // X-Chartboost-Signature is generated on every request using the following hashing algorithm 
    descriptor = "action:pia\n" + CB_API_SECRET + "\n" + app_signature + "\n" + data;
    signature = crypto.createHash('sha256').update(descriptor).digest('hex');

    options = {
        host: CB_HOST,
        port: CB_PORT,
        path: CB_PATH,
        method: 'POST',
        agent: false,
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': data.length,
            'X-Chartboost-Token': CB_API_TOKEN,
            'X-Chartboost-Signature': signature
        }
    };

    // Build the request using node https module
    req = https.request(options, function(res) {
        res.setEncoding('utf8');
        console.log("statusCode: ", res.statusCode);
        res.on('data', function(chunk) {
            console.log('Response: ' + chunk);
        });
    });

    req.write(data);
    req.end();
    callback();
}

// Send the postback
sendEvent( function() {
        console.log(data);
    }
);

Sample Response

{
  "status": 200,
  "message": "OK"
}

HTTPS Request

POST https://live.chartboost.com/event_service/v3/track

Authentication

To authenticate with this endpoint, you must generate a signature on each request. A string with the following template must be made, and the signature is created by taking the SHA-256 hash of the string. Note that anything contained within double curly brackets is a variable that is meant to be replaced by your server.

Computed Signature: "action:pia\n{{CB_API_SECRET}}\n{{app_signature}}\n{{JSON data}}"

The Chartboost app signature is an identifier unique to each individual app in the Chartboost dashboard. Chartboost developers can find their game’s app signature on the Chartboost dashboard’s App Settings page:

The resulting digest from the hash function should be sent in the X-Chartboost-Signature header in the request. For an example of the signature hashing, refer to the code example.

Headers

Header Value
Content-Type application/json
X-Chartboost-Token {{your_api_token}}
X-Chartboost-Signature {{computed signature}}

Request Parameters

Name Required Type Description
app_id true string Chartboost app ID (found in the Chartboost dashboard)
gaid true* string Google advertising identifier, required if Google Play Store app
uuid false string Legacy Android ID, required if gaid unavailable such as with Amazon devices
ifa true string Apple identifier for advertising, required if iTunes Store app
iap true* object JSON of in-app purchase details; see IAP object requirements section below
event true* object JSON of custom event details; see Event object requirements section below

IAP object requirements

Name Required Type Description
product_id true string Unique identifier describing the purchased item
price true float Price paid for the item
currency true string 3-letter currency code, if currency is unavaiable, a static string of "USD" is acceptable.
localized_title false string Localized name of the purchased item.
localized_description false string Localized description of the purchased item.
<?php

const CB_PIA_ENDPOINT = "https://live.chartboost.com/event_service/v3/track";
const CB_API_TOKEN = "{{your_api_token}}"; 
const CB_API_SECRET = "{{your_api_secret}}";

$app_id = "54ecc0535beacdc1e1eff778"; # replace this with your app id
$app_signature = "601be68e3bb4e7eb953024eb4f2ac03376e2c2fb"  # replace this with your app signature
$gaid = "8df6c9bf-d647-4400-bc13-7ff317ff0000";  # example Google Advertising ID
$ifa = "8df6c9bf-d647-4400-bc13-7ff317ff0004";  # example iOS Identifier For Advertising
$event_label = "Level Completed";  # example `event_label`; use only one `event_label` per `event_field` value.
$event_field = 1;  # example `event_field`; use only one `event_field` per `event_label` value.
$main_level = 12; # example `main_level`; indicates that player completed level 12 in game.
$sub_level = 0;  # example `sub_level`; indicates that there is no sub_level associated with the event -- set as 0 if no sub_level value is provided.
$description = "Hidden Caverns";  # example `description`; indicates that main_level 12 is known as "Hidden Caverns".

$data = json_encode(array(
    "app_id" => $app_id,
    "gaid" => $gaid,
    #"ifa" => $ifa,
    "event" => array( 
            "event_label": $event_label,  
            "event_field": $event_field,  
            "main_level": $main_level,
            "sub_level": $sub_level,
            "description": $description
    ),
));

# Create the header signature
$descriptor = "action:pia\n" + CB_API_SECRET + "\n" + app_signature + "\n" + data;
$signature = crypto.createHash('sha256').update(descriptor).digest('hex');

$headers = array(
  "Content-Type" => "application/json",
  "X-Chartboost-Token" => CB_API_TOKEN,
  "X-Chartboost-Signature" => $signature
);

# Send the postback
Requests::post(CB_PIA_ENDPOINT, $headers, $data);
?>
import json
import hashlib
import requests

CB_PIA_ENDPOINT = 'https://live.chartboost.com/event_service/v3/track'
CB_API_TOKEN = '{{your_api_token}}'
CB_API_SECRET = '{{your_api_secret}}'

app_id = '54ecc0535beacdc1e1eff778'  # replace this with your app id
app_signature = '601be68e3bb4e7eb953024eb4f2ac03376e2c2fb'  # replace this with your app signature
gaid = '8df6c9bf-d647-4400-bc13-7ff317f046f3'  # example Google Advertising ID
ifa = '8df6c9bf-d647-4400-bc13-7ff317ff0004'  # example iOS Identifier For Advertising
event_label = 'Level Completed'  # example `event_label`; use only one `event_label` per `event_field` value.
event_field = 1  # example `event_field`; use only one `event_field` per `event_label` value.
main_level = 12  # example `main_level`; indicates that player completed level 12 in game.
sub_level = 0  # example `sub_level`; indicates that there is no sub_level associated with the event -- set as 0 if no sub_level value is provided.
description = 'Hidden Caverns'  # example `description`; indicates that main_level 12 is known as "Hidden Caverns".

data = json.dumps({
    'app_id': app_id,
    'gaid': gaid,
    # 'ifa': ifa,
    'event': {
        'event_label': event_label,  
        'event_field': event_field,  
        'main_level': main_level,
        'sub_level': sub_level,
        'description': description
    }
})

# Create the header signature
descriptor_template = 'action:pia\n{}\n{}\n{}'
descriptor = descriptor_template.format(CB_API_SECRET, app_signature, data)
signature = hashlib.sha256(descriptor).hexdigest()

headers = {
  'Content-Type': 'application/json',
  'X-Chartboost-Token': CB_API_TOKEN,
  'X-Chartboost-Signature': signature
}

# Send the postback
requests.post(CB_PIA_ENDPOINT, data=data, headers=headers)
var https = require('https');
var crypto = require('crypto');

var data, descriptor, signature, options, req;
const CB_PIA_HOST = "live.chartboost.com";
const CB_PIA_PATH = "/event_service/v3/track"; 
const CB_PIA_PORT = "443";
const CB_API_SECRET = "{{your_api_secret}}"; 
const CB_API_TOKEN = "{{your_api_token}}"; 


var app_id = "54ecc0535beacdc1e1eff778";  // replace this with your app id
var app_signature = "601be68e3bb4e7eb953024eb4f2ac03376e2c2fb";  // replace this with your app signature
var gaid = "8df6c9bf-d647-4400-bc13-7ff317f046f3";  // example Google Advertising ID
var ifa = "8df6c9bf-d647-4400-bc13-7ff317ff0004";  // example iOS Identifier For Advertising
var event_label = "Level Completed";  // example `event_label`; use only one `event_label` per `event_field` value.
var event_field = 1;  // example `event_field`; use only one `event_field` per `event_label` value.
var main_level = 12;  // example `main_level`; indicates that player completed level 12 in game.
var sub_level = 0;  // example `sub_level`; indicates that there is no sub_level associated with the event -- set as 0 if no sub_level value is provided.
var description = "Hidden Caverns";  // example `description`; indicates that main_level 12 is known as "Hidden Caverns".


function sendEvent(callback) {
    data = JSON.stringify({
        "app_id": app_id, 
        "ifa": ifa,
        // "gaid": gaid, 
        "event": {
            "event_label": event_label,  
            "event_field": event_field,  
            "main_level": main_level,
            "sub_level": sub_level,
            "description": description
        }   
    });

    // X-Chartboost-Signature is generated on every request using the following hashing algorithm 
    descriptor = "action:pia\n" + CB_API_SECRET + "\n" + app_signature + "\n" + data;
    signature = crypto.createHash('sha256').update(descriptor).digest('hex');

    options = {
        host: CB_PIA_HOST,
        port: CB_PIA_PORT,
        path: CB_PIA_PATH,
        method: 'POST',
        agent: false,
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': data.length,
            'X-Chartboost-Token': CB_API_TOKEN,
            'X-Chartboost-Signature': signature
        }
    };

    // Build the request using node https module
    req = https.request(options, function(res) {
        res.setEncoding('utf8');
        console.log("statusCode: ", res.statusCode);
        res.on('data', function(chunk) {
            console.log('Response: ' + chunk);
        });
    });

    req.write(data);
    req.end();
    callback();
}

// Send the postback
sendEvent( function() {
        console.log(data);
    }
);

The PIA custom event tracking integration works by sending player event/level data – tutorial completed, for example – in the form of distinct Event Fields.

Event object requirements

Name Required Type Description
event_label true string Unique string describing the type of event, should always be the same for a given event_field.
event_field true integer An integer 1 through 5, should always be the same for a given event_label.
main_level true integer Represents the main value to be associated with the event; must be >= 1.
sub_level true integer Represents the sub value to be associated with the event; must be >= 0; send 0 if no sub_level is provided.
description false string Description of the main_level value (such as the given level’s name); optional.

Event Field / Event Label

Each event field must correspond to a single type of event, e.g. “Level Reached” or “Registration Completed”.

Example event fields are listed in the table below; common use cases follow:

Event FieldSequential?2DefinitionExample Event Label 1Optional
Description Example 3
1 Yes Highest numerical level a user has reached “Highest level puzzle solved” “Chocolate Fudge Level”
2 User’s current level/area “Area main character is in” “Lunar Caverns”
3 Yes The level of the player’s character in game “Level of the character class” “Master Wizard”
4 Yes Extra field for developers to send sequential data “VIP reward level” “5”
5 Extra field for developers to send non-sequential data “FTUE completed?” “Tutorial Completed”

Notes

  1. event_label is required and will be used to identify the type of event field in the Chartboost dashboard
  2. An associated event_field is used to track either 1) level data that is always increasing and can never decrease; or 2) numerical data developers need to segment based on whether a player is “higher” or “lower” than a certain number
  3. Optional event description can be used to identify specific level values. For example, if main_level==2, description might be “Lunar Caverns,”, while main_level==3 might be “Lunar Landing”. The event_label describes more generically the type of the event, such as “Level Reached”.

Of the five event_field options, three (1,3,4) can be used for sequential level values, while the other two (2,5) can be used for non-sequential level values. These integer-based level values can be used, for example, to track if the player has gotten to level 3, 8, 17, etc., which is always increasing and can never decrease, or any other numerical data you need to segment based on whether a player is “higher” or “lower” than.

Note: For event_field 1, 3, or 4 (sequential events), Chartboost only records the player’s first level event along with subsequent level value increases. Sequential events with level values that are equal to or less than the player’s current value are discarded.

Additional Notes on Custom Events

Inside the request, event is a single JSON object element. This object specifies the details of the event.

The event_field specifies the event type (1,2,3,4, or 5). In your advertiser-facing UI, the event_field should be able to be selected by the Chartboost customer and will correspond to a specific event tracked in your platform, labeled as the Event ID.

The event_label describes the nature of its corresponding event_field. The event_label can be the name of the event according to the app, but if possible you should allow user override of the event name in your dashboard.

For non-sequential or non-numerical events, set main_level:1 and sub_level:0 in the request.

Errors

Chartboost APIs use the following error codes:

Error Code Meaning
400 Bad Request – Your request is formatted incorrectly, contains bad values, or does not include required parameters.
403 Forbidden – You have supplied an incorrect signature or are using an invalid API token.
404 Not Found – The resource could not be found or required parameters contain bad values (invalid Click ID for example)
405 Method Not Allowed – You are using an invalid HTTP method for the resource.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

If your call receives a 5xx HTTP error code, your server should retry the request using an exponential back-off: Try again in 5 seconds, then 10 seconds, then 20 seconds, then 40 seconds, etc.. Set a max number of retries or TTL that can accomodate temporary server outages (recommended: 24 hour TTL).

Chartboost Publisher Mediation

Discrepancies between Chartboost Dashboard and Mediation Partner Dashboard

Chartboost mediation partners consume information about publisher traffic from Chartboost via our real-time API and aggregate this data into their “Mediation Dashboard”. Since this is a separate API exclusively built for mediation, publishers may observe discrepancies in reporting between the Chartboost Dashboard, other Chartboost API endpoints, and the Mediation Dashboard.

The technical specifications on how to utilize this dedicated API can be found on the Chartboost Helpsite: AppCountry endpoint. Access to the endpoint however, is available to publishers themselves, and they can research potential discrepancies directly with their User IDs and Signatures.

We’re happy to help investigate discrepancies, but before reaching out, it may help to have a look at some of the most common causes for differences in reporting:

Chartboost Exchange




Welcome, partner!
We’re excited that you want to go programmatic on the Chartboost network. Here are the specs and other need-to-know information about integrating us with your real-time bidding platform. Please contact us with any questions or concerns.

OpenRTB Bid Request Specifications

// Interstitial placement: static OR playable (MRAID) 
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "imp": [
    {
      "id": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
      "banner": {
        "api": [3],
        "w": 320,
        "h": 480,
        "wmax": 1536,
        "hmax": 2008,
        "pos": 7,
        "topframe": 1,
        "battr": [1, 2, 6, 7],
        "btype": [4],
        "ext": {
          "placementtype": "interstitial",
          "playableonly": false
        }
      },
      "instl": 1,
      "tagid": "Default",
      "displaymanager": "Chartboost-iOS-SDK",
      "displaymanagerver": "6.6.1",
      "bidfloor": 0.5,
      "bidfloorcur": "USD",
      "secure": 1
    }
  ],
  "app": {
    "id": "4fa7c657f77659a92b000111",
    "name": "Buster's Boost",
    "bundle": "com.chartboost.apollo",
    "storeurl": "https://itunes.apple.com/us/app/busters-boost/id907175713",
    "cat": ["IAB9-30"],
    "publisher": {
      "id": "4dd5173cbb93162407001111",
      "name": "Chartboost Sample Company"
    }
  },
  "device": {
    "carrier": "WIFI",
    "connectiontype": 2,
    "devicetype": 1,
    "geo": {
      "city": "San Francisco",
      "country": "US",
      "region": "CA",
      "type": 2,
      "zip": "94105"
    },
    "h": 2008,
    "w": 1536,
    "ifa": "EEEE44E2-EC2C-C266-4A64-AD1CADA1D062",
    "ip": "50.174.86.6",
    "language": "en",
    "lmt": 0,
    "model": "iPad4,4",
    "os": "iOS",
    "osv": "10.0.1",
    "ua": "Mozilla/5.0 (iPad; CPU OS 10_0_1 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A403"
  },
  "user": {
    "id": "20470538-b75f-11e6-a614-6158f10b9151",
    "geo": {
      "country": "US",
      "type": 2,
      "region": "CA",
      "city": "San Francisco",
      "zip": "94105"
    }
  },
  "at": 2,
  "cur": ["USD"],
  "regs": {
    "coppa": 0
  },
  "badv": [
    "badapps.com",
    "worseapps.com"
  ],
  "bcat": ["IAB2-3"],
  "bapp": ["com.badapps.badapp"],
  "test": 0
}

// Interstitial placement: video only (VAST)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "imp": [
    {
      "id": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
      "video": {
        "mimes": ["video/mp4"],
        "minduration": 6,
        "maxduration": 30,
        "protocols": [1,2,3,5,6],
        "w": 320,
        "h": 480,
        "placement": 5,
        "linearity": 1,
        "skip": 1,
        "delivery": [1,2],
        "pos": 7,
        "companiontype": [1,2],
        "ext": {
            "placementtype": "interstitial"
        }
      },
      "instl": 1,
      "tagid": "Default",
      "displaymanager": "Chartboost-iOS-SDK",
      "displaymanagerver": "6.6.1",
      "bidfloor": 0.5,
      "bidfloorcur": "USD",
      "secure": 1
    }
  ],
  "app": {
    "id": "4fa7c657f77659a92b000111",
    "name": "Buster's Boost",
    "bundle": "com.chartboost.apollo",
    "storeurl": "https://itunes.apple.com/us/app/busters-boost/id907175713",
    "cat": ["IAB9-30"],
    "publisher": {
      "id": "4dd5173cbb93162407001111",
      "name": "Chartboost Sample Company"
    }
  },
  "device": {
    "connectiontype": 2,
    "devicetype": 1,
    "geo": {
      "city": "San Francisco",
      "country": "US",
      "region": "CA",
      "type": 2,
      "zip": "94105"
    },
    "h": 2008,
    "w": 1536,
    "ifa": "EEEE44E2-EC2C-C266-4A64-AD1CADA1D062",
    "ip": "50.174.86.6",
    "language": "en",
    "lmt": 0,
    "model": "iPad4,4",
    "os": "iOS",
    "osv": "10.0.1",
    "ua": "Mozilla/5.0 (iPad; CPU OS 10_0_1 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A403"
  },
  "user": {
    "id": "20470538-b75f-11e6-a614-6158f10b9151",
    "geo": {
      "country": "US",
      "type": 2,
      "region": "CA",
      "city": "San Francisco",
      "zip": "94105"
    }
  },
  "at": 2,
  "cur": ["USD"],
  "regs": {
    "coppa": 0
  },
  "badv": [
    "badapps.com",
    "worseapps.com"
  ],
  "bcat": ["IAB2-3"],
  "bapp": ["com.badapps.badapp"],
  "test": 0
}


// Interstitial placement: video (VAST) OR playable (MRAID)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "imp": [
    {
      "id": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
      "video": {
        "mimes": ["video/mp4"],
        "minduration": 6,
        "maxduration": 30,
        "protocols": [1,2,3,5,6],
        "w": 320,
        "h": 480,
        "placement": 5,
        "linearity": 1,
        "skip": 1,
        "delivery": [1,2],
        "pos": 7,
        "companiontype": [1,2],
        "ext": {
            "placementtype": "interstitial"
        }
      },
      "banner": {
        "api": [3],
        "w": 320,
        "h": 480,
        "wmax": 1536,
        "hmax": 2008,
        "pos": 7,
        "topframe": 1,
        "battr": [1, 2, 6, 7],
        "btype": [4],
        "ext": {
          "placementtype": "interstitial",
          "playableonly": true
        }
      },
      "instl": 1,
      "tagid": "Default",
      "displaymanager": "Chartboost-iOS-SDK",
      "displaymanagerver": "6.6.1",
      "bidfloor": 0.5,
      "bidfloorcur": "USD",
      "secure": 1
    }
  ],
  "app": {
    "id": "4fa7c657f77659a92b000111",
    "name": "Buster's Boost",
    "bundle": "com.chartboost.apollo",
    "storeurl": "https://itunes.apple.com/us/app/busters-boost/id907175713",
    "cat": ["IAB9-30"],
    "publisher": {
      "id": "4dd5173cbb93162407001111",
      "name": "Chartboost Sample Company"
    }
  },
  "device": {
    "carrier": "WIFI",
    "connectiontype": 2,
    "devicetype": 1,
    "geo": {
      "city": "San Francisco",
      "country": "US",
      "region": "CA",
      "type": 2,
      "zip": "94105"
    },
    "h": 2008,
    "w": 1536,
    "ifa": "EEEE44E2-EC2C-C266-4A64-AD1CADA1D062",
    "ip": "50.174.86.6",
    "language": "en",
    "lmt": 0,
    "model": "iPad4,4",
    "os": "iOS",
    "osv": "10.0.1",
    "ua": "Mozilla/5.0 (iPad; CPU OS 10_0_1 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A403"
  },
  "user": {
    "id": "20470538-b75f-11e6-a614-6158f10b9151",
    "geo": {
      "country": "US",
      "type": 2,
      "region": "CA",
      "city": "San Francisco",
      "zip": "94105"
    }
  },
  "at": 2,
  "cur": ["USD"],
  "regs": {
    "coppa": 0
  },
  "badv": [
    "badapps.com",
    "worseapps.com"
  ],
  "bcat": ["IAB2-3"],
  "bapp": ["com.badapps.badapp"],
  "test": 0
}

// Rewarded placement: video only (VAST)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "imp": [
    {
      "id": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
      "video": {
        "mimes": ["video/mp4"],
        "minduration": 6,
        "maxduration": 30,
        "protocols": [1,2,3,5,6],
        "w": 320,
        "h": 480,
        "placement": 5,
        "linearity": 1,
        "skip": 1,
        "delivery": [1,2],
        "pos": 7,
        "companiontype": [1,2],
        "ext": {
            "placementtype": "rewarded"
        }
      },
      "instl": 1,
      "tagid": "Default",
      "displaymanager": "Chartboost-iOS-SDK",
      "displaymanagerver": "6.6.1",
      "bidfloor": 0.5,
      "bidfloorcur": "USD",
      "secure": 1
    }
  ],
  "app": {
    "id": "4fa7c657f77659a92b000111",
    "name": "Buster's Boost",
    "bundle": "com.chartboost.apollo",
    "storeurl": "https://itunes.apple.com/us/app/busters-boost/id907175713",
    "cat": ["IAB9-30"],
    "publisher": {
      "id": "4dd5173cbb93162407001111",
      "name": "Chartboost Sample Company"
    }
  },
  "device": {
    "carrier": "WIFI",
    "connectiontype": 2,
    "devicetype": 1,
    "geo": {
      "city": "San Francisco",
      "country": "US",
      "region": "CA",
      "type": 2,
      "zip": "94105"
    },
    "h": 2008,
    "w": 1536,
    "ifa": "EEEE44E2-EC2C-C266-4A64-AD1CADA1D062",
    "ip": "50.174.86.6",
    "language": "en",
    "lmt": 0,
    "model": "iPad4,4",
    "os": "iOS",
    "osv": "10.0.1",
    "ua": "Mozilla/5.0 (iPad; CPU OS 10_0_1 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A403"
  },
  "user": {
    "id": "20470538-b75f-11e6-a614-6158f10b9151",
    "geo": {
      "country": "US",
      "type": 2,
      "region": "CA",
      "city": "San Francisco",
      "zip": "94105"
    }
  },
  "at": 2,
  "cur": ["USD"],
  "regs": {
    "coppa": 0
  },
  "badv": [
    "badapps.com",
    "worseapps.com"
  ],
  "bcat": ["IAB2-3"],
  "bapp": ["com.badapps.badapp"],
  "test": 0
}

// Rewarded placement: video (VAST) OR playable (MRAID)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "imp": [
    {
      "id": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
      "banner": {
        "api": [3],
        "w": 320,
        "h": 480,
        "wmax": 1536,
        "hmax": 2008,
        "pos": 7,
        "topframe": 1,
        "battr": [1, 2, 6, 7],
        "btype": [4],
        "ext": {
          "placementtype": "rewarded",
          "playableonly": true
        }
      },
      "video": {
        "mimes": ["video/mp4"],
        "minduration": 6,
        "maxduration": 30,
        "protocols": [1,2,3,5,6],
        "w": 320,
        "h": 480,
        "placement": 5,
        "linearity": 1,
        "skip": 1,
        "delivery": [1,2],
        "pos": 7,
        "companiontype": [1,2],
        "ext": {
            "placementtype": "rewarded"
        }
      },
      "instl": 1,
      "tagid": "Default",
      "displaymanager": "Chartboost-iOS-SDK",
      "displaymanagerver": "6.6.1",
      "bidfloor": 0.5,
      "bidfloorcur": "USD",
      "secure": 1
    }
  ],
  "app": {
    "id": "4fa7c657f77659a92b000111",
    "name": "Buster's Boost",
    "bundle": "com.chartboost.apollo",
    "storeurl": "https://itunes.apple.com/us/app/busters-boost/id907175713",
    "cat": ["IAB9-30"],
    "publisher": {
      "id": "4dd5173cbb93162407001111",
      "name": "Chartboost Sample Company"
    }
  },
  "device": {
    "carrier": "WIFI",
    "connectiontype": 2,
    "devicetype": 1,
    "geo": {
      "city": "San Francisco",
      "country": "US",
      "region": "CA",
      "type": 2,
      "zip": "94105"
    },
    "h": 2008,
    "w": 1536,
    "ifa": "EEEE44E2-EC2C-C266-4A64-AD1CADA1D062",
    "ip": "50.174.86.6",
    "language": "en",
    "lmt": 0,
    "model": "iPad4,4",
    "os": "iOS",
    "osv": "10.0.1",
    "ua": "Mozilla/5.0 (iPad; CPU OS 10_0_1 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A403"
  },
  "user": {
    "id": "20470538-b75f-11e6-a614-6158f10b9151",
    "geo": {
      "country": "US",
      "type": 2,
      "region": "CA",
      "city": "San Francisco",
      "zip": "94105"
    }
  },
  "at": 2,
  "cur": ["USD"],
  "regs": {
    "coppa": 0
  },
  "badv": [
    "badapps.com",
    "worseapps.com"
  ],
  "bcat": ["IAB2-3"],
  "bapp": ["com.badapps.badapp"],
  "test": 0
}

Chartboost bid requests are built to the Open RTB 2.3 standard. The following fields are sent by Chartboost in the bid request. Bidders must ensure that they adhere to the requirements listed. DSPs should refer to the sample bid requests provided in the JSON tab to the right for a comparison of different ad placements.

Bid Request

The BidRequest object contains the following fields:

Field Description Notes
at Auction type. Always set to 2. Chartboost Exchange only supports second-price auctions.
app App object. Details about the publisher app requesting an impression.
badv Domains of blocked companies. Array of strings. Won’t be included if no blocked domains exist.
bapp Bundle id of blocked apps. Array of strings. This is an OpenRTB 2.5 field so using it is optional. Won’t be included if no blocked apps exist.
bcat IAB categories that are blocked. Array of strings. Won’t be included if no blocked categories exist.
cur Currency. Array of strings. Always set to [ "USD" ].
device Device object. Contains information on device such as make, model, os, etc.
id A Chartboost-defined unique identifier for this bid request.
imp Impression object. At least one per bid request.
regs Object of regulatory conditions for all impressions in this bid request. Contains "coppa":0 or "coppa":1. See Section 7.1 of OpenRTB 2.3 specifications for details.
test A flag informing the DSP to treat this request as a test that won’t be billed. DSPs must confirm whether they support this flag. If not, DSPs must provide a test URL in order to integrate.
user User object. Chartboost user id and geo information.

Array of Objects: BidRequest.imp

Field Description Notes
banner Object indicating that a banner format creative is expected in the response. Videos will not be permissible in responses to requests containing this object.
bidfloor Minimum expected bid value for this request. Will always be sent and must be respected. This is set by the publisher.
bidfloorcur Always set to 'USD'.
id A Chartboost-defined unique identifier for this impression.
instl Always set to 1. Chartboost Exchange will only serve full-screen interstitial ads. DSPs must confirm that they can respect this field.
secure Always set to 1, indicating that all asset URLs must be https. DSPs must confirm that they will respect this field.
tagid A Chartboost-defined string indicating the in-game location where an ad is being requested (String).
video High-level object indicating that a video format creative following the VAST standard is expected in the response. VAST 2.0 & 3.0 are supported.

Object: BidRequest.app

Field Description Notes
bundle Bundle ID of the app. Chartboost can send iTunes Store ID instead of bundle id for iOS titles. Please let us know if you would prefer this.
cat IAB category of the app. Chartboost inventory is primarily mobile games.
id An internal Chartboost ID for the publishing app.
name Name of the publishing app as it appears in the app store. If no name is found, the name designated by the publisher in the Chartboost dashboard.
publisher An object containing 1) the internal ID of the company publishing this app, and 2) the name of the company as entered in the Chartboost dashboard.
storeurl Store URL for the app.

Object: BidRequest.device

Field Description Notes
carrier Indicates cellular carrier, if availble. Chartboost will pass carrier like “VERIZON”, “WIFI” if on a WiFi connection, or omit the field is it’s unknown.
connectiontype Indicates type of type of device connectivity. Chartboost generally only passes 0, 2, or 3 (Unknown, WiFi, or Cellular Network - Unknown Generation)
devicetype Indicates type of device. Chartboost currently only passes 1 to indicate mobile/tablet.
dpidsha1 SHA1 of Android device ID. Chartboost will include this field only if GAID is not available.
geo Object containing country, type, region, city, and ZIP code. This information is inferred based on the device IP. Note: Chartboost does not provide latitudinal & longitudinal data.
h Height of device as inferred by Chartboost SDK. Same as hmax.
ifa IDFA or GAID Identifier for Advertising for iOS devices; Google Advertising ID for Android devices.
ip Device IP.
language Content language using ISO-639-1-alpha-2 Chartboost will omit the field if it’s unknown.
lmt Limit Ad Tracking. 1 implies the advertising ID should not be used to track this device. The responsibility lies upon the DSP to adhere to this restriction. When LAT is enabled on iOS, Chartboost can only send masked device ids (000).
model Device model e.g. 'iPhone8,1'.
os Operating system e.g. 'iOS', 'Android'.
osv Version of operating system. e.g. 'iOS 9.2'
ua User-Agent (String). e.g. 'Mozilla/5.0 (iPhone; CPU OS 9_0 like Mac OS X) AppleWebKit/601.1.16 (KHTML, like Gecko) Version/8.0 Mobile/13A171a Safari/600.1.4'
w Width of device as inferred by Chartboost SDK. Same as wmax.

Object: BidRequest.user

Field Description Notes
geo Geo object containing country, type, region, city, zip. This information is inferred based on the device IP. Note: Chartboost does not provide latitudinal & longitudinal data.
id Chartboost-defined user ID (String).

Object: BidRequest.imp.banner

Field Description Notes
api Indicates whether the creative should be MRAID or VAST (Array of integers). DSPs must respect this field and only send a creative that matches this value.
battr Blocked IAB creative attributes for this ad placement. Refer to list 5.3 of the Open RTB 2.3 specifications.
btype Blocked banner types for this ad placement. Refer to list 5.2 of the Open RTB 2.3 specifications. Chartboost always sends [4] to block the iframe banner type.
ext.placementtype Type of ad being placed. Will be either rewarded or
interstitial.
ext.playableonly Indicates if banner ad format must be a playable ad. Will be either true or false. If true, set the value of BidResponse.seatbid.bid.ext.crtype in your bid response to "MRAID playable".
h Default IAB standard size unless otherwise requested during integration. e.g. 320 or 480 for Phones, 1024 or 768 for Tablets.
hmax Maximum height for the impression as inferred by Chartboost from the SDK on the device.
pos Ad position on the screen. Will always be set to 7, since all Chartboost ads are shown in full-screen interstitial format.
topframe Always set to 1. The use of iFrames in the payload is not supported or allowed.
w Default IAB standard size unless otherwise requested during integration. e.g. 320 or 480 for Phones, 1024 or 768 for Tablets.
wmax Maximum width for the impression as inferred by Chartboost from the SDK on the device.

Object: BidRequest.user.geo & BidRequest.device.geo

Field Description
city City using United Nations Code for Trade & Transport Locations (String). Always null.
country Country code using ISO-3166-1-alpha-3 (String).
region Region code using ISO-3166-2; 2-letter state code if USA (String). Always null.
type Source of location data (Int).
zip Zip or postal code (String). Always null.

Object: BidRequest.imp.video

Field Description
companiontype Indicates that only Static or HTMResource companion ad types are allowed. Chartboost currently supports both.
delivery Indicates the supported deliver method. Chartboost strongly recommends using progressive video content delivery (2).
ext.placementtype Type of ad being placed. Will be either rewarded or interstitial.
h Height of device as inferred by Chartboost SDK.
linearity Indicates if the impression is linear, nonlinear, etc. Chartboost currently supports only linear/in-stream impressions.
maxduration Maximum video ad duration, in seconds. Chartboost will always send 30.
mimes Content MIME types supported. Chartboost currently supports only video/mp4.
minduration Minimum video ad duration, in seconds.
placement Placement type for the impression. Chartboost currently supports only 5 (Interstitial/Sliding/Floater).
pos Ad position on the screen. Chartboost currently supports only 7 (Full Screen).
protocols Array of supported video bid response protocols. Will always be 1 (VAST 1.0), 2 (VAST 2.0), 3 (VAST 3.0), 5 (VAST 2.0 Wrapper), 6 (VAST 3.0 Wrapper).
skip Indicates whether the player can skip the video ad. 0 = no, 1 = yes. If a bidder sends markup/creative that is skippable, the Bid object should include the attr array with an element of 16 to indicate skippable video.
w Width of device as inferred by Chartboost SDK.

OpenRTB Bid Response Specifications

DSPs can refer to the sample bid responses provided in the JSON tab to the right.

{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "bidid": "cbrtb-512939461-320x5680.2625",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "foobar",
      "bid": [
        {
          "impid": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
          "adomain": [
            "twitter.com"
          ],
          "id": "cbrtb-512939461-320x568-9d554579-f21a-4f6f-a33e-42c41b09b206",
          "crid": "foobar:190d3bfd",
          "cid": "190d3bfd",
          "price": 15.2625,
          "iurl": "https:\/\/secure.foobar.com\/promote\/mock\/190d3bfd",
          "adid": "190d3bfd",
          "nurl": "https:\/\/lb-www2.foobar.com\/ads\/notify.php?partnerkey=cbrtb&siteid=cbrtb-512939461-320x568&adid=190d3bfd&deviceid=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062&earnings=${AUCTION_PRICE}&ip=10.58.130.151&countryCode=US&apikey=cbrtb&device=iPad&os=10.0&mach=&ni=0&appid=333903271&adGroup=Twitter_iOS_Campaign+A_US&ourprice=0.2625&adom=twitter.com&adgroupID=180589&campaignID=123160110&creativeID=ad4ee8cb&ccimpid=X96142fe8497a5eb8888888802081156&nb=1&ra=0U0..WSA.1.200O000P31100.0000000003B0U00000B0.A0&sg=&cpa=0&accountID=2165&siteaccountID=&pubappid=&its=1486583763&it=mi&inf=0&cg=CampaignA%26B-+Nerd&adType=StaticInterstitial&creativeID=ad4ee8cb&aid=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062",
          "adm": "<div id='foobarad' style='background-color:black; position:relative; width:100%; height:100%;'><a href='https:\/\/c.foobar.com\/ads\/c.php?a=cbrtb&b=cbrtb-512939461-320x568&c=190d3bfd&d=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062&ct=0&nb=1&gf=https%3A%2F%2Fcdn.foobar.com%2F88518%2FQ2_FIND_GET_testB_320x480_20161020_18_28_26.jpg&its=1486583763&f=96ebd0d524e12401190d3bfd02081156&ra=0U0..WSA.1.200O000P31100.0000000003B0U00000B0.A0&aid=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062&campaignID=123160110&adgroupID=180589&adGroup=Twitter_iOS_Campaign+A_US&campaignCode=iOS_Campaign+A&defcpa=0&defcpc=0&appid=333903271&creativeID=ad4ee8cb&adType=StaticInterstitial&countrycode=US&ccimpid=X96142fe8497a5eb8888888802081156&accountid=2165&it=mi&inf=0&cg=CampaignA%26B-+Nerd&adType=StaticInterstitial&creativeID=ad4ee8cb'><img style='position:absolute;top: 0;left: 0;bottom: 0;right: 0;margin:auto; max-width:100%; max-height:100%' src='https:\/\/cdn.foobar.com\/88518\/Q2_FIND_GET_testB_320x480_20161020_18_28_26.jpg' ><\/a><\/div>",
          "ext": {
            "imptrackers": [
              "https:\/\/lb-www2.foobar.com\/ads\/notify.php?partnerkey=cbrtb&siteid=cbrtb-512939461-320x568&adid=190d3bfd&deviceid=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062&earnings=${AUCTION_PRICE}&ip=10.58.130.151&countryCode=US&apikey=cbopen&device=iPad&os=10.0&mach=&ni=0&appid=333903271&adGroup=Twitter_iOS_Campaign+A_US&ourprice=0.2625&adom=twitter.com&adgroupID=180589&campaignID=123160110&creativeID=ad4ee8cb&ccimpid=X96142fe8497a5eb8888888802081156&nb=1&ra=0U0..WSA.1.200O000P31100.0000000003B0U00000B0.A0&sg=&cpa=0&accountID=2165&siteaccountID=&pubappid=&its=1486583763&it=mi&inf=0&cg=CampaignA%26B-+Nerd&adType=StaticInterstitial&creativeID=ad4ee8cb&aid=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062"
            ]
          }
        }
      ]
    }
  ]
}

The BidResponse object contains the following fields:

Field Description Notes
bidid Bidder-generated response ID to assist with logging/tracking.
cur Currency. Should always be set to 'USD'.
id Bidder-generated bid ID to assist with logging/tracking.
seatbid Name of the client. Required. We support multiple seats with multiple bids, but typically only see one seat and one bid in production.

BidResponse.seatbid

Field Description Notes
bid Array of objects containing details of the bid(s). Typically just one bid object.
seat ID of the client making the bid.

seatbid: bid

Field Description Notes
adid ID of a preloaded ad to be served if the bid wins.
adomain Advertiser domain for block list checking (e.g., “ford.com”). Required
adm Only supported method of sending payload. Required OpenRTB macros are supported here.
cid Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
crid Creative ID to assist with ad quality checking. Required
ext.crtype String which defines payload format. Required if bidding with a user-interactive / playable ad – value must be set to "MRAID playable"; else Optional.
ext.imptrackers Array of URLs that will be hit from device when impression is shown on the screen. Optional. OpenRTB macros are supported here.
id Bidder-generated bid ID to assist with logging/tracking. Required
impid ID of the imp object in the related bid request.
iurl URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.
nurl Notification URL to be called when auction is won. Optional. OpenRTB macros are supported here. By default, nurl is called from the device at the time impression is shown. Please let us know if you want nurl to be called from our servers at the time the auction is won instead.
price Bid price expressed as CPM. Required

Integration & Testing

After filling out our technical survey, we’ll schedule a kickoff call with you to discuss the project timeline and go over any questions. Chartboost will work with your technical team to first ensure the following:

Bid Request, Bidder URL, Bid Response & Sample Payloads

DSPs are required to share with Chartboost the following:

Analytics

Auction & Impression Tracking

Network Information

Creatives & Ad Formats

Banners

When Chartboost requests a display ad, indicated by the banner field in the bid request, we expect to receive HTML, MRAID payloads. The following MRAID APIs are supported:

All URLs must be HTTPS. Check for the imp.secure flag in the bid request. If any URLs in the payload are not HTTPS, your ads will fail to render.

Banner requests will be sent for Chartboost interstitial placements. If you have playable ads, we can also add a banner object to rewarded placement bid requests. Please see Playables section below for details on requirements.

Video

Video requests will be sent for Chartboost Video Interstitial and Rewarded Video placements by default. The placement type (“interstitial” or “rewarded”) is indicated by the video.ext.placementtype field in the bid request.

Playables

Chartboost supports playable (user interactive) ads in interstitial placements by default, and optionally in rewarded placements. If you have playable ads, we strongly recommend taking advantage of bidding on inventory in both placement types.

Please let us know if you plan to bid with playable ads!

Verifying your Creatives

Pre-Caching


By default, Chartboost does not pre-cache ad markup payloads. They are rendered in our ad placements immediately after the client calls for an ad to be shown.

Possible Flows for Rendering an Ad

Bidders Requiring Pre-Caching of Large Assets

If you require pre-caching creative assets to ensure reliable rendering, please reach out to us for a custom integration.

Bid Response for No Ad

Bidders should send a 204 No Content response for a case where no bid is made.