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. Including both click_id and completed_view_id in the same request is valid, but at least one is required. If both are included, the click_id takes precedence.

For click-through attributions, you must enforce a minimum 7-day attribution window. Chartboost will validate clicks for attribution up to 21 days.

For view-through attributions, there is no minimum attribution window. Chartboost will validate completed views for attribution up to 7 days.

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", required for view-through attributions

$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", required for view-through attributions

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)
// Example of an attributed install postback, POST request
var https = require('https');
var crypto = require('crypto');

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

var click_id = "{{click id}}";  // e.g. "178660e204b0166e0364e637"
var completed_view_id = "{{completed view id}}";  // e.g. "178660e204b0166e0364e638, required for view-through attributions

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

request_json['token']    = CB_API_TOKEN;
request_json['click_id'] = click_id;
request_json['completed_view_id'] = completed_view_id;

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 a public S2S API token unique to your platform.

Headers

Each request must contain the following headers:

Header Value
Content-Type application/json

Request Parameters

Each request must contain the following parameters:

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

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}

Method: POST

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

See code examples of POST JSON request bodies to the right.

Opens (Bootups)

Each time a device (both attributed and non-attributed/organic) launches the app, a postback should be sent to this endpoint. Chartboost uses this data to track player retention as well as for negative-targeting of 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 advertiser 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 app open (aka bootups or launches) postbacks. NOTE: This endpoint should also be used for any rejected attributed installs (due to suspected fraud rejection).

<?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}}";
$android_id          = "{{Android ID}}";
$click_id            = "{{Click ID}};
$completed_view_id   = "{{Completed View ID}};
$tracking_id         = "{{tracking URL identifier}}";
$version             = "{{app bundle version}}";
$rejected_reason     = "{{attributed install rejection reason}}";
$rejected_value      = "{{attributed install rejection value}}"

$data = json_encode(array(
  "token"             => CB_API_TOKEN,
  "app_id"            => $app_id,
  "idfa"              => $idfa,
  "gaid"              => $gaid,
  "uuid"              => $android_id,
  "click_id"          => $click_id,
  "completed_view_id" => $completed_view_id
  "tracking_id"       => $tracking_id,
  "version"           => $version,
  "rejected_reason"   => $rejected_reason,
  "rejected_value"    => $rejected_value
));


$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}}'
click_id          = '{{Click ID}}'
completed_view_id = '{{Completed View ID}}
tracking_id       = '{{tracking URL identifier}}'
version           = '{{app bundle version}}'
rejected_reason   = '{{attributed install rejection reason}}'
rejected_value    = '{{attributed install rejection value}}'

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

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

requests.post(CB_ATTRIBUTION_ENDPOINT, data=data, headers=headers)
// Example of an open postback, POST request
var https = require('https');
var crypto = require('crypto');

var data, 
    options, 
    req;

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}}",
    click_id           = "{{Click ID}}",
    completed_view_id  = "{{Completed View ID}}"
    tracking_id        = "{{tracking URL identifier}}", 
    version            = "{{app bundle version}}";
    rejected_reason    = "{{attributed install rejection reason}}"
    rejected_value     = "{{attributed install rejection value}}";

var request_json = {};

request_json['app_id'] = app_id;
request_json['idfa'] = idfa;
request_json['gaid'] = gaid;
request_json['uuid'] = uuid;
request_json['click_id'] = click_id;
request_json['completed_view_id'] = completed_view_id;
request_json['tracking_id'] = tracking_id;
request_json['version'] = version;
request_json['rejected_reason'] = rejected_reason;
request_json['rejected_value'] = rejected_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":"Bootup 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 for iOS app
gaid true* string Device Google Advertising Identifier for Google Play app
uuid true* string Device Android Identifier for Amazon app. Recommended to send for Google Play apps as well, as a fallback in case GAID in unavailable.
click_id false* string Click ID if available. Required for rejected installs.
completed_view_id false* string Completed View ID if available. Required for rejected installs.
tracking_id false string A value used to verify the correct tracking URL is in use for the app, used for automated S2S approval of an app.
version false string The app’s package version, used for automated S2S approval of the app.
rejected_reason false string For a rejected install, the reason code for the rejection.
rejected_value false string For a rejected install, metadata associated with the reason code.

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}&rejected_reason={REJECTED_REASON}&rejected_value={REJECTED_VALUE}

Android:

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

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}&rejected_reason={REJECTED_REASON}&rejected_value={REJECTED_VALUE}

Method: POST

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

