FairBid User Level Reporting API

User Level Reporting API Metrics and Dimensions

Introduction

The FairBid 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 here.

Some programmatic networks do not disclose their exact CPM bids to publishers for the purpose of calculating user level revenues. In such cases, Fyber uses approved methods to base the user level revenue calculations on close estimates. When a non-disclosing network wins an impression we calculate the price of the impression based on the second highest bid of every auction and perform a revenue aggregation on a user level. This allows for reaching a number that's close to the actual revenue generated for impressions and therefore the users.

Naturally, when estimates are being used gaps in total revenues are being formed and therefore in every report that includes non-disclosing networks we will add a row called "Aggregated masked user level revenue". This row, not representing a real user, essentially accounts for any gap in total daily revenues that may be formed. That way when you compare the total revenue generated from the user level reporting APIs to those generated from less granular reporting APIs you will get to the same sum of revenues. 

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

Fyber'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

  1. Sign in to the Fyber Console, here.
  2. On the top right side of the screen click your User ID
c99c3d8-Screen_Shot_2019-11-06_at_9.51.49__1_.png
  1. Click User Profile to display the Reporting API Keys
c55d94e-Screen_Shot_2019-11-06_at_9.57.40__1_.png
  1. If necessary, you can click Revoke to delete the current credentials.
    You are returned to the API Keys window.
c64eafb-Screen_Shot_2019-11-06_at_9.57.01__1_.png
  1. Click Generate New Keys again, to receive new credentials.
d1deccf-Screen_Shot_2019-10-30_at_12.45.14__1_.png

Note

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
POST /auth/v1/token
Headers
Content-Type    application/json
Sample Request
https://reporting.fyber.com/auth/v1/token
Params
format  csv
Body: raw (application/json)
{
    "grant_type": "client_credentials",
    "client_id": "3ce66d885XXXXXXXXXXa3b752bb9058",
    "client_secret": "YtMvC7VYTQMQ7w9UCUaFTRGJnwVZnQqqN02XNyt8IIh2h8XFDuXXXXXXXXSS6XTrFWW4TkebCcMLJkrXSw5IurkearTJIDzUxsbiMXv8hb4T23MwN6eE7DDIthRFqDnhnuhiDlY2oPeaOjsMbzE8joZ5cs6tsySJz6uZXwJ-x3lcYaYbgXXXXXXXX3_hFeuXm-C7-me2V1MMs-ftJxTd5QbHoUhG3Q5anCWCW_pg8x3CL4yPGCbpWUDZfpdNPyyCT4rxCEb-VC0Bdqwe8N2GGn_VSFOwQYxa-yap2JuNSGJfl_ZURXXXXXXXXFe1GpHDn8pk7yYwQYIGAg"
}

Note

  • 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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1NzAwMTY5MDAsImV4cCI6MTU3MDAyMDUwMCwiYXVkIjoic3BlZWRiYWxsIiwic3ViIjoiMjEwMjYzIn0.hDo1waTytSys_oRhFNUPqZPom26bL05rxgtSt3XYHqI",
  "tokenType": "bearer",
  "expiresIn": 3600
}

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
{
  "error": "internal_server_error"
}

Possible Authentication Errors

Set out in the table are a list of possible errors which resulted in an unsuccessful response.

HTTP Status Code Error Scenario
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 Fyber'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-02-16
AppID: 123

For further descriptions about the terms used in this article, click here.

Make a POST request to receive your report.

URL
https://reporting.fyber.com/api/v1/report/user-level-data
Headers
Content-Type:   application/json
Authorization: Bearer <Access Token from Authentication Response>
Body. raw (application/json)
{
    “date”: “2020-01-01",
    “appId”: “123"
}
 

Responses

Set out below are examples of both successful and unsuccessful responses.

Response: Successful
{
  "id": "6fad42cb-25db-4af0-8988-1e7d8e6d90bc",
  "url": "https://fyber-async-reports.s3.amazonaws.com/group%3D210263/6fad42cb-25db-4af0-8988-1e7d8e6d90bc.csv?AWSAccessKeyId=AKIAQBQNZ5FY23OTK4UD&Expires=1570020564&Signature=LbhE5uljlPEKQRTbepDqmDgJuFQ%3D",
}
  • 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
{
  "error": "invalid_token"
}
 

Possible Errors

The table below shows the main errors indicating an unsuccessful response.

HTTP Status Code Error Description (optional) Scenario
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 Fyber's servers
 

Step 3: Receiving the Custom Report

To obtain the Custom Report, follow the steps below:

  1. Receive the URL from the successful response in Step 2
  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 24 hours. 

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
 
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request