Rewarded Ads

Loading a Rewarded Ad

The following code shows you how to attach listeners and load the first rewarded ad:

const REWARDED_AD_UNIT_IDS = {
  "android" : "android_rewarded_ad_unit_ID"
  "ios" : "ios_rewarded_ad_unit_ID",
}

func _initialize_rewarded_ads():
  var platform = OS.get_name().to_lower() # "android", "ios", etc.
  var ad_unit_id = adUnitsDict.get(platform)  

  var rewarded_listener = AppLovinMAX.RewardedAdEventListener.new()
  rewarded_listener.on_ad_loaded = Callable(self, "_on_rewarded_ad_loaded")
  rewarded_listener.on_ad_load_failed = Callable(self, "_on_rewarded_ad_load_failed")
  rewarded_listener.on_ad_displayed = Callable(self, "_on_rewarded_ad_displayed")
  rewarded_listener.on_ad_display_failed = Callable(self, "_on_rewarded_ad_display_failed")
  rewarded_listener.on_ad_clicked = Callable(self, "_on_rewarded_ad_clicked")
  rewarded_listener.on_ad_received_reward = Callable(self, "_on_rewarded_ad_received_reward")
  rewarded_listener.on_ad_hidden = Callable(self, "_on_rewarded_ad_hidden")
  AppLovinMAX.set_rewarded_ad_listener(rewarded_listener)

func _load_rewarded_ad():
  var platform = OS.get_name().to_lower() # "android", "ios", etc.
  var ad_unit_id = adUnitsDict.get(platform)
    
  AppLovinMAX.load_rewarded_ad(ad_unit_id)

### Rewarded Ad Callbacks

func _on_rewarded_ad_loaded(ad_unit_id: String, ad_info: AppLovinMAX.AdInfo):
  # Rewarded ad is ready to be shown. AppLovinMAX.is_rewarded_ad_ready(ad_unit_id) will now return 'true'
  print("Rewarded ad loaded from" + ad_info.network_name)
    
func _on_rewarded_ad_load_failed(ad_unit_id: String, errorInfo: AppLovinMAX.ErrorInfo):
  ⋮
    
func _on_rewarded_ad_displayed(ad_unit_id: String, ad_info: AppLovinMAX.AdInfo):
  ⋮
    
func _on_rewarded_ad_display_failed(ad_unit_id: String, errorInfo: AppLovinMAX.ErrorInfo, ad_info: AppLovinMAX.AdInfo):
  ⋮
    
func _on_rewarded_ad_clicked(ad_unit_id: String, ad_info: AppLovinMAX.AdInfo):
  ⋮

func _on_rewarded_ad_received_reward(ad_unit_id: String, ad_info: AppLovinMAX.AdInfo, reward: AppLovinMAX.Reward):
  ⋮
    
func _on_rewarded_ad_hidden(ad_unit_id: String, ad_info: AppLovinMAX.AdInfo):
  ⋮

Showing a Rewarded Ad

To show a rewarded ad, call ShowRewardedAd():

var platform = OS.get_name().to_lower() # "android", "ios", etc.
var ad_unit_id = REWARDED_AD_UNIT_IDS.get(platform)  

if AppLovinMAX.is_rewarded_ad_ready(ad_unit_id):
    AppLovinMAX.show_rewarded_ad(ad_unit_id)

S2S Rewarded Callbacks

To learn how to receive callbacks to your currency server, see the MAX S2S Rewarded Callback API guide and update the S2S Rewarded Callback URL in your Edit Ad Unit page.

Impression-level revenue data helps you better understand your users, calculate ROI precisely, and build accurate LTV models. MAX gives you revenue information associated with each impression, as well as information about the demand source and the creative served for supported networks.

You can either process the data directly yourself, or work with any of our supported analytics providers, which are listed in the “MMP Integration: MAX to MMP” section of this page.

Direct Integration: MAX to You

There are three ways you can get user-level revenue data:

User Revenue API

Use this API to retrieve user-level revenue data on a daily basis. You can retrieve this data aggregated for a particular user or with one row per impression. Data is available eight hours after UTC day end. Read more about it on the User Revenue API documentation page.

Client-Side

Starting in SDK version 10.3.0+, you can access impression-level user revenue data on the client side in real-time. You can find integration instructions in the Advanced Settings page.

Server-to-Server

If you want to access real-time revenue data on the server side, you can provide an impression postback to track impression-level user ad revenue data. Please contact your account team or the support team to enable this feature. This feature and the macros that the impression postback supports are described in the “Server-to-Server Impression Revenue API” section of this page.

MMP Integration: MAX to MMP

MAX partners with various analytics solutions to help you easily access your data in a single dashboard. You can work with any of our supported partners such as Adjust, GameAnalytics, AppsFlyer, or Singular to access impression-level ad revenue or aggregated ad revenue data. Please refer to the documentation pages maintained by those partners for more information.

