NAV
javascript php python

Third-Party Documentation Center

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NOTE: S2S API v1 is deprecated as of 2/1/2017. Please update to v2.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Welcome to the Chartboost third-party documentation center!

This site is divided into two sections: Chartboost S2S and Chartboost Publisher Mediation.

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

S2S Install Attribution Overview

Chartboost’s S2S Install Tracking feature lets advertisers leverage attribution data from approved third parties to 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 to our S2S endpoint and will stop using the Chartboost SDK (if applicable) for install attribution.

Requirements

Authentication

All API endpoints require authentication and use the same signature generation method. Requests must be signed and the computed signature must be placed in the X-Chartboost-Signature header.

All API requests must be made via HTTPS.

Install Postback Method: POST

<?php

const CB_ATTRIBUTION_ENDPOINT = "https://live.chartboost.com/api/v1/install.json";
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
$android_id = "f533bc6a9d9a2000";  # example legacy Android ID
$ifa = "8df6c9bf-d647-4400-bc13-7ff317ff0004";  # example iOS Identifier for Advertising
$click_id = "178660e204b0166e0364e637"; # only used if fingerprinting attribution is enabled by your server in lieu of a device identifier; optional
$claim = 1;  # indicates install is attributable, set claim = 0 if install is non-attributable / organic
$attributed_to = "Chartboost";  # optional, send another network name if attributed to other network, or Organic if organic
$is_organic = 0;  # optional, send 0 if not organic, 1 if organic

$data = json_encode(array(
  "app_id" => $app_id,
  "gaid" => $gaid,
  "uuid" => $android_id,
  "click_id" = > $click_id
  "claim" => $claim,
  "attributed_to" => $attributed_to,
  "is_organic" => $is_organic
));

$descriptor = "action:attribution\n$CB_API_SECRET\n$app_signature\n$data";
$signature = hash("sha256", $descriptor);

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


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


CB_ATTRIBUTION_ENDPOINT = 'https://live.chartboost.com/api/v1/install.json'
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
android_id = 'f533bc6a9d9a2000'  # example Legacy Android ID
ifa = '8df6c9bf-d647-4400-bc13-7ff317ff0004'  # example iOS Identifier for Advertising
click_id = '178660e204b0166e0364e637';  # only used if fingerprinting attribution is enabled by your server in lieu of a device identifier; optional
claim = 1  # indicates install is attributable, set claim=0 if install is non-attributable / organic
attributed_to = 'Chartboost'  # optional, send another network name if attributed to other network, or Organic if organic
is_organic = 0  # optional, send 0 if not organic, 1 if organic

data = json.dumps({
  'app_id': app_id,
  'gaid': gaid,
  'uuid': android_id,
  'click_id': click_id
  'claim': claim,
  'attributed_to': attributed_to,
  'is_organic': is_organic
})

descriptor_template = 'action:attribution\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
}

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

var data, descriptor, signature, options, req;

const CB_API_TOKEN = "{{your_api_token}}"; 
const CB_API_SECRET = "{{your_api_secret}}"; 
const CB_ATTRIBUTION_HOST = "live.chartboost.com";
const CB_ATTRIBUTION_PATH = "/api/v1/install.json";
const CB_ATTRIBUTION_PORT = "443";

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-7ff317ff0003";  // example Google Advertising ID
var android_id = "f533bc6a9d9a2000";  // example Legacy Android ID
var ifa = "61109b4c-0f16-4fbc-82ec-5475313af000";  // example iOS Identifier for Advertising
var click_id = "178660e204b0166e0364e637";  // only used if fingerprinting attribution is enabled by your server in lieu of a device identifier; optional
var claim = 1; // indicates install is attributable, set claim = 0 if install is non-attributable / organic
var attributed_to = "Chartboost"; // optional, send another network name if attributed to other network, or Organic if organic
var is_organic = 0; // optional, send 0 if not organic, 1 if organic

