Documentation

Support

Offerwall

Get started with Monetization

Get started with User Acquisition

Unity SDK integration

Offerwall

User Level Revenue API Overview

Use Tapjoy Offerwall's User-Level Revenue API to track user-specific earnings and adjust your app's monetization strategy based on actionable insights.
Read time 3 minutesLast updated 23 days ago
Tapjoy enables publishers to access their Offerwall user level ad revenue data via a User Level Ad Revenue API, in addition to our existing offer data callbacks. This API makes User Level Ad Revenue reports available directly to Mobile Measurement Partners (MMPs) or Publisher Partners via a CSV file stored in Amazon Web Services (AWS) S3. In order to make the requests, users will need the relevant Tapjoy App ID (the same one associated with the app for the Tapjoy LTV dashboard) and the date for which data is desired. To use the API, the MMP or Partner must make a request to the Tapjoy OAuth endpoint with their Reporting API/Marketing API key to receive an access token. With the access token, the user then makes a request to the Tapjoy Report API to receive the pre-signed URLs pointing to the reports in AWS S3. The pre-signed URLs will allow access to the reports for 5 min following retrieval. Lastly, a request to the report URLs in AWS S3 will return the CSV reports containing the User Level Ad Revenue data.

Report API

Endpoint: 
https://api.tapjoy.com/api/client/publisher/apps/<app_id>/user_revenue_report
 Accessible via OAuth with your Reporting API/Marketing API key. Required parameters:
  • Publisher app ID
  • Date in UTC
Acceptable date formats are mm/dd, mm/dd/yyyy, mm/dd/yy, dd-mm yyyy-mm-dd, yy-mm-dd Returns an array of urls to the static report(s) with a pre-signed authentication token which is valid for 5 min.

Example request

GET api/client/publisher/apps/<publisher_app_id>/user_revenue_report?date=<date> 
Host: api.tapjoy.com 
Authorization: Bearer <access_token_string> 
Accept: application/json

Example Response

Success

{
	"urls": [
	"https://tapjoy.amazon.s3.com/data/report.csv.gz&key=secure"
  	  ]
}

Failure

status 404 
{ 
	“reason”: “No publisher app with id <publisher_app_id> found.” 
}

S3 API

Data SLA - data for day x to be ready by day x+1 at 01:00 UTC Retention SLA - reports are available for 14 days (day x + 15) Returns a CSV file of the User Level Revenue report

Example request

GET /data/report.csv.gz&key=secure
Host: tapjoy.amazon.s3.com 
Accept: application/json

Example response

Success

status 200 
{ 
  CSV File
}

Fields Overview

The following table details what the different columns in the report represent.

Field

Description

date_id and report_dateThis is the user-specific report date from the API request. The metrics in the report will be for this date in question
partner_idThis is your Tapjoy internal identifier
app_name and appkeyThese are the name and Tapjoy identifier for your app
IDFA/IDFV/GAIDDepending on the platform, these columns will either have the identifier value or UNKNOWN
device_os_versionOperating system version for the associated mobile device
att_statusiOS App Tracking Transparency status for the device if known
publisher_user_idThe publisher identifier associated with the device if available
ad_unitThis will always be offerwall and is used by MMPs for processing
placementThe Tapjoy placement name
content_cardThe Tapjoy content card name
geoip_countryThe country associated with the device if available by IP lookup
currency_saleA value of 1 indicates that a currency sale was not in progress when the associated conversion happened or will be the currency multiplier value if there was a sale
conversion_rateThis is the currency exchange rate used for the transaction
impressionsThe aggregated impressions associated with this device ID for the day in question. This represents the number of times the user viewed the converted offer, on the day that they converted.
publisher_amountThe aggregated revenue associated with this device ID for the day in question

FAQ

No, this report includes Offerwall ad revenue only. If user level ad revenue data is desired, then Partners should contact their mediator on accessing an applicable API or report.

Reports are accessible for Publisher Partners to access for 14 days and each day at 1:00 AM UTC the previous day's report will be available.

For the MR-CPE product, there is often a delay (days or even weeks) between when the impression was shown and when the event conversions happen later in the multi-reward funnel.

It's shown in United States Dollars (USD)

Appsflyer

It's possible for a user to view and convert an offer in the same publisher app with different 
publisher_user_ids
or 
geoip_countries
. These IDs are set by the publisher on SDK initialization, so something like the following could happen:
  1. The user connects with 
    publisher_user_id A
    .
  2. They view offer A. The view record has 
    publisher_user_id A
    .
  3. The user connects later with 
    publisher_user_id B
    .
  4. They view offer A again. The view record has 
    publisher_user_id B
    .
  5. They convert. The conversion record has 
    publisher_user_id B
    .
The same thing could happen for 
geoip_countries
. To avoid inflating earnings, these values need to be combined into a single row.