Server-to-Server Impression Revenue API

Please contact your account team or the support team to enable this feature.

AppLovin can send (HTTP or HTTPS) GET requests, from its servers to an external endpoint that you define, whenever a MAX impression is recorded. AppLovin makes these postbacks soon after the impression, but they may be delayed by up to a few minutes. You can use an impression timestamp macro to reconcile any delay between the impression and the postback times.

If the postback receives a non-200 response code, AppLovin will retry the postback up to three more times: twice right away and then once more about 60 seconds later. The postback request will timeout if five seconds pass without a response.

Example

https://myimpressionserver.com/impression?idfa={IDFA}&user_id={USER_ID}&event={EVENT_ID}&token={EVENT_TOKEN}

Available Macros

You can incorporate any of the macros in the following table into your postback URL (as in the example URL above). AppLovin’s servers will replace these macro names with accurate values at the time it makes the postback to your server.

Name Description Example
{AD_UNIT_ID} MAX Ad Unit ID (16 hex characters) 9ad0816ac071552a
{AD_UNIT_NAME} Ad Unit name (URL-encoded) My%20App%20Banners
{AD_UNIT_TEST_NAME} Name of the ad unit test, URL-encoded Control
{ALL_REVENUE} Estimated revenue, including FB Bidding estimates 0.0121, 5.74466e-05
{CC} Two-letter country code of the user gb
{CURRENCY} The type of currency you choose to award the user (URL-encoded). You set this in the Ad Unit edit page for each Ad Unit. coins
{CUSTOM_DATA} Custom data passed in from the integration (URL-encoded). AppLovin recommends that you keep the size of the string under 8192 characters. my%20custom%20data
{DEVICE_TYPE} User’s device type. Tablet
{EVENT_ID} Unique event ID, 40 hex characters 8dc948013d71f04264b8e5c1c61933154b226e08
{EVENT_TOKEN} sha1( EVENT_ID + Your_Event_Key ) e000949f6d851c1f34adae08e6ef1076ba43cf31
{EVENT_TOKEN_ALL} sha256( All macros alphabetically, URL-decoded + Your_Event_Key )

If EVENT_TOKEN is one of your macros, it is omitted from the “All macros alphabetically” string.

eba615583ed59bc679a495ec58439f4b82b5460d822348eff6be5f218702a97a
{FORMAT} Ad Unit format reward, banner, inter
{IDFA} iOS IDFA or Google Advertising ID 860635ea-65bc-eaed-d355-1b5283b30b94
{IDFV} Identifier for Vendor 4CD1C3C4-3FD7-00F5-1635-7BC6D9387E60
{IP} User’s IP address (IPv6 values are URL-encoded) 162.1.1.1, fe80%3A%3A1ff%3Afe23%3A4567%3A890a%0A
{NETWORK} Name of the ad network that served the impression. Names should match the names used in the ManagementAPI. APPLOVIN_NETWORK
{NETWORK_PLACEMENT} Placement name of the external ad network ca-app-pub-12345678%2F0987654321
{PACKAGE_NAME} App Package Name (Android) or Bundle ID (iOS). URL-encoded. com.test.app
{PLACEMENT} Publisher-defined MAX ad placement name (URL-encoded) Launch%20Screen
{PLATFORM} Platform android, ios
{PRECISION} Information on how precise the revenue value is. Options are:
publisher_defined
if revenue is the price assigned to the line item by the publisher
exact
if revenue is the resulting price of a real-time auction
estimated
if the revenue amount is based on Auto CPM or FB Bidding estimates
undefined
if no line item amount is defined and there is not enough data to estimate
exact
{REVENUE} Estimated revenue. Set to 0 when FB Bidding. 0.0121, 5.74466e-05
{TS} Timestamp of impression (integer, seconds since epoch) 1546300800
{USER_ID} Publisher-defined, URL-encoded, user ID; maximum length is 8192 characters 7634657898
{WATERFALL_NAME} The name of the Ad Unit waterfall LAT

Setting the Reward Amount and Currency

To set the reward amount and currency, click Add S2S Reward Callback in your Edit Ad Unit page:

Ad Type: ☐App Open, ☐Banner, ☐Interstitial, ☐MREC, ☐Native, ☑Rewarded. Add S2S Reward Callback.

Add the Server Side Callback URL, Reward Amount, and Rewarded Currency Name:

Ad Type: ☐App Open, ☐Banner, ☐Interstitial, ☐MREC, ☐Native, ☑Rewarded. Hide Callback Settings. Server Side Callback URL form field. Reward Amount form field. Rewarded Currency Name form field. AppLovin Event Key form field.