Documentation

Unity Offerwall

Offerwall Android SDK

Offerwall iOS SDK

Offerwall Unity SDK

Unity Offerwall

Reporting API for advertisers

Access Tapjoy Offerwall's Reporting API as an advertiser to retrieve detailed data, monitor and assess app performance, and optimize your reporting queries for better campaign insights.
Read time 13 minutesLast updated a month ago
As an Advertiser, you can use the Reporting API to retrieve reporting data for your ads that are served in the Offerwall.

Prerequisites

You must authenticate with the API.

Advertiser reporting metrics

Use the Reporting API to request performance data for your ad sets and multi-reward events, including metrics such as revenue, impressions, and conversions.
The recommended best practice is to start with the following base query to retrieve performance metrics:
query {  adSet(id: "00000000-0000-0000-0000-000000000000") {    insights(timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"}) {      timestamps      reports {        impressions      }    }  }}
Refer to the following table for a list of advertiser reporting metrics:

Advertiser metric

Description

Calculation

amount
The advertiser-configured bid for this event.Not applicable
averageBid
The average bid amount.
Note
This is a derived metric representing the realized average bid paid per conversion, not the configured bid (
amount
).
Total Spend ÷ Total Conversions.
callToActionClicks
The number of times users clicked the call-to-action, if a call-to-action is present.Not applicable
clickToConversionTime
Click to conversion time data segmented in several different ways.
Note
CTCT metrics are only reported in the first UTC hour of every day. When you use a granularity of 
HOURLY
, only the hour representing 
00:00:00 UTC to 00:59:59 UTC
will have a value other than 0.
Not applicable
conversions
Number of conversions for the ad objective.Not applicable
csConversions
Number of Customer Service conversions for the ad objective.Not applicable
csSpend
Total Customer Support amount spent.Not applicable
ecpi
Effective cost per engagement.Total Spend ÷ Total Engagements.
engagementInstalls
The number of installs inferred from engagements.Not applicable
iaaRevenue
Total Ad Revenue generated by an offer during the selected time range.Not applicable
iapRevenue
Total IAP Revenue generated by an offer during the selected time range.Not applicable
impressions
The number of times the ad was clicked on in the offerwall.
Note
This metric more accurately represents 
clicks
, not 
impressions
.
Not applicable
offerwallAverageRank
The (weighted) average offerwall position the ad was served in.
The value is ascending from 
1
, with 
1
representing the top spot in the offerwall. A value of 
0
means the offer was not displayed in the offerwall for the selected time period.
offerwallImpressions
The number of times the ad appeared in the offerwall.
Note
An ad can appear in the offerwall and not be viewed by a user (for example, user has not scrolled far enough to see the ad). The recommended best practice is to use 
offerwallTrueImpressions
.
Not applicable
offerwallTrueImpressions
The number of times the ad was viewed by a user in the offerwall.Each view registers as a true impression.
returnOnAdSpend
Return on ad spend (ROAS) data for users who installed on each day.
Note
ROAS metrics are only reported in the first UTC hour of every day.
Not applicable
dayXRoas
Total return on ad spend 
X
days from install.
dayXRoasRevenue
÷ 
dayXRoasSpend
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
Note
If 
dayXRoasRevenue
is 0, this field will also be 0.
dayXRoasAdRevenue
Total ad revenue generated by an offer 
X
days after install, from users who installed the offer during the selected time range.
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
dayXRoasEngagements
Total user engagements 
X
days from install.
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
dayXRoasIapRevenue
Total IAP revenue generated by an offer 
X
days after install, from users who installed the offer during the selected time range.
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
dayXRoasRevenue
Total revenue (IAP + Ad Revenue) generated by an offer 
X
days after install, from users who installed the offer during the selected time range.
dayXRoasIapRevenue
+ 
dayXRoasAdRevenue
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
dayXRoasSpend
Total advertiser spend 
X
days from install.
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
spend
Total amount spent.Not applicable
totalRevenue
Total revenue (IAP + Ad Revenue) generated by an offer during the selected time range.
iaaRevenue + iapRevenue
.
Note
When segmented by 
multiRewardEngagementEvent
, 
averageBid
represents the realized average bid paid per conversion for each engagement event over the selected range, not the configured bid. For the configured bid, refer to 
amount
in Campaign management.
averageBid
is returned as an array with one value per time bucket, like other insights metrics, with a single element when 
timeIncrement
is 
ALL
. A value of 
null
means there were no conversions for that event in the bucket.
The following additional advertiser metrics are also available in the dashboard:
  • Conversion Rate (CVR)
  • Instruction CVR
  • Conversions/Impressions
  • Click-through Rate (CTR)
  • ROAS by Total Spend (the Reporting API returns ROAS by Cohorted Spend)

Metric segmentations

By adding segment fields to your queries, the API can return performance data broken down by segements such as event, publisher app, or country. The Reporting API supports segmentation under the following breakdowns:
  • country
  • attributionSource
  • language
  • platform
  • id (Publisher App ID)
  • id (AdSet/Offer ID)
  • multiRewardEngagementEvent

Segmentation examples

Segment by country, attribution source, and/or language

The following query returns conversion data segmented by country, attribution source, and language for a specific ad set and time range.
{ adSet(id: "00000000-0000-0000-0000-000000000000") { insights(timeRange: {from: "2024-08-01T00:00:00Z", until: "2024-08-01T11:59:59Z"}, timeIncrement: DAILY) { timestamps reports { country attributionSource language conversions } } }}

Filtering capabilities

By adding filters to your queries, the API will return performance metrics from the specified sources only. The Reporting API supports the following filtering capabilities:
  • adSet (Single Ad Set)
  • adSets (Multiple Ad Sets)
  • appIds (Publisher App)
  • configuredStatus (
    ACTIVE
    , 
    ARCHIVED
    , or 
    PAUSED
    )
  • countries
  • timePreset
  • timeRange

Filtering examples

Filter by ad set

This limits results to a single 
adSet
:
query {  adSet(id: "00000000-0000-0000-0000-000000000000") {    insights(timeRange: {from: "2024-08-06T00:00:00Z", until: "2024-08-07T00:00:00Z"}) {      timestamps      reports {        impressions        conversions        spend        offerwallAverageRank      }    }  }}

Deprecated dimensions

The following deprecated dimensions are unavailable as of February 2025. Ensure that your API queries don't reference any of the following dimensions to prevent errors when fetching data from Tapjoy's Offerwall:
  • Enums > TargetConnectionType > MOBILE
  • Enums > TargetDeviceType > WINDOWS