User-Level Ad Revenue API

Use this API to retrieve user-level revenue data. You can retrieve this data aggregated for a particular user or with one row per impression.

User-level revenue data is available eight hours after UTC day end. So, for example, data for UTC 2019-01-01 is available on UTC 2019-01-02 after 08:00.

You can share user-level and impression-level ad revenue data with your mobile measurement partner of choice, such as Adjust, AppsFlyer, GameAnalytics or Singular, for all supported networks. Starting in SDK version 10.3.0, you can also access impression-level user revenue data on the client side. You can read more about this in Platform > Overview > Advanced Settings.

See also

How to find your AppLovin SDK version.

There is also a Server-to-Server Impression Revenue API by which MAX posts data to a tracking URL of your choosing whenever it records a MAX impression. See the S2S Impression Revenue API documentation page for more information.

See also

• “Take Ad-Revenue Attribution to the Next Level With MAX” from AppLovin’s Blog
• “Three Ways You Can Measure User-Level Ad Revenue with MAX” from AppLovin’s Blog

Request Format

Note

You must authenticate to use this API. To do so, set the value of the URL parameter api_key to your Report Key.

Target URL

https://r.applovin.com/max/userAdRevenueReport?api_key=«report-key»&date=«report-day»&platform=«app-platform»&application=«app-package-name»&store_id=«app-store-ID»&aggregated=«is-aggregated»

Request Parameters

Name	Description	Example
aggregated	Whether the data should be aggregated (per user) or not (per impression). Defaults to true.	false
api_key	Report Key, for authentication.	tgCe3d7SFRU0S…304ZKs6ba
application	Application package name (for Android) or bundle ID (for iOS). (You cannot use this parameter if you define store_id)	com.mycompany.application
date†	Day to return data for, in «YYYY»-«MM»-«DD» format.	2019-02-06
platform	Application platform: android, fireos, or ios.	android
store_id	The numeric portion of the iTunes ID on iOS, or the app’s package name on Android. If you do not know the iTunes ID, use the bundle ID instead. You cannot use this parameter if you define application.	1207472156

^† This API has a request window of 45 days. Make sure the date parameters are within the last 45 days.

Response Format

Response Body

{
  "status": 200,
  "url": "https://applovin-externalreports.s3.amazonaws.com/%2Fmediation_reports/report_date%3D1549756800/pub_id%3D12345/mediation_app_id%3D12345/user_report.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190216T000208Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=dataio.amazon.s3.access_key%2F20190216%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=e45bdfbd88cbcf4e[…]927dd"
  "ad_revenue_report_url": "https://applovin-externalreports.s3.amazonaws.com/%2Fmediation_reports/report_date%3D1549756800/pub_id%3D12345/mediation_app_id%3D12345/user_report.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190216T000208Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=dataio.amazon.s3.access_key%2F20190216%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=e45bdfbd88cbcf4e[…]927dd"
}

Response Parameters

Name	Description
ad_revenue_report_url	Location of the CSV file with all revenue including estimated Meta Audience Network Bidding data.
fb_estimated_revenue_url	Location of the CSV file with only estimated Meta Audience Network Bidding data. Please note that these numbers may differ from actuals since Meta Audience Network Bidding data is calculated using estimated revenue data. This option is only available on aggregated requests.
status	Status of the request: 200 if a user report can be accessed.
url	Location of the CSV file that excludes estimated Meta Bidding data.

User-Level Revenue Data CSV Format

Examples

Aggregated

Ad Unit ID,Placement,IDFA,IDFV,User Id,Impressions,Revenue
da39a3ee5e6b4b0,home_screen,04034992-E5AA-4BA1-890C-5075B2504050,4F2A07BC-315B-11E9-B210-D663BD873D93,20349,27,5.000025
da39a3ee5e6b4b0,level_end,12309422-331C-41A3-9BF5-2D7D1C04A4E0,4F2A0A6E-315B-11E9-B210-AD023491FF20,,11,0.006100

Non Aggregated (Impression Level)

