Rewarded Ads

Loading a Rewarded Ad

To load a rewarded ad, get an instance of a MARewardedAd object that corresponds to your rewarded ad unit and then call its loadAd method. Implement MARewardedAdDelegate so that you are notified when your ad is ready and of other ad-related events.

  • #import "ExampleViewController.h"
    #import <AppLovinSDK/AppLovinSDK.h>
    
    @interface ExampleViewController()<MARewardedAdDelegate>
    @property (nonatomic, strong) MARewardedAd *rewardedAd;
    @property (nonatomic, assign) NSInteger retryAttempt;
    @end
    
    @implementation ExampleViewController
    
    - (void)createRewardedAd
    {
      self.rewardedAd = [MARewardedAd sharedWithAdUnitIdentifier: @"ad_unit_ID"];
      self.rewardedAd.delegate = self;
    
      // Load the first ad
      [self.rewardedAd loadAd];
    }
    
    #pragma mark - MAAdDelegate Protocol
    
    - (void)didLoadAd:(MAAd *)ad
    {
      // Rewarded ad is ready to show. '[self.rewardedAd isReady]' now returns 'YES'
    
      // Reset retry attempt
      self.retryAttempt = 0;
    }
    
    - (void)didFailToLoadAdForAdUnitIdentifier:(NSString *)adUnitIdentifier withError:(MAError *)error
    {
      // Rewarded ad failed to load
      // AppLovin recommends that you retry with exponentially higher delays up to a maximum delay (in this case 64 seconds)
    
      self.retryAttempt++;
      NSInteger delaySec = pow(2, MIN(6, self.retryAttempt));
    
      dispatch_after(dispatch_time(DISPATCH_TIME_NOW, delaySec * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
        [self.rewardedAd loadAd];
      });
    }
    
    - (void)didDisplayAd:(MAAd *)ad {}
    
    - (void)didClickAd:(MAAd *)ad {}
    
    - (void)didHideAd:(MAAd *)ad
    {
      // Rewarded ad is hidden. Pre-load the next ad
      [self.rewardedAd loadAd];
    }
    
    - (void)didFailToDisplayAd:(MAAd *)ad withError:(MAError *)error
    {
      // Rewarded ad failed to display. AppLovin recommends that you load the next ad.
      [self.rewardedAd loadAd];
    }
    
    #pragma mark - MARewardedAdDelegate Protocol
    
    - (void)didStartRewardedVideoForAd:(MAAd *)ad {}
    
    - (void)didCompleteRewardedVideoForAd:(MAAd *)ad {}
    
    - (void)didRewardUserForAd:(MAAd *)ad withReward:(MAReward *)reward
    {
      // Rewarded ad was displayed and user should receive the reward
    }
    
    @end
  • class ExampleViewController : UIViewController, MARewardedAdDelegate
    {
      var rewardedAd: MARewardedAd!
      var retryAttempt = 0.0
    
      func createRewardedAd()
      {
        rewardedAd = MARewardedAd.shared(withAdUnitIdentifier: "ad_unit_ID")
        rewardedAd.delegate = self
    
        // Load the first ad
        rewardedAd.load()
      }
    
      // MARK: MAAdDelegate Protocol
    
      func didLoad(_ ad: MAAd)
      {
        // Rewarded ad is ready to show. '[self.rewardedAd isReady]' now returns 'YES'.
    
        // Reset retry attempt
        retryAttempt = 0
      }
    
      func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError)
      {
        // Rewarded ad failed to load
        // AppLovin recommends that you retry with exponentially higher delays up to a maximum delay (in this case 64 seconds).
    
        retryAttempt += 1
        let delaySec = pow(2.0, min(6.0, retryAttempt))
    
        DispatchQueue.main.asyncAfter(deadline: .now() + delaySec) {
          self.rewardedAd.load()
        }
      }
    
      func didDisplay(_ ad: MAAd) {}
    
      func didClick(_ ad: MAAd) {}
    
      func didHide(_ ad: MAAd)
      {
        // Rewarded ad is hidden. Pre-load the next ad
        rewardedAd.load()
      }
    
      func didFail(toDisplay ad: MAAd, withError error: MAError)
      {
        // Rewarded ad failed to display. AppLovin recommends that you load the next ad.
        rewardedAd.load()
      }
    
      // MARK: MARewardedAdDelegate Protocol
    
      func didStartRewardedVideo(for ad: MAAd) {}
    
      func didCompleteRewardedVideo(for ad: MAAd) {}
    
      func didRewardUser(for ad: MAAd, with reward: MAReward)
      {
        // Rewarded ad was displayed and user should receive the reward
      }
    }

Showing a Rewarded Ad

To show a rewarded ad, call showAd on the MARewardedAd object you retrieved.

  • if ( [self.rewardedAd isReady] )
    {
      [self.rewardedAd showAd];
    }
  • if rewardedAd.isReady
    {
      rewardedAd.show()
    }

To prevent rewarded ad audio from interfering with your app’s background audio, AppLovin recommends that you stop your app’s background audio before you show an ad and then resume your app’s background audio after you hide the ad.

Accessing the Amount and Currency for a Rewarded Ad

To access the reward amount and currency, override the -[MARewardedAdDelegate didRewardUserForAd:withReward:] callback:

  • - (void)didRewardUserForAd:(MAAd *)ad withReward:(MAReward *)reward
    {
      NSLog(@"Rewarded user: %d %@", reward.amount, reward.label);
    }
  • func didRewardUser(for ad: MAAd, with reward: MAReward)
    {
      print("Rewarded user: \(reward.amount) \(reward.label)")
    }

S2S Rewarded Callbacks

AppLovin’s servers make server-to-server rewarded callbacks to an external server that you define, to notify that server that a user of your app completed a rewarded ad and so qualifies for a reward. This provides another layer of protection against malicious users who attempt to gain extra rewards without finishing rewarded ads.

Introduction

AppLovin can send (HTTP or HTTPS) GET requests to an external endpoint that you define, after the user completes a rewarded ad that is served via MAX mediation. AppLovin makes these callbacks soon after the ad completion, 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 callback times. If the callback receives a non-200 response code, AppLovin will retry the callback up to three more times: twice right away and then once more about 60 seconds later. The callback request times out if five seconds pass without a response. You can configure these callbacks by setting the value of Server Side Callback URL in the Edit Ad Unit page for any of your rewarded Ad Units.

Example

https://myrewardedserver.com/rewards?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 callback URL (as in the example URL above). These macro names will be replaced with accurate values at the time it makes the callback 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.

Setting an Ad Placement Name

See: Advanced Settings: Ad Placements

Setting an Internal User ID

If you want to tag users with your own internal User ID, do so with code like the following. The maximum size of the User ID string is 8192 characters.

  • [ALSdk shared].userIdentifier = @"user-id";
  • ALSdk.shared()!.userIdentifier = "user-id"

Custom Data

Starting in SDK version 11.0.0, you can tag data/postbacks with custom string data. Do this with the code like the following. AppLovin recommends that you keep the size of the string under 8192 characters.

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

Banners

  • adView.customData = @"custom data";
  • adView.customData = "custom data"

MRECs

  • adView.customData = @"custom data";
  • adView.customData = "custom data"

Interstitials

-[MAInterstitialAd showAdForPlacement:customData:]

Rewarded Ads

-[MARewardedAd showAdForPlacement:customData:]

Native Ads

  • nativeAdLoader.customData = @"my custom data";
  • nativeAdLoader.customData = "my custom data"