See code examples of POST requests to the right.

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!
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: Display only (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,
        "allowscustomclosebutton": 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": "USA",
      "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,
    "make": "Apple",
    "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": "USA",
      "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"],
  "tmax": 300,
  "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],
      "companionad": [{
        "btype": [4],
        "battr": [1, 2, 6, 7],
        "pos": 7,
        "h": 320,
        "w": 480,
        "id": "1"
      }],
      "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": "USA",
      "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,
    "make": "Apple",
    "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": "USA",
      "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"],
  "tmax": 300,
  "test": 0
}


// Interstitial placement: Video (VAST) OR Display (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],
      "companionad": [{
        "btype": [4],
        "battr": [1, 2, 6, 7],
        "pos": 7,
        "h": 320,
        "w": 480,
        "id": "1"
      }],
      "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": false,
        "allowscustomclosebutton": 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": "USA",
      "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,
    "make": "Apple",
    "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": "USA",
      "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"],
  "tmax": 300,
  "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": 0,
      "delivery": [1, 2],
      "pos": 7,
      "companiontype": [1, 2],
      "companionad": [{
        "btype": [4],
        "battr": [1, 2, 6, 7],
        "pos": 7,
        "h": 320,
        "w": 480,
        "id": "1"
      }],
      "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": "USA",
      "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,
    "make": "Apple",
    "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": "USA",
      "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"],
  "tmax": 300,
  "test": 0
}

// Rewarded placement: Video (VAST) OR Display User-interactive (MRAID playable only)
{
  "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,
        "allowscustomclosebutton": false
      }
    },
    "video": {
      "mimes": ["video/mp4"],
      "minduration": 6,
      "maxduration": 30,
      "protocols": [1, 2, 3, 5, 6],
      "w": 320,
      "h": 480,
      "placement": 5,
      "linearity": 1,
      "skip": 0,
      "delivery": [1, 2],
      "pos": 7,
      "companiontype": [1, 2],
      "companionad": [{
        "btype": [4],
        "battr": [1, 2, 6, 7],
        "pos": 7,
        "h": 320,
        "w": 480,
        "id": "1"
      }],
      "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": "USA",
      "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,
    "make": "Apple",
    "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": "USA",
      "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"],
  "tmax": 300,
  "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 placement types and creative types.

Bid Request

The BidRequest parent 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.
tmax Maximum time in milliseconds to submit a bid to avoid timeout. Default value is 250 or 300.
user User object. Chartboost user id and geo information.

BidRequest Object: 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.

BidRequest Object: 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.
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).
make Device make e.g. 'Apple'. Note: This only applies to iOS bid requests.
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.

BidRequest Object: 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).

BidRequest Array[Object]: imp

Field Description Notes
banner Object indicating that a banner format creative is expected in the response.
bidfloor Minimum expected bid value for this request. Will always be sent. Bids below this floor will not participate in the auction.
bidfloorcur Always set to 'USD'.
ext Object supporting various custom fields, such as whether the impression viewability will be measured by Moat.
id A Chartboost-defined unique identifier for this impression. Your bid response’s seatbid.bid.impid should match this value.
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). Publishers make use of locations in their apps for customizing business logic on the Chartboost network. Partners often find it valuable to consume and try to optimize on this data.
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.

BidRequest Object: imp.banner

Field Description Notes
api Indicates supported MRAID versions (Array of integers). Chartboost fully supports MRAID-1 but has limited support for MRAID-2 features. We will only send [3] in this field. Please see the Creatives & Ad Formats section below for more details.
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.allowscustomclose Indicates whether MRAID custom close buttons are allowed in the ad markup. Will be either true or false.
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.

BidRequest Object: imp.video

Field Description Notes
companionad Array of Banner objects defining companion ad specs. Please refer to BidRequest Object: imp.video.companionad for more details.
companiontype Indicates that only Static or HTMResource companion ad types are allowed. Chartboost currently supports both.
delivery Indicates the supported delivery method. Chartboost strongly recommends using progressive video content delivery (2).
ext.placementtype Type of ad being placed. Will be either rewarded or interstitial.
h Default IAB standard size unless otherwise requested during integration.
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 only supports video/mp4.
minduration Minimum video ad duration in seconds. Current default is 6.
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 Default IAB standard size unless otherwise requested during integration.

BidRequest Object: imp.video.companionad

Field Description Notes
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.
battr Blocked IAB creative attributes for this ad placement. Refer to list 5.3 of the Open RTB 2.3 specifications.
pos Ad position on the screen. Will always be set to 7, since all Chartboost ads are shown in full-screen interstitial format.
h Default IAB standard size unless otherwise requested during integration. e.g. 320 or 480 for Phones, 1024 or 768 for Tablets.
w Default IAB standard size unless otherwise requested during integration. e.g. 320 or 480 for Phones, 1024 or 768 for Tablets.
id Unique identifier for this banner object. Will always be set to 1