Date,Ad Unit ID,Ad Unit Name,Waterfall,Ad Format,Placement,Country,Device Type,IDFA,IDFV,User ID,Revenue, Ad Placement
2019-07-29 15:53:07.39,97f7d2048121fe62,sc-and-v1,Default Waterfall,BANNER,home-screen,gb,PHONE,34d5d192-4d67-4382-a730-6828a5f769a2,,e41aaf1d-72ea-4c02-8543-27a2ba09a258,0.000079,1642799
2019-07-29 15:49:31.468,97f7d2048121fe62,sc-and-v1,LAT Users,BANNER,level-end,de,TABLET,31dae586-12d9-47dc-99bd-80855feb2afd,,cf-3042e652059847e5b0911dca682e9509,0.006000,202009

Fields

Name	Description
Ad Format	INTER, BANNER, REWARD (Non-Aggregated only).
Ad Placement	The placement ID of the external ad network that showed the ad (Non-Aggregated only).
Ad Unit ID	ID of the MAX Ad Unit from which the revenue was generated.
Ad Unit Name	Name of the MAX Ad Unit from which the revenue was generated (Non-Aggregated Only).
Country	The two-letter country code of the impression (Non-Aggregated only).
Custom Data	Custom data passed in from the integration.
Date	Time of the impression (Non-Aggregated only).
Device Type	PHONE, TABLET (Non-Aggregated only).
IDFA	Advertising identifier: IDFA for iOS devices, GAID for Android devices.
IDFV	Identifier for vendor.
Impressions	The number of ads displayed to the user (Aggregated only).
Network	The Ad Network that generated the impression. Ad Network values can be found in the “Network API Name” column of this table. (Non-Aggregated ad_revenue_report_url Only)
Placement	The Ad Placement Name where the user generated impressions and revenue.
Revenue	The revenue generated by the user, in USD, expressed with six-decimal precision.
User ID	Optional ID of the user, set via the AppLovin SDK. (See the “Setting an Internal User ID” section below.)
Waterfall	MAX ad unit waterfall name (Non-Aggregated only).

Setting an Ad Placement Name

The following code snippets show you how you can add a placement name to an ad unit. The value of the placement name replaces the {PLACEMENT} macro in postback requests:

ActionScript

Banners

AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

MRECs

AppLovinMAX.setMRecPlacement(«ad-unit-ID», «placement»);

Interstitials

AppLovinMAX.showInterstitial(«ad-unit-ID», «placement»);

Native Ads

nativeAdLoader.setPlacement(«placement»);

Rewarded Ads

AppLovinMAX.showRewardedAd(«ad-unit-ID», «placement»);

Blueprint

Banners

MRECs

Interstitials

Rewarded Ads

C++

Banners

UAppLovinMAX::CreateBanner(«ad-unit-ID», «position»);
UAppLovinMAX::SetBannerPlacement(«ad-unit-ID», «placement»);

MRECs

UAppLovinMAX::CreateMRec(«ad-unit-ID», «position»);
UAppLovinMAX::SetMRecPlacement(«ad-unit-ID», «placement»);

Interstitials

UAppLovinMAX::ShowInterstitial(«ad-unit-ID», «placement»);

Rewarded Ads

UAppLovinMAX::ShowInterstitial(«ad-unit-ID», «placement»);

C#

Banners

MaxSdk.CreateBanner(«ad-unit-ID», «position»);
MaxSdk.SetBannerPlacement(«ad-unit-ID», "«placement»");

MRECs

MaxSdk.CreateMRec(«ad-unit-ID», «position»);
MaxSdk.SetMRecPlacement(«ad-unit-ID», "«placement»");

Interstitials

MaxSdk.ShowInterstitial(«ad-unit-ID», "«placement»");

Rewarded Ads

MaxSdk.ShowRewardedAd(«ad-unit-ID», "«placement»");

Dart

Banners

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

MRECs

AppLovinMAX.createMRec(«ad-unit-ID», «position»);
AppLovinMAX.setMRecPlacement(«ad-unit-ID», «placement»);

Interstitials

AppLovinMAX.showInterstitial(«ad-unit-ID», placement: «placement»);

Rewarded Ads

AppLovinMAX.showRewardedAd(«ad-unit-ID», placement: «placement»);

