S2S API v2


title: β€œ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
    
    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}

  • 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
    
    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.
match_type false string Represents the method of attribution determination (e.g. fingerprinting, device ID, google referrer, etc.)

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

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
    
    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 πŸ”—

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)
ifa true* string Apple identifier for advertising, required if iTunes Store app
gaid true* string Google advertising identifier, required if Google Play Store app
fire_adid true* string FireOS advertising identifier, required if Amazon Store app and available
uuid false string Legacy Android ID, only required if gaid is unavailable, such as with Amazon devices
iap true object JSON of in-app purchase details; see IAP object requirements section below
click_id false string Chartboost Click ID if available
completed_view_id false string Chartboost Completed View ID if available
match_type false string Represents the method of attribution determination (e.g. fingerprinting, device ID, google referrer, etc.)

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 code is unavailable, set to "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 πŸ”—