BidRequest Object: user.geo / device.geo

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

OpenRTB Bid Response Specifications

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

// Display ad response(MRAID)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "bidid": "cbrtb-512939461-320x5680.2625",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "foobar",
      "bid": [
        {
          "impid": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
          "adomain": [
            "foobar.com"
          ],
          "attr": [13],
          "bundle": "com.foobar.game",
          "id": "cbrtb-512939461-320x568-9d554579-f21a-4f6f-a33e-42c41b09b206",
          "crid": "foobar:190d3bfd",
          "cid": "190d3bfd",
          "price": 15.2625,
          "adid": "190d3bfd",
          "burl": "https:\/\/lb-www2.foobar.com\/ads\/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}",
          "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?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}"
            ],
            "crtype": "MRAID playable"
          }
        }
      ]
    }
  ]
}

// Video ad response(VAST)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "bidid": "cbrtb-512939461-320x5680.2625",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "foobar",
      "bid": [
        {
          "impid": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
          "adomain": [
            "foobar.com"
          ],
          "bundle": "com.foobar.game",
          "id": "cbrtb-512939461-320x568-9d554579-f21a-4f6f-a33e-42c41b09b206",
          "crid": "foobar:190d3bfd",
          "cid": "190d3bfd",
          "price": 15.2625,
          "adid": "190d3bfd",
          "burl": "https:\/\/lb-www2.foobar.com\/ads\/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}",
          "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<VAST version=\"3.0\">\n<Ad id=\"idleheros-gp-001\">\n    <InLine>\n        <AdSystem>Chartboost</AdSystem>\n<Error></Error>\n<AdTitle>idleheros-gp-001</AdTitle>\n\n<Impression><![CDATA[https://testbid.chartboost.com/impression?ssp=cbbidder&creative_id=7&model_id=SM-N900T&cpi_price=10.0&exchange=chartboost&impression_id=05f2322fee88b9bf6892e6257bfabea83939b4c4&cpm_price=5.95&ip_address=73.84.99.99&app_bundle=com.foo.bar&city=West Palm Beach&country=USA&region=FL&cpm_bid=60.0&ssp_fields=%7B%22ad_group%22%3A%2232%22%7D&model=SM-N900T&identifier=7c0ffa99-9238-459e-82ff-9465634bb8a1&os=5.0]]></Impression>\n\n<Creatives>\n\n            <Creative>\n\n<Linear>\n<Duration>00:00:29</Duration>\n<MediaFiles>\n<MediaFile bitrate=\"906\" delivery=\"progressive\" height=\"320\" maintainAspectRatio=\"true\" scalable=\"true\" type=\"video/mp4\" width=\"568\"><![CDATA[http://v.chartboost.com/videoads/5a2863cf55fbf70b8e3d35d0_568-1512596432.mp4]]></MediaFile>\n</MediaFiles>\n<VideoClicks>\n<ClickThrough><![CDATA[https://testbid.chartboost.com/click?ssp=cbbidder&creative_id=7&model_id=SM-N900T&cpi_price=10.0&exchange=chartboost&impression_id=05f2322fee88b9bf6892e6257bfabea83939b4c4&cpm_price=5.95&ip_address=73.84.99.99&app_bundle=com.foo.bar&city=West Palm Beach&country=USA&region=FL&cpm_bid=60.0&ssp_fields=%7B%22ad_group%22%3A%2232%22%7D&model=SM-N900T&identifier=7c0ffa99-9238-459e-82ff-9465634bb8a1&os=5.0]]></ClickThrough>\n</VideoClicks>\n               </Linear>\n\n</Creative>\n\n<Creative>\n\n<CompanionAds>\n<Companion assetHeight=\"473\" assetWidth=\"841\" height=\"473\" width=\"841\">\n<StaticResource creativeType=\"image/jpeg\"><![CDATA[https://a.chartboost.com/creatives/582e0b9ff6cd451685c344cc/3a079f4abd4b649aea509a81ebd3972992b3d18b.jpeg]]></StaticResource>\n<CompanionClickThrough><![CDATA[https://testbid.chartboost.com/click?ssp=cbbidder&creative_id=7&model_id=SM-N900T&cpi_price=10.0&exchange=chartboost&impression_id=05f2322fee88b9bf6892e6257bfabea83939b4c4&cpm_price=5.95&ip_address=73.84.99.99&app_bundle=com.foo.bar&city=West Palm Beach&country=USA&region=FL&cpm_bid=60.0&ssp_fields=%7B%22ad_group%22%3A%2232%22%7D&model=SM-N900T&identifier=7c0ffa99-9238-459e-82ff-9465634bb8a1&os=5.0]]></CompanionClickThrough>\n</Companion>\n</CompanionAds>\n                \n</Creative>\n\n</Creatives>\n</InLine>\n</Ad>\n</VAST>",
          "ext": {
            "imptrackers": [
              "https:\/\/lb-www2.foobar.com\/ads\/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}"
            ]
          }
        }
      ]
    }
  ]
}

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 Array of objects containing seat & bid information. Required. We support only one bid per bid response.

