statistics - Unity-Technologies/unity-ads GitHub Wiki

/* Title: Monetization statistics
Sort: 3 */

Unity Ads provides robust reporting tools for analyzing your monetization metrics. You can either use the dashboard reporting tools, or the Monetization stats API to pull performance data.

From the Unity Dashboard, click the navigation menu (☰) and select Monetize > Organization/Ads Data Export, then select Email & CSV from the left navigation panel. If you're using the old dashboard interface, click the Operate tab, then select Ads Data Export > Email & CSV from the left navigation panel.

You can either download data directly, or set up automated email reports for your Organization.

Under the Raw Data CSV Download section, configure the parameters of your report. Specify the data split (by country, Ad Unit, and platform), granularity of statistics reported, and date range. When finished, click the Download CSV button to export.

To create automated reports on a specified cadence:

1. Under the Email reporting section, click the Add button.
2. In the configuration prompt, name the report, then set how to split the data (by country, Ad Unit, or platform) and how often you want to generate the report. Finally, enter the email addresses (separated by commas) to receive the reports.

From the Unity Dashboard, click the navigation menu (☰) and select Monetize > Project/Reporting. If you're using the old dashboard interface, click the Operate tab, then select Reporting > Ad Revenue from the left navigation.

Use the filters to isolate data by date range, platform, country, Ad Unit, or content type.

• Ads Revenue shows the total revenue from ads.
• Impressions shows the number of times a video ad played.
• eCPM (effective cost per mille) shows the average revenue you generate per 1000 impressions.
• Fill Rate shows the rate of available ads served divided by the number of ad requests.
• Impressions/DAU shows the average number of impressions per daily active user.

The chart (top) provides a visualization of each performance metric. Use the dropdown menu to plot results by date, platform, country, Ad Unit, or project. Click the chart icons to toggle between bar and line graphs.

The table (bottom) provides performance metric data as an exportable CSV file. Click the tabs to parse results by date, project, platform, country, Ad Unit, or content type. Click the download icon to export the data into a CSV file.

The Monetization Stats API allows you to retrieve monetization data directly in CSV format. The API fetches the same statistics that are available on the developer dashboard, however you can use it to programmatically pull data for your own uses.

Important: Mediation partners need a Unity API key in order to gather accurate reporting for the Unity Ads network. If you already use the deprecated Applifier Statistics API in your mediated integration, please consult your mediation partner before migrating to the Monetization Statistics API. Note that you can still use the Monetization Statistics API to ping Unity's network for reporting data directly. All unmediated customers can safely migrate to the new API.

The endpoint uses an API key from the Monetize dashboard. Select Ads Data Export > API Access from the navigation bar, then copy the API key from the Monetization Stats API Access section, or click Create Api Key if none exists.

Note: The Monetization Statistics API generates a unique key for each user. For mediation integration purposes, any individual's key will work for the entire Organization.

You must include the API key as the "apikey=<token>" query parameter, or using the authentication header "Authorization: Token <token>". The redirect URL fetches the data. This is standard HTTP behavior that is supported by all HTTP clients.

If the authentication fails, the authentication server responds with an HTTP/2 error code, and a message in the body. For example:

400 {"errors":[{"msg":"access token required"}]}

To retrieve statistics data from the Unity Ads service, use the following GET request, where organizationId is the Organization core ID of your Unity Organization:

GET 
https://monetization.api.unity.com/stats/v1/operate/organizations/:organizationId

The API supports various ways to split your data. Some are required for a successful request.

Note: Some of the following parameters were updated from the Applifier API. To see a list of changes, see the section on migration.

This API supports returning CSV or JSON files. Specify the output format in the "Accept" header as follows:

• For CSV, use "Accept: text/csv"
• For JSON, use "Accept: application/json"

Following is an example request, using real parameters (with the exception of placeholder Organization core ID and API key):

curl 
https://monetization.api.unity.com/stats/v1/operate/organizations/:organizationId?groupBy=country,placement,platform,game&fields=adrequest_count,available_sum,revenue_sum,start_count,view_count&scale=hour&start=2020-05-01T00:00:00Z&end=2020-06-01T23:59:00Z&apikey=:apiKeyValue -H "Accept: text/csv" --output stats.csv

