Advertising

Analytics Methods

Campaign Analytics 🔗

The campaign analytics endpoint provides detailed reports that can be grouped by either app or creative. Be advised that when specifying a groupBy field, a job ID will be returned by the Queued Analytics system, as detailed in the Chartboost API Overview.

HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/campaign
Example Request https://analytics.chartboost.com/v3/metrics/campaign?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}

Parameter 🔗

Parameter Request Type Required? Default Description
aggregate String Optional Daily Aggregate the results over time (daily, weekly, monthly)
campaignId String Optional N/A Campaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role)
campaignType String Optional network network,cross_promo
dateMin String Required N/A The minimum date (YYYY-MM-DD)
dateMax String Required N/A The maximum date (YYYY-MM-DD)
groupBy String Optional None One of the following: country, app, app, creative, target_creative, date, campaign, campaign_target, campaign_type
platform String Optional All Filter by specific platforms (iOS, Google Play, Amazon)
role String Optional Both advertiser

Response Fields 🔗

Parameter Description Returned for…
adTypeId 1=interstitial, 2=more_apps, 3=in_play, 4=rewarded_video, 5=video_interstitial, 10=banner, 11=native Everyone
app App name Everyone
campaign Campaign name Everyone
campaignId Campaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role) Everyone
campaignTarget Campaign target name (only returned when grouping by campaign_target Advertisers
campaignSubType user_acquisition Everyone
clicksDelivered Clicks delivered Publishers
clicksReceived Clicks received Advertisers
cpcvEarned Ratio of money earned from completed video views to completed video views Advertisers
cpcvSpent Ratio of money spent on completed video views to the number of completed video views Publishers
creative Advertised creative name (only returned when grouping by creative) Advertisers
ctrDelivered Click through rate for delivered impressions Publishers
ctrReceived Click through rate for received impressions Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1,000 impressions Publishers
ecpmSpent Cost per 1,000 impressions Advertisers
impressionsDelivered Impressions delivered by the publisher Publishers
impressionsReceived Impressions received by the advertiser Advertisers
installDelivered Installs delivered Publishers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
InstallReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
videoCompletedDelivered Completed video views delivered Publishers
videoCompletedReceived Completed video views received Advertisers

App analytics 🔗

The app analytics endpoint provides detailed reports that can be grouped by app, ad type, or ad location.

HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/app
Example Request https://analytics.chartboost.com/v3/metrics/app?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}

Parameters 🔗

Parameter Request type Required? Description Default
aggregate String Optional Aggregate the results over time (daily, weekly, monthly) Daily
appId String Optional One or more (comma-separated) app IDs All
dateMax String Required The maximum date (YYYY-MM-DD) N/A
dateMin String Required The minimum date (YYYY-MM-DD) N/A
groupBy String Optional One of the following: One of the following: app, ad_type, app, date, ad_location (Publishers only), platform, campaign_type, country None
platform String Optional Any of the following: iOS, Google Play, Amazon All
role String Optional advertiser or publisher Both

Response Fields 🔗

Parameter Description Returned for…
ad_type Creative ad type Learn more about ad types Everyone, only when groupBy=ad_type,app
allInstalls Number of total installs accrued regardless of source (Chartboost or otherwise) Everyone
app App name Everyone
appBundleId No longer sent; user will see Deprecated in reports Everyone
appId Chartboost app ID Everyone
bootups Number of times a user launches your app on a device Everyone
campaignType network, cross_promo Everyone, only when groupBy=campaignType
clicksDelivered Clicks delivered Publishers
clicksReceived Clicks received Advertisers
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
ctrlDelivered Clickthrough rate for delivered impressions Publishers
ctrReceived Clickthrough rate for received impressions Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1,000 impressions Publishers
ecpmSpent Cost per 1,000 impressions Advertisers
eventLocation The Chartboost named location of the ad being published in the app. Advertisers will see default in the response field. Everyone
impressionsDelivered Impressions delivered by the publisher Publishers
impressionsReceived Impressions received by the advertiser Advertisers
installDelivered Installs delivered Publishers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
installReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
platform iOS, Google Play, or Amazon Everyone
uniques Number of unique devices that booted up the app Everyone
videoCompletedDelivered Completed video views delivered Publishers
VideoCompletedReceived Completed video views received Advertisers

Export installs 🔗

The export installs endpoint provides a full list of all installs received and/or provided. Please note that this endpoint will always return a Job ID from the Queued Analytics system, as detailed in the Chartboost API Overview.

HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/install
Example Request https://analytics.chartboost.com/v3/metrics/install?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}

Parameters 🔗

Parameter Request type Required? Description Default
campaignIds String Optional One or more (comma-separated) campaign IDs All campaigns
campaignType String Optional network, cross_promo All
dateMax String Required The maximum date (YYYY-MM-DD) N/A
dateMin String Required The minimum date (YYYY-MM-DD) N/A
platform String Optional Any of the following: iOS, Google Play, Amazon All
role String Optional advertiser or publisher Both

Response Fields 🔗

Parameter Description Returned for…
Ad Type Creative ad type Learn more about ad types Everyone
Click Timestamp Date & time (DD-MM-YYYY HH:MM:SS) Everyone
Cost Type Advertising bid type Learn more about bid types Everyone
Cost Value Advertising bid amount Everyone
Country Two-letter country code of device Everyone
Date Date & time (DD-MM-YYYY HH:MM:SS) Everyone
From App Bundle Publishing app bundle ID Everyone
From App ID Publishing app ID Everyone
From App Name Publishing app name Everyone
From Campaign ID Publishing campaign ID Publishers
From Campaign Name Publishing campaign name Publishers
From Campaign Type network, cross_promo Publishers
GAID Google Advertising ID Everyone (Publisher only if Behavioral Targeting is disabled)
IFA iOS Identifier for Advertisers (if iOS 10 Limit Ad Tracking is disabled) Everyone (Publisher only if Behavioral Targeting is disabled)
MAC MAC address (Deprecated) N/A
Model Device model Everyone
OS Device operating system Everyone
To App Bundle Advertising app bundle ID Everyone
To App ID Advertising app ID Everyone
To App Name Advertising app name Everyone
To Campaign ID Advertising campaign ID Advertisers
To Campaign Name Advertising campaign name Advertisers
To Campaign Target Advertising campaign target ID Everyone
To Campaign Type network, cross_promo Advertisers
UUID Device Universal Unique Identifier (if available) Everyone (Publisher only if Behavioral Targeting is disabled)

App analytics grouped by country 🔗

The appcountry endpoint is a specially designed endpoint to return clean analytics data at the app, date, and country level and can also be used on behalf of Chartboost customers by third-party attribution and mediation services that require country-level data.

HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/appcountry
Example Request https://analytics.chartboost.com/v3/metrics/appcountry?dateMin={Minimum date}&dateMax={Maximum date}&userId={Chartboost customer’s user ID}&userSignature={CB customer’s user signature}

Parameters 🔗

Parameter Request Type Required? Description Default
appIds String Optional One or more (comma-separated) app IDs All apps
dateMin String Required The minimum date (YYYY-MM-DD) N/A
dateMax String Required The maximum date (YYYY-MM-DD) N/A
campaignType String Optional network or cross_promo or both (comma-separated) network
adTypeIds String Optional One or more (comma-separated) ad type IDs: 1 interstitial,3 in_play, 4 = rewarded_video, 5 = video_intersitial, 10 = banner 1, 4, 5, 10
role String Optional advertiser or publisher publisher
timezone String Optional utc or pst utc
adLocation String Optional One or more (comma-separated) adLocations
Case #1: (adLocation=\) shows results aggregated by each adLocation presented for ONLY for the specified adLocation(s). Information for any adLocation(s) is only available if the adLocation(s) is one of the Top 100 adLocations used by the Publisher App. No data is returned for the remaining adLocation(s).
Case #2: (adLocation='all') shows results broken down by the Top 100 adLocation(s) for a Publisher App with the remaining data being aggregated under adLocation = 'Default'
Case #3: (adLocation= empty or not-passed) aggregates all data under adLocation = 'overall'. No breakdown by adLocation is provided.		 see case #3

Response Fields 🔗

Parameter Description Returned for…
adLocation The Chartboost named location of the ad being published in the app. Advertisers will see default in the response field. Everyone
adType interstitial, rewarded_video, video_interstitial, banner Everyone
app App name Everyone
campaignType network, cross_promo Everyone
clicksDelivered Clicks Publishers
clicksReceived Clicks Advertisers
CountryCode Two-letter country code, or “unknown” Everyone
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
ctrDelivered Click-through rate Publishers
ctrReceived Click-through rate Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1000 impressions Publishers
ecpmSpent Cost per 1000 impressions Advertisers
impressionsDelivered Impressions Publishers
impressionsReceived Impressions Advertisers
installRateDelivered Install rate Publishers
InstallRateReceived Install rate Advertisers
installsDelivered Installs Publishers
installsReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
platform iOS, Google Play, or Amazon Everyone
videoCompletedDelivered Completed video views Publishers
videoCompletedReceived Completed video views Advertisers

Last modified November 27, 2023