BidResponse.seatbid

Field Description Notes
bid Array of bid objects containing details of the bid. Should contain a single bid object.
seat Name of the client making the bid.

seatbid: bid

Field Description Notes
adid ID of a preloaded ad to be served if the bid wins. Optional
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.
attr Creative attributes of the returned ad. Optional* For User-Interactive ads, this field is required and the value should be [13].
burl Notification URL to be called from device once impression is shown. Required OpenRTB macros are supported here. Either burl, nurl, or ext.imptrackers must be provided for impression tracking.
bundle Bundle id (preferred) or iTunes Store id of an advertised app. Optional If your advertisement is for a Google Play Store or iTunes Store app, this field is required.
cid Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. Optional
crid Creative ID to assist with ad quality checking. Required
ext.crtype String which defines payload format. Required. If bidding with a User-Interactive ad this value must be set to "MRAID playable" or the bid response will be rejected; else set to one of the following: "VAST 1.0", "VAST 2.0", "VAST 3.0", "MRAID 1.0", "MRAID 2.0".
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 Must match the imp.id from the auction’s bid request. Required
iurl URL to an image that is representative of the content of the campaign for ad quality/safety checking. Optional
nurl Notification URL to be called from device once impression is shown. Required OpenRTB macros are supported here. Either burl, nurl, or ext.imptrackers must be provided for impression tracking.
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:

Analytics

Inventory Snapshot: Chartboost will provide DSPs with a Metamarkets dashboard invitation that shows total daily impressions and spend on the Chartboost Exchange, which can be segmented by bundle/store id, publisher company, platform (iOS or Android), country, device model, and placement type. * Note: Metamarkets data is processed apart from our internal data and provided for estimate purposes only. It should be a reliable & accurate reflection of our internal data, but minor discrepancies may exist. Billing is based on data collected and stored by Chartboost directly.

Auction & Impression Tracking

Network Information

Bid Response for No Ad

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

Moat Viewability Measurement

Chartboost introduced support Moat Viewability Measurement in March 2018 with version 7.1.0 of the Chartboost SDK. We can pass an indication that an impression’s viewability will be measured by the Moat SDK on each bid request as an imp.ext field.

The name of the field and the value to be sent under imp.ext is customizable. For example, if you wish you receive this as imp.ext.moat_sdk: 1 or imp.ext.viewability:["moat"], please let us know your requirement and we will enable this for you.

<Extensions>
  <Extension>
    <AdVerifications>
      <Verification vendor=\"Moat\">
        <ViewableImpression id=\"zMoatBuyerId1=${BUYER_ID_1}zMoatBuyerId2=${BUYER_ID_2}\">
          <![CDATA[https://px.moatads.com/pixel.gif?moatPartnerId=${MOAT_PARTNER_ID}&moatPartnerKey=${MOAT_PARTNER_KEY}&moatNode=true]]>
        </ViewableImpression>
      </Verification>
    </AdVerifications>
  </Extension>
</Extensions>

Moat VAST Extension

Chartboost also supports Moat VAST Extensions tags. See the VAST XML example to the right for implementation details. Moat should provide you with the values to use for ${MOAT_PARTNER_ID} and ${MOAT_PARTNER_KEY}.

Creatives & Ad Formats

Display

When Chartboost requests a display ad, indicated by the banner field in the bid request, we expect to receive HTML ad markup. Markup can include javascript tags that call mraid methods (mraid is provided as apart of the global namespace). We fully support MRAID 1.0, and have limited support for some MRAID 2.0 methods. A full list of supported methods is detailed below.

All URLs in ad markup 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.

If you have User-Interactive (playable ads), please see the Playables section below for details on additional requirements.

The following MRAID methods are supported:

The following MRAID properties are available:

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 User-interactive (playable) ads in both Interstitial and Rewarded placements by default. If you have playable ads, we strongly recommend taking advantage by 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. As such it is strongly recommended to make use of geo-optimized CDNs for hosting your ad markup assets.

Possible Flows for Rendering an Ad