Note: Splitting data across multiple dimensions causes the CSV to grow exponentially, which might cause some large data sets to time-out. The request times out if the server takes more than 60 seconds to process the request.

The endpoint returns the following status codes indicating the result of the request:

Many changes from the Applifier API are not backwards compatible. However, they are not time consuming, and only require minor modifications. The following section highlights those changes, and guidance on how to adapt to the new API.

The following main differences apply:

• The endpoint URL
• The API key
• Using Organization IDs instead of Developer IDs
• Query parameters

The new API URL is:

https://monetization.api.unity.com/stats/v1/operate/organizations/:coreOrganizationId

coreOrganizationId is your Organization ID (see section below).

The old API uses a legacy API key that is not supported by the new API. The new API key is located in the Monetize Dashboard (see section on Authentication).

The new API requires an Organization ID as part of the URL. To locate it, open the Monetize Dashboard, select Settings, and copy the Organization core ID field from the Organization info section.

The following table maps parameters from the old API to their equivalents in the new API. These changes apply to CSV column names as well.

The fields parameter is the same, however, note that it is now required. Omitting it won’t default to all, as with the Applifier API. The following parameter options have changed:

The splitBy parameter is now groupBy. Note that it is now optional. Omitting the parameter defaults to groupBy=none. The following parameters have changed:

The scale parameter is the same, however, note that it is now required. Omitting it won’t default to day, as with the Applifier API. The following parameter option has changed:

The start and end parameters are the same. However, while the Applifier API allowed you to define a time frame relative to the current date (for example, start=7), that is no longer supported. Both start and end are now required parameters.

The sourceIDs parameter represents a source's store-specific ID. Note that this is different from a Game ID, which refers to a source's internal Unity ID.

The Applifier Statistics API is deprecated, but still works for mediated customers while their mediation partners update their API calls. If your mediation partner isn't listed in this section, contact them directly for more information.

In order to update your API key in mediation, you'll need the following information:

• Organization Core ID (located in the Monetize Dashboard under Settings).
• Monetization Stats API key (located in the Monetize Dashboard under Ads Data Export > API Access).

1. In the MAX dashboard, select Networks from the left nav bar, then Unity Settings.
   
   
2. Click the link to reconnect the network with new credentials.
   
   
3. Input the Organization core ID and Monetization Stats API key from Unity's Monetize Dashboard, then click Save.
   
   

MAX will automatically switch to call the new Unity reporting API.

1. In the MoPub dashboard, edit the Unity Ads network settings.
   
   
2. In the "Network settings" tab, make sure the Reporting access toggle is enabled.
3. Input the Organization core ID and Monetization Stats API key from Unity's Monetize Dashboard.
   
   

MoPub will automatically switch to call the new Unity reporting API.

1. In the IronSource dashboard, select Monetize > SETUP > SDK Networks.
2. Select Unity Ads from the list of available networks.
   
   
3. In the Account Settings modal, input the Organization core ID and Monetization Stats API key from Unity's Monetize Dashboard.

IronSource will automatically switch to call the new Unity reporting API.

1. In the AdMob dashboard, select Mediation from the left nav.
2. Select the AD SOURCES tab.
3. Locate Unity Ads in the waterfall list, then select Edit in the Network Credentials column.
   
   
4. In the edit modal, input the Organization core ID and Monetization Stats API key from Unity's Monetize Dashboard.

AdMob will automatically switch to call the new Unity reporting API.

For additional questions regarding migration, please contact support.

Note: The Applifier API is supported, but will be deprecated in the future. Unity recommends migrating to the new API.

The Applifier API works in two stages:

1. The user performs a GET request to an authentication server. After successful authentication, the server responds with a 302 HTTP redirect message, which contains the final URL to the statistics server.
2. When the user performs a GET request to the signed URL, the server responds with the requested data in the body of the message in CSV format.

The API uses a key from the Developer Dashboard. To find it:

1. From the Monetize Dashboard, ensure that you are viewing your Organization dashboard (in other words, no specific Project is selected).
2. Select Ad Data Export on the left navigation bar to expand its options, then select API Access.

You must include the API Key in the authentication GET request, as the apikey parameter.

After successful authentication, the server responds with a 302 HTTP redirect message. Obtain the redirect URL from the Location HTTP header.

The redirect URL fetches the data. This is standard HTTP behavior that is supported by all HTTP clients. For example, the following request directly outputs the file to the console:

curl -L 
"https://gameads-admin.applifier.com/stats/monetization-api?apikey=APIKEY" 

To retrieve data from the statistics server, you must use a valid URL signature. If the authentication fails, the authentication server responds with an HTTP/1.1 200 OK header, and an error message in the body:

{"error":"Authentication error","responseCode":500,"status":"error"}

The monetization statistics API supports the following request format:

https://gameads-admin.applifier.com/stats/monetization-api?apikey=<apikey>&fields=<fields>[&splitBy=<splitbyfields>][&scale=<scale>][&start=<startDate>][&end=<endDate>][&sourceIds=<sourceIds>]

For Example:

curl -L 
"https://gameads-admin.applifier.com/stats/monetization-api?apikey=a0db664ac99b65cb4h1825e878e06472477dd067752dbeec828cb3b14vb723ee&splitBy=zone,country&fields=adrequests,available,views,revenue&start=2016-01-01&end=2016-10-01&scale=day&sourceIds=1003843" > ~/Desktop/UnityAdsMonetization.csv

To split your data, specify the following parameters:

Note: Splitting data across multiple dimensions causes the CSV to grow exponentially, which might cause some large data sets to time-out. The request times out if the server takes more than 60 seconds to process the request.

For additional questions regarding the Applifier API, please contact support.

The game client makes an ad request to the Unity Ads network during SDK initialization. If an ad is available, the ad caches and the server tallies a received request. When a player views the cached ad, the game client sends a new request.

An ad start counts when a video begins playing. This is more commonly called an impression. The quality of impressions generated by your game dictates how much revenue you earn.

An available ad refers to a successful response to an ad request.

eCPM is the average revenue your game earns per 1000 impressions. This value depends on the bids of the ads shown in your game and their overall performance; you can think of it as a general representation of how valuable your ad space is to advertisers.

Fill rate is the rate of available ads served divided by the number of ad requests. Unity Ads generally has a 95%+ fill rate, though several factors such as region and player base may mitigate this.

Unity Ads has a global fill rate of greater than 95%, but some regions outside of America and Europe that might have smaller ad pools won't always have ads available. It's important to check whether ads are available before showing ads to your users.

For more tips on maximizing impressions, see the best practices guide.

Impressions indicate the number of times an ad is fetched from the server, and tally every time a video begins playing. Impressions earn revenue, however, the quality of impressions vary (see section on interpreting the data, below).

A view counts when a player watches a video ad to completion.

The following section details some useful relationships between data points to consider.

Test mode may cause this issue. Check to ensure you’ve disabled it.

This number reflects a blend of the volume and quality of impressions your game provides; consider reviewing your integration design and marketing strategy. The following user interaction types are listed in escalating order of quality and earning potential:

1. Ad start (the player triggers an ad)
2. Completed view (the player watches an ad to the end)
3. Click (the player clicks the ad, leading to an external product link)
4. Install (the player clicks out to the external product page and installs the product)

Keep this in mind as you consider your monetization strategy. Please review our best practices guide for more integration tips.

A low ad requests ratio can indicate that the Ads SDK is initializing more often than users are viewing ads in your game. An ad request counts when the SDK initializes using your Game ID and requests an ad from the network, which returns an ad for caching. If those ads are never viewed, consider the following tweaks to your integration design:

• Provide increased or more prominent opportunities for players to view ads.
• Provide stronger incentives for players to opt into rewarded ads.

Please review our Best practices guide for more integration tips.

Double-check that the Ads Delivery Service is turned on, and that you’re calling the correct Game ID when initializing Ads.