GDScript

Banners

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.set_banner_placement(«ad-unit-ID», «placement»);

MRECs

AppLovinMAX.createMRec(«ad-unit-ID», «position»);
AppLovinMAX.set_mrec_placement(«ad-unit-ID», «placement»);

Interstitials

AppLovinMAX.show_interstitial(«ad-unit-ID», «placement»);

Rewarded Ads

AppLovinMAX.show_rewarded_ad(«ad-unit-ID», «placement»);

Java

Banners

adViewAd.setPlacement( "«placement»" );

Interstitials

interstitial.showAd( "«placement»" );

Rewarded Ads

rewardedAd.showAd( "«placement»" );

Native Ads

nativeAdLoader.setPlacement( "«placement»" );

Native Ads (Ad Placer)

MaxAdPlacerSettings settings = new MaxAdPlacerSettings( "«ad-unit-ID»" );
settings.setPlacement( "«placement»" );

JavaScript (Cordova)

Banners

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

MRECs

AppLovinMAX.createMRec(«ad-unit-ID», «position»);
AppLovinMAX.setMRecPlacement(«ad-unit-ID», «placement»);

Interstitials

AppLovinMAX.showInterstitial(«ad-unit-ID», «placement»);

Rewarded Ads

AppLovinMAX.showRewardedAd(«ad-unit-ID», «placement»);

JavaScript (React Native)

Banners (Programmatic)

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

Banners (Native UI Component)

import { AdView, AdFormat } from 'react-native-applovin-max';
⋮
<AdView adUnitId={«ad-unit-ID»}
        adFormat={AdFormat.BANNER}
        placement={«placement»} />

MRECs (Programmatic)

import { MRecAd } from 'react-native-applovin-max';
⋮
MRecAd.createAd(«ad-unit-ID», «position»);
MRecAd.setPlacement(«ad-unit-ID», «placement»);

MRECs (Native UI Component)

import { AdView, AdFormat } from 'react-native-applovin-max';
⋮
<AdView adUnitId={«ad-unit-ID»}
        adFormat={AdFormat.MREC}
        placement={«placement»} />

Interstitials

import { InterstitialAd } from 'react-native-applovin-max';
⋮
InterstitialAd.showAd(«ad-unit-ID», "«placement»");

Rewarded Ads

import { RewardedAd } from 'react-native-applovin-max';
⋮
RewardedAd.showAd(«ad-unit-ID», "«placement»");

Native Ads

<NativeAdView
  adUnitId={«ad-unit-ID»}
  placement="«placement»"
  ⋮
/>

Kotlin

Banners

adView.setPlacement( "«placement»" )

Interstitials

interstitial.showAd( "«placement»" )

Rewarded Ads

rewardedAd.showAd( "«placement»" )

Native Ads

nativeAdLoader.setPlacement( "«placement»" )

Native Ads (Ad Placer)

val settings = MaxAdPlacerSettings( "«ad-unit-ID»" )
settings.placement = "«placement»"

Lua

Banners

applovin.create_banner(«ad-unit-ID», «position»)
applovin.set_banner_placement(«ad-unit-ID», «placement»)

MRECs

applovin.create_mrec(«ad-unit-ID», «position»)
applovin.set_mrec_placement(«ad-unit-ID», «placement»)

Interstitials

applovin.show_interstitial(«ad-unit-ID», «placement»);

Rewarded Ads

applovin.show_rewarded_ad(«ad-unit-ID», «placement»);

Objective-C

Banners

adView.placement = @"«placement»";
[adView loadAd];

Interstitials

[interstitialAd showAdForPlacement: @"«placement»"];

Rewarded Ads

[rewardedAd showAdForPlacement: @"«placement»"];

Native Ads

nativeAdLoader.placement = @"«placement»";

Native Ads (Ad Placer)

MAAdPlacerSettings *settings = [MAAdPlacerSettings settingsWithAdUnitIdentifier: @"«ad-unit-ID»"];
settings.placement = @"«placement»";

Swift

Banners

adView.placement = "«placement»"
adView.loadAd()

Interstitials

interstitial.show(forPlacement: "«placement»")

Rewarded Ads

