S2S API v2

S2S Install Attribution Overview 🔗

Chartboost’s S2S Install Tracking program allows advertisers to use attribution data from approved MMPs 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 🔗

• 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. 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
• Python
• Javascript

• <?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:

Request Parameters 🔗

Each request must contain the following parameters:

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}

• Note: parameter values can be left blank OR omitted if there is no value, e.g. https://live.chartboost.com/api/v2/attributed_install?token={{your_api_token}}&click_id=&completed_view_id=12345

Method: POST 🔗

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

Opens (Bootups) 🔗

Each time a device (either attributed or 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.

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 (e.g. suspected fraud rejections).

• PHP
• Python
• Javascript

• <?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:

Request Parameters 🔗

Each request must use these parameters:

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}&gaid={device Android Advertising ID, GAID or Amazon Fire Advertising 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

In-app Purchase Events 🔗

For a more complete analysis of campaign performance as well as campaign optimization, Chartboost advertisers can configure MMPs to send their in-app purchase event data to Chartboost. MMPs can use the instructions on this page to build their initial in-app purchase tracking integration.

Overview 🔗

The Post-Install Analytics (PIA) integration lets Chartboost advertisers share IAP data for post-campaign analysis and optimization – we consider payer %, ARPU, purchase counts, ARPPU, ROAS, and more. Setting up postbacks for this data is strongly recommended. Any other custom in-app events, for example Tutorial Completion, Player Registration, etc., are not supported.

• PHP
• Python
• Javascript

• <?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);
      }
  );
  

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.

X-Chartboost-Signature: sha256("action:pia\n{{CB_API_SECRET}}\n{{app_signature}}\n{{JSON body}}")

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 request header below.

Headers 🔗

Request Parameters 🔗

IAP object requirements 🔗

Errors 🔗

Chartboost APIs use the following error codes:

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 documentation. Partners should submit a request to add documentation there for your integration.