Documentation

Support

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.

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

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 daysyesyesyesyesyes
arpdau
Average revenue per daily active user (total revenue divided by the number of daily active users)yesyesyesnoyes
arpduvAverage 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)yesyesyesnoyes
averageDau
Average number of daily active users (counted once per 24 hours per user) divided by number of daysyesyesyesnoyes
averageDuv
Average number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) divided by number of daysyesyesyesnoyes
clicks
Number of clicks that originated from the placementyesnonoyesno
conversions
Number of conversions that originated from the placementyesnonoyesno
dailyActiveUsers
Number of daily active usersyesyesyesnoyes
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 cardsyesnonoyesno
dailyUniqueOfferwallEngagements
Number of unique users that converted on an offerwall ad in the app (counted once per 24 hours per user)yesyesyesnoyes
dailyUniqueOfferwallViewers
Number of unique users that viewed an offerwall in the app (counted once per 24 hours per user)yesyesyesnoyes
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 cardsyesnonoyesno
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)yesyesyesyesyes
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 usersyesyesyesnoyes
earnings
Total amount earnedyesnonoyesno
eCPM
Total revenue / (Total Offerwall Opens / 1000). This is represented in USDyesnonoyesno
impressions
Number of impressions that originated from the placementyesnonoyesno
newUsers
Number of new usersyesyesyesnoyes
offerwallViews
Total number of offerwall openyesyesyesnoyes
sessions
Number of app opensyesyesyesnoyes
totalRevenue
Total revenueyesyesyesnoyes
Additional publisher metrics available in the Dashboard:
  • 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
Input Objects >
CreatePlacementAndContentSetInput
> ecpmSettingsToAdd
Input Objects >
UpdatePlacementAndContentSetInput
:
  • ecpmSettingsToAdd
  • ecpmSettingsToDelete
  • ecpmSettingsToUpdate