rewardedAd.show(forPlacement: "«placement»")

Native Ads

nativeAdLoader.placement = "«placement»"

Native Ads (Ad Placer)

let settings = MAAdPlacerSettings(adUnitIdentifier: "«ad-unit-ID»")
settings.placement = @"«placement»"

Setting an Internal User ID

The following code snippets show how to tag users with your own internal User ID. The maximum size of the User ID string is 8192 characters.

ActionScript

AppLovinMAX.setUserId("«user-ID»");

C#

MaxSdk.SetUserId("«user-ID»");

Java

AppLovinSdkInitializationConfiguration.builder( "«SDK-key»", this )
   ⋮
   .configureSettings( settings -> {
     settings.setUserIdentifier( "«user-ID»" );
   }).build();

JavaScript

AppLovinMAX.setUserId("«user-ID»");

Kotlin

AppLovinSdkInitializationConfiguration.builder( "«SDK-key»", this )
   ⋮
   .configureSettings { settings ->
     settings.userIdentifier = "«user-ID»"
   }.build();

Lua

applovin.set_user_id("«user-ID»")

Objective-C

ALSdkInitializationConfiguration *initConfig = [ALSdkInitializationConfiguration configurationWithSdkKey: @"«SDK-key»" builderBlock:^(ALSdkInitializationConfigurationBuilder *builder) {
  ⋮
  builder.settings.userIdentifier = @"«user-ID»";
}];

Swift

let initConfig = ALSdkInitializationConfiguration(sdkKey: "«SDK-key»") { builder in
  ⋮
  builder.settings.userIdentifier = "«user-ID»"
}

Custom Data

The following code snippets show you how to add custom String data to postbacks. This String data replaces the {CUSTOM_DATA} macro in these postbacks. AppLovin recommends that your string contain fewer than 8192 characters.

Note

You must set custom data before you load a banner ad or MREC ad. Otherwise that data will not appear in the postbacks associated with the ad.

Banners & MRECs

C#

MaxSdk.SetBannerCustomData("«ad-unit-ID»", "«custom-data»"); // Banners
MaxSdk.SetMRecCustomData("«ad-unit-ID»", "«custom-data»"); // MRECs

Java

adViewAd.setCustomData( "«custom-data»" );

JavaScript

BannerAd.setCustomData("«ad-unit-ID»", "«custom-data»"); // Banners
MRec.setCustomData("«ad-unit-ID»", "«custom-data»"); // MRECs

Kotlin

adView.setCustomData( "«custom-data»" )

Objective-C

adView.customData = @"«custom-data»";

Swift

adView.customData = "«custom-data»"

Interstitials

C#

MaxSdk.ShowInterstitial(«adUnitIdentifier», «placement», «custom data»);

Java

MaxInterstitialAd.showAd(«placement», «custom data»);

JavaScript

InterstitialAd.showAd(interAdUnitId, "«placement»", "«custom data»");

Kotlin

MaxInterstitialAd.showAd(«placement», «custom data»)

Objective-C

-[MAInterstitialAd showAdForPlacement:customData:]

Swift

[interstitialAd showAdForPlacement: @"«placement»" customData: @"«custom-data»"];

Rewarded Ads

C#

MaxSdk.ShowRewardedAd(«adUnitIdentifier», «placement», «custom data»);

Java

MaxRewardedAd.showAd(«placement», «custom data»);

JavaScript

RewardedAd.showAd(adUnitId, "«placement»", "«custom data»");

Kotlin

MaxRewardedAd.showAd(«placement», «custom data»)

Objective-C

-[MARewardedAd showAdForPlacement:customData:]

Swift

rewardedAd.show(forPlacement: "«placement»" customData: "«custom-data»")

Native Ads

Java

nativeAdLoader.setCustomData( "«custom data»" );

JavaScript

<NativeAdView
  adUnitId={«ad-unit-ID»}
  customData="«custom-data»"
  ⋮
/>

Kotlin

nativeAdLoader.setCustomData( "«custom data»" )

Objective-C

nativeAdLoader.customData = @"«custom data»";

Swift

nativeAdLoader.customData = "«custom data»"