Reporting API - Publisher
Access Tapjoy Offerwall’s Reporting API as a publisher to retrieve detailed data, monitor and assess app performance, and optimize your monetization strategies.
Read time 5 minutesLast updated 3 hours ago
As a Publisher, you can use the Reporting API to retrieve reporting data for your apps that serve the Offerwall.
Prerequisites
You must authenticate with the API. Refer to API authentication.- For information on how to manage your content through the Reporting API, refer to Content Management.
- For information on error handling and limitations with the Reporting API, refer to Reporting API Best Practices.
Publisher Reporting Metrics
The Reporting API can be used to request performance data for your Offerwall content, including metrics such as clicks, conversions, and total revenue. All available publisher reporting metrics are listed in the chart below. We recommend publishers to start with the following base query to retrieve performance metrics:{ publisher { placements(appId: "00000000-0000-0000-0000-000000000000") { id name insights( timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"} ) { timestamps reports { dailyUniqueViewers earnings } } } } }
Publisher Metric | Description | Country | App Group | Single Publisher App | Placement | Sum across all Publisher Apps |
---|---|---|---|---|---|---|
| Average number of unique users that converted on an offerwall ad in the app, placement, or content card (counted once per 24 hours per user) divided by number of days | yes | yes | yes | yes | yes |
| Average revenue per daily active user (total revenue divided by the number of daily active users) | yes | yes | yes | no | yes |
arpduv | Average revenue per daily unique offerwall viewer (total revenue divided by the number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) | yes | yes | yes | no | yes |
| Average number of daily active users (counted once per 24 hours per user) divided by number of days | yes | yes | yes | no | yes |
| Average number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) divided by number of days | yes | yes | yes | no | yes |
| Number of clicks that originated from the placement | yes | no | no | yes | no |
| Number of conversions that originated from the placement | yes | no | no | yes | no |
| Number of daily active users | yes | yes | yes | no | yes |
| Number of users who converted on an ad from this placement or content card (counted once per 24 hours per user). Currently only applies to offerwall content cards | yes | no | no | yes | no |
| Number of unique users that converted on an offerwall ad in the app (counted once per 24 hours per user) | yes | yes | yes | no | yes |
| Number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) | yes | yes | yes | no | yes |
| Number of unique users who viewed an ad in this placement or content card (counted once per 24 hours per user). Currently only applies to offerwall content cards | yes | no | no | yes | no |
| Number of users who converted on an ad from this placement or content card (counted once per 24 hours per user) divided by the number of users who viewed an ad in this placement or content card (counted once per 24 hours per user) | yes | yes | yes | yes | yes |
| Number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) divided by the number of daily active users | yes | yes | yes | no | yes |
| Total amount earned | yes | no | no | yes | no |
| Total revenue / (Total Offerwall Opens / 1000). This is represented in USD | yes | no | no | yes | no |
| Number of impressions that originated from the placement | yes | no | no | yes | no |
| Number of new users | yes | yes | yes | no | yes |
| Total number of offerwall open | yes | yes | yes | no | yes |
| Number of app opens | yes | yes | yes | no | yes |
| Total revenue | yes | yes | yes | no | yes |
- Impressions/Views
- Conversion Rate (CVR)
Metric Segmentations
By adding segment fields to your queries, the API can return performance data broken down by app, placement, and/or country. The Reporting API supports segmentation under the following breakdowns:- country
- id (App Group ID)
- id (Publisher App ID)
- placement
- platform
- total across all Publisher Apps
Segmentation Examples
Segment by Country
{
publisher {
placements(appId: "00000000-0000-0000-0000-000000000000") {
id
insights(timePreset: TODAY) {
timestamps
reports {
country
dailyUniqueViewers
}
}
}
}
}
Segment by App Group
{
publisher {
apps(first: 3) {
nodes {
appGroupId
insights(timePreset: TODAY) {
reports {
dailyActiveUsers
}
}
}
}
}
}
Segment by Publisher App
query {
publisher {
apps(first:3) {
edges {
node {
name
insights(timePreset:TODAY) {
reports {
dailyActiveUsers
}
}
}
}
}
}
}
Segment by Placement
{
publisher{
placements(appId: "00000000-0000-0000-0000-000000000000") {
id
name
insights(timePreset: TODAY) {
reports {
impressions
}
timestamps
}
}
}
}
Segment by Platform
{
publisher {
placements(appId: "00000000-0000-0000-0000-000000000000") {
id
insights(timePreset: TODAY) {
timestamps
reports {
platform
dailyUniqueViewers
}
}
}
}
}
Sum across all Publisher Apps
This represents the total or sum of the requested metrics, across all apps under this Publisher.{
publisher {
publisherAppInsights(timePreset: TODAY) {
timestamps
reports {
ecpm
totalRevenue
offerwallViews
}
}
}
}
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:- appId (single app)
- apps (the first or last x apps)
- appGroupId
- content
- country
- platform
- timePreset
- timeRange
Filtering Examples
Filter by App
This limits results to a single App{ publisher{ app(id: "<app ID>") { id name insights(timePreset: TODAY) { reports { arpdau } timestamps } } } }
Filter for Multiple Apps
This limits results to the first or last x Apps{ publisher { apps(first: 3) { nodes { id platform insights { reports { arpdau totalRevenue } } } } } }
Filter by App Group ID
This limits results to apps under a specific App Group ID{ publisher { publisherAppInsights(timePreset: TODAY, filter: {appGroupIds: ["00000000-0000-0000-0000-000000000000"]}) { timestamps reports { offerwallViews eCPM totalRevenue } }
Filter by Content Card
This limits results to a single Content Card ID{ publisher { placements(appId: "<app ID>") { id name content(id: "<content ID>") { id type insights(timePreset: TODAY) { timestamps reports { earnings } } } } } }
Filter by Country
This limits results to the specified geos{ publisher { publisherAppInsights(timePreset: TODAY, filter: {countries: ["KR, US"]}) { timestamps reports { offerwallViews eCPM totalRevenue } }
Filter by Platform
This limits results to the specified platforms{ publisher { publisherAppInsights(timePreset: TODAY, filter: {platforms: [ios]}) { timestamps reports { offerwallViews eCPM totalRevenue } }
Filter by a Preset Timeframe
This limits results to a preset timeframe. This is a relative time range and results will vary based on when the query is run. Options: LAST_30D, LAST_WEEK, TODAY, YESTERDAY.{ publisher { placements(appId: “<app ID>”) { content(id: “<content card ID>") { insights(timePreset:LAST_30D, timeIncrement: DAILY) { timestamps reports { dailyUniqueViewers } } } } } }
Filter by an Absolute Time Range
This limits results to the absolute time range specified. The maximum range is 3 months and the earliest date supported is 2 years in the past.{ publisher { placements(appId: “<app ID>”) { content(id: “<content card ID>") { insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-17T00:00:00Z"}, timeIncrement: DAILY) { timestamps reports { dailyUniqueViewers } } } } } }
Deprecated Dimensions
The following legacy dimensions will be removed from the Reporting API on February 3, 2025. Ensure that your API queries do not reference any of the dimensions listed in bold below, to prevent errors when fetching data from Tapjoy's offerwall. Objects > ContentCard > ecpmSettings Enums > PublisherContentType:ANNOUNCEMENT
DIRECT_PLAY_HOUSE_AD
FEATURED
FSI_HOUSE_AD
IAP_PROMOTION
INTERSTITIAL_VIDEO
MEDIATED_DIRECT_PLAY
MEDIATED_FSI
PREVIEW_CODE
PROGRAMMATIC_INTERSTITIAL_VIDEO
PROGRAMMATIC_REWARDED_VIDEO
REWARDED_VIDEO
TJ_RECOMMENDED
REWARD_UNLOCK
CreatePlacementAndContentSetInput
UpdatePlacementAndContentSetInput
ecpmSettingsToAdd
ecpmSettingsToDelete
ecpmSettingsToUpdate