function sendInstall(callback) {
    data = JSON.stringify({
        "app_id": app_id,
        "ifa": ifa,
        "click_id": click_id
        "claim": claim,
        "attributed_to": attributed_to,
        "organic": is_organic
    });

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

    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,
            '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 it!
sendInstall( function() {
    console.log(data);
  } 
);

Sample Response

{"message":"Install request received!","status":200}

This endpoint can receive attributed and non-attributed app installs, as well as app opens, from an install attribution platform. Installs will be processed, stored, and used in reporting.

HTTPS Request

POST https://live.chartboost.com/api/v1/install.json

Authentication

To authenticate with the API endpoint, two special headers are required on every request: X-Chartboost-Token and X-Chartboost-Signature. The X-Chartboost-Token is your static S2S API Token. The X-Chartboost-Signature is created by taking the SHA-256 hash of the following string template:

Computed signature: "action:attribution\n{{CB_API_SECRET}}\n{{Chartboost app signature}}\n{{JSON body}}"

Note that anything contained within double curly brackets is a macro that is meant to be replaced by your software.

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 on the right.

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:

Headers

Each request must contain the following headers:

Header Value
Content-Type application/json
X-Chartboost-Token {{CB_API_TOKEN}}
X-Chartboost-Signature {{computed_signature}}

Request Parameters

Each request must use these parameters:

Name Required Type Description
app_id true string Chartboost app ID (found in the Chartboost dashboard)
claim true int 1 if Chartboost can claim the install, 0 otherwise
gaid true* string Google advertising identifier
ifa true string Apple identifier for advertising
uuid false* string android_id if Android
click_id true string if available, else send empty string as value
organic false int 1 if organic install, 0 if attributed to a network
attributed_to false string Name of network that received the attribution
timestamp false int UNIX timestamp in seconds

Install Postback Method: GET

var crypto = require('crypto');
var requestify = require('requestify');
var urlEncodeJson = require('urlcode-json');

var params, params_url_encoded, uri, url, descriptor, signature;

var CB_API_TOKEN = "{{your_api_token}}"; 
var CB_API_SECRET = "{{your_api_secret}}"; 
var CB_ATTRIBUTION_HOST = "https://live.chartboost.com";
var CB_ATTRIBUTION_PATH = "/api/v1/install.json";
var CB_ATTRIBUTION_PORT = "443";

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-7ff317ff0003";  // example Google Advertising ID
var android_id = "f533bc6a9d9a2000";  // example Legacy Android ID
var ifa = "61109b4c-0f16-4fbc-82ec-5475313af000";  // example iOS Identifier for Advertising
var click_id = "178660e204b0166e0364e637";  // only used if fingerprinting attribution is enabled by your server in lieu of a device identifier; optional
var claim = 1; // indicates install is attributable, set claim = 0 if install is non-attributable / organic
var attributed_to = "Chartboost"; // optional, send another network name if attributed to other network, or Organic if organic
var is_organic = 0; // optional, send 0 if not organic, 1 if organic

function sendInstall(callback) {

    params = {
        "app_id": app_id,
        "ifa": ifa,
        "click_id": click_id,
        "claim": claim,
        "attributed_to": attributed_to,
        "is_organic": is_organic
    };

    params_url_encoded = urlEncodeJson.encode(params);
    url = CB_ATTRIBUTION_HOST + CB_ATTRIBUTION_PATH;
    uri = CB_ATTRIBUTION_PATH + "?" + params_url_encoded;

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

    console.log("  Request parameters are: " + JSON.stringify(params));
    console.log("  Computed Signature is: " + signature);

    requestify.request(url, {
        method: 'GET',
        params: params,
        headers: {
            'X-Chartboost-Token': CB_API_TOKEN,
            'X-Chartboost-Signature': signature
        },      
    }).then(function(response) {
        console.log("  Status Code: " + response.getCode());
        console.log("  Response Body: " + response.body);
    });
    callback();
}

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

Sample Response

{"message":"Install request received!","status":200}

This endpoint can receive attributed and non-attributed app installs, as well as app opens, from an install attribution platform. Installs will be processed, stored, and used in reporting.

HTTPS Request

GET https://live.chartboost.com/api/v1/install.json

Authentication

To authenticate with the API endpoint, two special headers are required on every request: X-Chartboost-Token and X-Chartboost-Signature. The X-Chartboost-Token is your static S2S API Token. The X-Chartboost-Signature is created by taking the SHA-256 hash of the following string template:

Computed signature: "action:attribution\n{{CB_API_SECRET}}\n{{Chartboost app signature}}\n{{URI}}"

Note that anything contained within double curly brackets is a macro that is meant to be replaced by your software.

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 on the right. {{URI}} refers to everything past https://fqdn, e.g. /api/v1/install.json?app_id=538e68a3c2611441d13e3e15&ifa=60009b4c-0f16-4fbc-82ec-5475313af000&claim=1&attributed_to=Chartboost&is_organic=0

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:

Headers

Each request must contain the following headers:

Header Value
X-Chartboost-Token {{CB_API_TOKEN}}
X-Chartboost-Signature {{computed_signature}}

Request Parameters

Each request must use these parameters:

Name Required Type Description
app_id true string Chartboost app ID (found in the Chartboost dashboard)
claim true int 1 if Chartboost can claim the install, 0 otherwise
gaid true* string Google advertising identifier
ifa true string Apple identifier for advertising
uuid false* string android_id if Android
click_id true string if available, else send empty string as value
organic false int 1 if organic install, 0 if attributed to a network
attributed_to false string Name of network that received the attribution
timestamp false int UNIX timestamp in seconds

Example GET Request

GET https://live.chartboost.com/api/v1/install.json?app_id=538e68a3c2611441d13e3e15&ifa=60009b4c-0f16-4fbc-82ec-5475313af000&click_id=178660e204b0166e0364e637&claim=1&attributed_to=Chartboost&is_organic=0

Post-Install Events

For a more complete analysis of player level data across platforms or networks, Chartboost customers can configure third-party tracking services to send their event/level data to Chartboost. After the integration, Chartboost customers can then view the third-party data in the Chartboost dashboard.

Third-party tracking services can use the instructions on this page to build their initial event tracking integration. Chartboost customers using level tracking should refer to these customer-facing instructions.

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.

For additional developer-facing information about PIA, visit our Help Site.

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,
    "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,
    '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, 
        "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 section below

In-app purchase details

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.

Custom events

<?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,
    "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,
    '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, 
        "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 event tracking integration works by sending player event/level data – tutorial completed, for example – from a third party tracking service to Chartboost via S2S integration in the form of distinct Event Fields.

Custom Event

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