Rewarded

Rewarded ads (also known as rewarded video ads) are a fullscreen format, but unlike interstitials, the user is incentivized to watch its entire duration (usually 30 seconds) in order to get an in-app reward, such as in-game currency, extra lives or hints to pass a level.

The didEarnReward callback will be triggered by the adapted network, signaling that you can give the user their reward. If the user decides to skip the ad, this callback will not be called.

Start loading an ad

SwiftObjective-C

import XMediator

XMediatorAds.startWith(appKey: "<your-app-key>") { result in
    XMediatorAds.rewarded.load(placementId: "<placement-id>")
}

@import XMediatorObjC;

[X3MXMediatorAds startWithAppKey:@"<your-app-key>"
                        callback:^(NSError * _Nullable error) {
    [X3MXMediatorAds.rewarded loadWithPlacementId:@"<placement-id>"];
}];

Presenting an ad

Calling isReady() will return if there's a rewarded ad available to be shown, regardless of its placement id. If multiple ads with different placement ids were previously loaded, the SDK will try to show the best one available.

SwiftObjective-C

if XMediatorAds.rewarded.isReady() {
    XMediatorAds.rewarded.present(fromViewController: self, fromAdSpace: "rewarded-ad-space")
}

if (X3MXMediatorAds.rewarded.isReady) {
    [X3MXMediatorAds.rewarded presentFromViewController:self.delegate.viewController fromAdSpace:@"rewarded-ad-space"];
}

Presenting an ad with placementId

When the app needs to present an ad for a specific placement id, isReady(withPlacementId:) and present(withPlacementId:) can be alternatively used.

SwiftObjective-C

if XMediatorAds.rewarded.isReady(withPlacementId: "<placement-id>") {
    XMediatorAds.rewarded.present(withPlacementId: "<placement-id>", fromViewController: self, fromAdSpace: "rewarded-ad-space")
}

if ([X3MXMediatorAds.rewarded isReadyWithPlacementId:@"<placement-id>"]) {
    [X3MXMediatorAds.rewarded presentWithPlacementId:@"<placement-id>" fromViewController:self fromAdSpace:@"rewarded-ad-space"];
}

Built-in features

Auto loading

Dismissed or failed to show ads will automatically trigger a new load request.

Auto retry

Failed to load ads will make a retry attempts, with an exponential backoff.

Additional settings

Register ad callbacks

Every ad callback indicates the placement id of the rewarded ad that triggered the event.

SwiftObjective-C

// Assign a delegate to handle the ad callbacks
XMediatorAds.rewarded.addDelegate(self)

// [...]

func didLoad(placementId: String, result: LoadResult) {
    print("Rewarded loaded! placementId: \(placementId)")
}

func didPresent(placementId: String) {
    print("Rewarded is being presented! placementId: \(placementId)")
}

func failedToPresent(placementId: String, error: PresentError) {
    // If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
    print("Rewarded failed to present. placementId: \(placementId), Reason: \(error.localizedDescription)")
}

func didRecordImpression(placementId: String, data: ImpressionData) {
    print("Rewarded impression, with revenue: \(data.revenue). placementId: \(placementId)")
}

func willDismiss(placementId: String) {
    print("Rewarded will be dismissed! placementId: \(placementId)")
}

func didDismiss(placementId: String) {
    // If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
    print("Rewarded dismissed! placementId: \(placementId)")
}

func didClick(placementId: String) {
    print("Rewarded clicked! placementId: \(placementId)")
}

// Reward Callback
func didEarnReward(placementId: String) {
    print("Rewarded ad earned a reward! placementId: \(placementId)")
}

// Assign a delegate to handle the ad callbacks
[X3MXMediatorAds.rewarded addDelegate:self];

// [...]

- (void)didLoadWithPlacementId:(NSString * _Nonnull)placementId result:(X3MLoadResult * _Nonnull)result {
    NSLog(@"Rewarded loaded! placementId: %@", placementId);
}

- (void)didPresentWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded is being presented! placementId: %@", placementId);
}

- (void)failedToPresentWithPlacementId:(NSString * _Nonnull)placementId error:(NSError * _Nonnull)error {
    // If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
    NSLog(@"Rewarded failed to present. placementId: %@. Reason %@", placementId, error);
}

- (void)didRecordImpressionWithPlacementId:(NSString * _Nonnull)placementId data:(X3MImpressionData * _Nonnull)data {
    NSLog(@"Rewarded impression, with revenue: %f. PlacementId %@", data.revenue, placementId);
}

- (void)willDismissWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded will be dismissed! placementId: %@", placementId);
}

