Reporting API - Publisher

Last updated: 12/11/2024

Overview

As a Publisher, you can use the Reporting API to retrieve reporting data for your apps that serve the Offerwall.

Before you begin: You must authenticate with the API, following the steps here.

For information on how to manage your content through the Reporting API, see Content Management.
For information on error handling and limitations with the Reporting API, see 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	Publisher App	Placement
averageDuc	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	x	x	x	x
arpdau	Average revenue per daily active user (total revenue divided by the number of daily active users)	x	x	x
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)	x	x	x
averageDau	Average number of daily active users (counted once per 24 hours per user) divided by number of days	x	x	x
averageDuv	Average number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) divided by number of days	x	x	x
clicks	Number of clicks that originated from the placement	x			x
conversions	Number of conversions that originated from the placement	x			x
dailyActiveUsers	Number of daily active users	x	x	x
dailyUniqueConversions	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	x			x
dailyUniqueOfferwallEngagements	Number of unique users that converted on an offerwall ad in the app (counted once per 24 hours per user)	x	x	x
dailyUniqueOfferwallViewers	Number of unique users that viewed an offerwall in the app (counted once per 24 hours per user)	x	x	x
dailyUniqueViewers	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	x			x
ducduv	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)	x	x	x	x
duvDau	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	x	x	x
earnings	Total amount earned	x			x
impressions	Number of impressions that originated from the placement	x			x
newUsers	Number of new users	x	x	x
offerwallViews	Total number of offerwall open	x	x	x
sessions	Number of app opens	x	x	x
totalRevenue	Total revenue	x	x	x

Additional publisher metrics available in the Dashboard:

Impressions/Views
Conversion Rate (CVR)
eCPM

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

Segmentation Examples

Segment by Country

Query

Result

{
  publisher {
    placements(appId: "00000000-0000-0000-0000-000000000000") {
      id
      insights(timePreset: TODAY) {
        timestamps
        reports {
          country
          dailyUniqueViewers
        }
      }
    }
  }
}

Segment by App Group

Query

Result

{
  publisher {
    apps(first: 3) {
      nodes {
        appGroupId
        insights(timePreset: TODAY) {
          reports {
            dailyActiveUsers
          }
        }
      }
    }
  }
}

Segment by Publisher App

Query

Result

query {
  publisher {
  apps(first:3) {
      edges {
        node {
          name
          insights(timePreset:TODAY) {
            reports {
              dailyActiveUsers
            }
          }
        }
      }
    }
  }
}

Segment by Placement

Query

Result

{
  publisher{
    placements(appId: "00000000-0000-0000-0000-000000000000") {
      id
      name
      insights(timePreset: TODAY) {
        reports {
          impressions
        }
        timestamps
      }
    }
  }
}

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 (multiple apps)
content
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 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 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.

Note: To define the level of data aggregation, include timeIncrement, which can take values DAILY, HOURLY, MONTHLY. timeIncrement is an optional parameter and defaults to ALL

{
  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.

Note: To define the level of data aggregation, include timeIncrement, which can take values DAILY, HOURLY, MONTHLY. timeIncrement is an optional parameter and defaults to ALL

{
  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
          }
        }
      }
    }
  }
}