Rewarded Ads

“What are Rewarded Video Ads?” from AppLovin’s Blog.

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.

Setting the Reward Amount and Currency

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

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

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"