User Level Reporting API
The User Level Reporting API enables you to access reporting data to measure all revenue generated from individual users. This information can be used to optimize retargeting campaigns and accurately measure user lifetime value.
You can query revenue and impressions metrics across the available dimensions. For all supported metrics and dimensions for the User Level Reporting API, click the Metrics and Dimensions tab above.
The User Level Reporting API is disabled by default for any new app onboarding. To enable it, contact your Account Manager. Once enabled, data is aggregated from six days prior to the activation date.
Reporting API Workflow
The publisher makes a POST request using the Client ID and Client Secret to receive the Access Token, as described in Step 1.
Once the request is successful and the Access Token is received, an API Request is made to create a custom report as described in Step 2.
A successful response will contain a URL leading to a file containing the custom report. More details can be found in Step 3.
Step 1: Obtaining the Access Token
Digital Turbine's Reporting API uses Access Tokens for authentication purposes. To obtain your Access Token, you must first get your Client ID and Client Secret.
Obtaining your Client ID and Client Secret
Sign in to the DT Console.
On the top left side of the screen click your User ID
Click User Profile to display the Reporting API Keys
If necessary, you can click Revoke to delete the current credentials. You are returned to the API Keys window.
Click Generate New Keys again, to receive new credentials.
Keep your Client ID and Client Secret safe, as they can be reused in the future.
Using your Client ID and Client Secret make a POST request to receive your Access Token.
The base End Point for the entire process is: https://reporting.fyber.com
Authentication token
Headers
Sample Request
Params
Body: raw (application/json)
Grant Type must be "client_credentials"
The credentials are sent according to the OAuth 2.0 protocol
Sample Authentication Response
When an authentication request is successful, you receive the following response in JSON format:
Successful Response
accessToken
The token required to continue the process
tokenType
Bearer
expiresIn
3600 seconds (1 hour)
When a request is unsuccessful, you receive the following response:
Unsuccessful Response
Possible Authentication Errors
Set out in the table are a list of possible errors which resulted in an unsuccessful response.
400
unsupported_grant_type
N/A
400
invalid_request
When there are missing credentials
400
invalid_client
When the credentials are incorrect or cannot be recognized. Can also occur when your account has been disabled or when the credentials have been revoked.
500
internal_server_error
Unexpected errors in DT's servers
Step 2: Reporting API Request
Use the access token you received in Step 1 to request your custom report.
The two dimensions that you can query in your request are:
Date
App ID
All other dimensions always appear in the report.
Request Example
The below is an example from the User Level report.
Date
Date: 2020-16-02 AppID: 123
For a full list of supported Metrics and Dimensions, see User Level Metrics and Dimensions.
For further descriptions about the terms used in this article, see Using the Reports.
Make a POST request to receive your report.
URL
Headers
Body. raw (application/json)
Responses
Set out below are examples of both successful and unsuccessful responses.
Response: Successful
The "id" field holds an identifier of the request for later troubleshooting, if required.
The "url" field holds the URL to be polled (GET request) until the body response (file) is populated.
Response: Unsuccessful
Possible Errors
The table below shows the main errors indicating an unsuccessful response.
401
invalid_token
N/A
Authorization header is empty Authorization header not sent or token is not present in the header Unrecognized token Disabled account
400
invalid_query
For example: Invalid value undefined supplied to : Query/dateRange: DateRange -or- Invalid value "XXXXX" supplied to : Query/dateRange: DateRange/end: Date
If the query sent is not in the expected schema Date range is not sent in the ISO 8601 format
500
internal_server_error
N/A
Error in DT's servers
Step 3: Receiving the Custom Report
To obtain the Custom Report, follow the steps below:
Receive the URL from the successful response in Step 2.
Click the link. You are redirected to a folder which contains your report.
The URL is valid for three hours.
Additional Information and Restrictions
It is important to take note of the information, restrictions and rules to ensure the reports provided to ensure a successful response.
General
All reports are presented in US dollars
The time zone used is UTC
The data in the folder is available by 1200 UTC (noon) for the previous 10 days.
Query Restrictions
All dimensions are mandatory.
Date Information
There are a number of rules that must be observed with regard to the date:
The date must be in the format of ISO 8601. For example, 2019-10-03
The date is included in the report
The date is relevant from 16 February 2020
You must specify in the API Request the metrics and dimensions you want to include in your custom report.
User Level Metrics and Dimensions
Set out in the tables below are the supported metrics and dimensions available in the User Level Reporting API.
Metrics
Impressions
Number of times the ad is displayed to the users
Revenue
The total revenue of the publisher in USD
Discrepancies may occur since the number of impressions is based on our counting method and revenues are estimated.
Dimensions
The following are the supported Dimensions for the User Level Reporting API:
Ad Network Name
For mediation, we use the network name and for DT Exchange networks we use 'DT Exchange'
Ad Unit ID
The ad unit identifier in the DT system
Container Type ID
The identifier of the type of placement
Advertising ID
The Advertising ID for either Apple or Google
IDFV
An alphanumeric string that uniquely identifies a device to the app’s vendor. (This dimension is relevant to FairBid customers only).
User ID
The identifier of the user supplied by the publisher. (This dimension is relevant to FairBid customers only).
Instance ID
The Instance ID as generated by the demand network. Note: This is referred to differently, by various demand networks.
Placement ID
A Placement's identifier in the DT system
Placement Type
Placement type describes how ads will look in your app and where ads will be located. Placement types can be either banner, interstitial or rewarded. Banner A basic placement type appearing at the top or bottom of the device's screen. Does not support video content Rewarded An ad placement type supporting video content Interstitial Full-page ads appear at natural breaks & transitions, such as level completion. Supports video content
Last updated