- (void)didDismissWithPlacementId:(NSString * _Nonnull)placementId {
    // If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
    NSLog(@"Rewarded dismissed! placementId: %@", placementId);
}

- (void)didClickWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded clicked! placementId: %@", placementId);
}

- (void)didEarnRewardWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded ad earned a reward! placementId: %@", placementId);
}

Advanced use cases

This guide provides the recommended integration steps to show a rewarded ad using X3M, which covers most of the common scenarios. For advanced use cases, where manually handling the lifecycle of the ad object is needed, refer to this section.

Code example

SwiftObjective-C

RewardedViewController.swift

import UIKit
import XMediator

class RewardedViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
    }

    @IBAction func startButtonTouchUpInside(_ sender: Any) {
        XMediatorAds.startWith(appKey: "<your-app-key>") { result in
            XMediatorAds.rewarded.addDelegate(self)

            // Start loading a rewarded ad. Subsequent loads or retries are handled by the sdk
            XMediatorAds.rewarded.load(placementId: "<placement-id>")
        }
    }

    @IBAction func presentButtonTouchUpInside(_ sender: Any) {
        if XMediatorAds.rewarded.isReady() {
            XMediatorAds.rewarded.present(fromViewController: self)
        }
    }
}

extension RewardedViewController: RewardedAdsDelegate {
    func didLoad(placementId: String, result: LoadResult) {
        print("Rewarded loaded! placementId: \(placementId)")
    }

    func didPresent(placementId: String) {
        print("Rewarded is being presented! placementId: \(placementId)")
    }

    func failedToPresent(placementId: String, error: PresentError) {
        // If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
        print("Rewarded failed to present. placementId: \(placementId), Reason: \(error.localizedDescription)")
    }

    func didRecordImpression(placementId: String, data: ImpressionData) {
        print("Rewarded impression, with revenue: \(data.revenue). placementId: \(placementId)")
    }

    func willDismiss(placementId: String) {
        print("Rewarded will be dismissed! placementId: \(placementId)")
    }

    func didDismiss(placementId: String) {
        // If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
        print("Rewarded dismissed! placementId: \(placementId)")
    }

    func didClick(placementId: String) {
        print("Rewarded clicked! placementId: \(placementId)")
    }

    func didEarnReward(placementId: String) {
        print("Rewarded ad earned a reward! placementId: \(placementId)")
    }
}

RewardedViewController.m

@import UIKit;
@import XMediatorObjC;

@interface RewardedViewController ()<X3MRewardedAdsDelegate>
@end

@implementation RewardedViewController

- (void)viewDidLoad {
    [super viewDidLoad];
}

- (IBAction)startButtonTouchUpInside:(id)sender {
    [X3MXMediatorAds startWithAppKey:@"<your-app-key>"
                            callback:^(NSError * _Nullable error) {
        [X3MXMediatorAds.rewarded addDelegate:self];

        // Start loading a rewarded ad. Subsequent loads or retries are handled by the sdk
        [X3MXMediatorAds.rewarded loadWithPlacementId:@"<placement-id>"];
    }];
}

- (IBAction)presentButtonTouchUpInside:(id)sender {
    if (X3MXMediatorAds.rewarded.isReady) {
        [X3MXMediatorAds.rewarded presentFromViewController:self];
    }
}

#pragma mark - Ads Delegate

- (void)didLoadWithPlacementId:(NSString * _Nonnull)placementId result:(X3MLoadResult * _Nonnull)result {
    NSLog(@"Rewarded loaded! placementId: %@", placementId);
}

- (void)didPresentWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded is being presented! placementId: %@", placementId);
}

- (void)failedToPresentWithPlacementId:(NSString * _Nonnull)placementId error:(NSError * _Nonnull)error {
    // If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
    NSLog(@"Rewarded failed to present. placementId: %@. Reason %@", placementId, error);
}

- (void)didRecordImpressionWithPlacementId:(NSString * _Nonnull)placementId data:(X3MImpressionData * _Nonnull)data {
    NSLog(@"Rewarded impression, with revenue: %f. PlacementId %@", data.revenue, placementId);
}

- (void)willDismissWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded will be dismissed! placementId: %@", placementId);
}

- (void)didDismissWithPlacementId:(NSString * _Nonnull)placementId {
    // If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
    NSLog(@"Rewarded dismissed! placementId: %@", placementId);
}

- (void)didClickWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded clicked! placementId: %@", placementId);
}

- (void)didEarnRewardWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Rewarded ad earned a reward! placementId: %@", placementId);
}

@end