## Requirements
- Click (and Completed View, if applicable set up by advertiser) event notifications are sent from our servers via HTTPS requests to your tracking URLs via [Chartboost Callbacks](/en/advertising/callbacks/setting-up-callbacks/). Users are sent directly to the app store upon clicking an ad, not to the tracking URL. The server sends the request to the tracking URL on behalf of the user (via Callbacks). An `X-Forwarded-For: {IP_ADDRESS}` header is included in the request which can be used to identify the IP of the client. Additionally, if needed, we can replace the User-Agent header with the device's User-Agent, instead of the default `User-Agent: Chartboost-Callbacks` value.
- Your tracking URL may redirect to subsequent endpoints. If you do redirect to secondary endpoints, you must use 302 HTTP redirects, and the Location URI in the 302 redirect header *must be URL-encoded*.
- Advertisers leveraging Chartboost S2S Install Tracking will need to set up an attributed install postback using our global postback URL. App open (aka bootup) postbacks should also be set up to enable tracking of user retention and to exclude non-attributed users from network campaign targeting (negative targeting).
- All requests must be made via HTTPS (both tracking callbacks and install/open postbacks).
## Attributed Installs
Installs attributed via clicks (and/or 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 accepted, 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}
<?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}
<?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
fire_adid = '8df6c9bf-d647-4400-bc13-7ff317f046f5' # example FireOS Advertising Identifier
uuid = '8df6c9bf0' # example legacy Android ID
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,
# 'fire_adid: fire_adid,
# 'uuid': uuid,
'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 Identifier
var ifa = "8DF6C9BF-D647-4400-BC13-7FF317F046F4"; // example iOS Identifier for Advertising
var fire_adid = "8df6c9bf-d647-4400-bc13-7ff317f046f5"; // exampple FireOS Advertising Identifier
var uuid = "8df6c9bf0"; // example legacy Android ID
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,
// "uuid": uuid,
// "fire_adid": fire_adid,
"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);
}
);
"USD".
localized_title | false | string | Localized name of the purchased item.
localized_description | false | string | Localized description of the purchased item.
## 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 accommodate temporary server outages (recommended: 24 hour TTL).
### Client Setup
- Advertisers may visit the Chartboost [S2S PIA integration for in-app purchases](/en/advertising/s2stracking/in-app-purchase-tracking/) documentation. Partners should submit a request to add documentation there for your integration.