Rewarded Ads

Integrate CloudX rewarded ads in iOS apps

@interface YourViewController () <CLXRewardedDelegate, CLXAdRevenueDelegate>
@property (nonatomic, strong) CLXRewarded *rewardedAd;
@property (nonatomic, assign) NSInteger retryAttempt;
@end

@implementation YourViewController

- (void)createRewardedAd {
    self.rewardedAd = [[CloudXCore shared] createRewardedWithAdUnitId:@"your-rewarded-ad-unit-id"];
    self.rewardedAd.delegate = self;
    self.rewardedAd.revenueDelegate = self;
    [self.rewardedAd load];
}

- (void)showRewardedAd {
    if (self.rewardedAd.isReady) {
        // Basic show
        [self.rewardedAd showFromViewController:self];

        // Or with optional placement and custom data for tracking
        // [self.rewardedAd showFromViewController:self placement:@"bonus_coins" customData:@"level:5,coins:100"];
    } else {
        NSLog(@"Rewarded ad not ready");
    }
}

- (void)dealloc {
    [self.rewardedAd destroy];
}

#pragma mark - CLXRewardedDelegate

- (void)didLoadAd:(CLXAd *)ad {
    NSLog(@"Rewarded ad loaded from %@", ad.networkName);
    self.retryAttempt = 0;
}

- (void)didFailToLoadAd:(NSString *)adUnitId error:(CLXError *)error {
    NSLog(@"Rewarded ad failed to load: %@", error.localizedDescription);
    self.retryAttempt++;
    NSTimeInterval delay = pow(2.0, MIN(5, self.retryAttempt));
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(delay * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
        [self.rewardedAd load];
    });
}

- (void)didDisplayAd:(CLXAd *)ad {
    NSLog(@"Rewarded ad displayed");
}

- (void)didFailToDisplayAd:(CLXAd *)ad error:(CLXError *)error {
    NSLog(@"Rewarded ad failed to display: %@", error.localizedDescription);
    [self.rewardedAd load];
}

- (void)didHideAd:(CLXAd *)ad {
    NSLog(@"Rewarded ad hidden");
    [self.rewardedAd load]; // Reload for next use
}

- (void)didClickAd:(CLXAd *)ad {
    NSLog(@"Rewarded ad clicked");
}

- (void)didRewardUserForAd:(CLXAd *)ad withReward:(CLXReward *)reward {
    NSLog(@"User rewarded: %ld %@", (long)reward.amount, reward.label);
    // Grant the reward to the user
}

#pragma mark - CLXAdRevenueDelegate

- (void)didPayRevenueForAd:(CLXAd *)ad {
    NSLog(@"Rewarded revenue: %@ from %@", ad.revenue, ad.networkName);
}

@end

Ad readiness

isReady is true from the moment an ad loads until you show it or destroy the ad object. An ad network can stop being able to show an ad without telling the SDK. isReady stays true in that case, and the problem is found when you call showFromViewController: (Swift show(from:)). If the network does report that its ad has expired, the ad is no longer ready.

  • If you show an ad the network can no longer show, didFailToDisplayAd:error: (Swift didFailToDisplay(_:error:)) fires and the ad is no longer ready. Call load to get a new ad.
  • In that case, if CloudX has enabled show recovery for your app and ad unit, the SDK loads a replacement and shows it instead. You receive the replacement’s display and revenue callbacks, and no didFailToDisplayAd:error:. If an expired-ad replacement is already loading, the SDK uses it, and didReloadExpiredAd:withNewAd: (Swift didReloadExpiredAd(_:with:)) fires before it is shown. If no replacement loads, or none is ready within the time limit CloudX sets, didFailToDisplayAd:error: fires.
  • If you call load while an ad is ready, no new request starts. didLoadAd: (Swift didLoad(_:)) fires at once with that ad.
  • A load call while an ad is showing runs after the ad closes. A load call while a show waits for a recovery replacement also runs after the show ends, and receives exactly one didLoadAd: or didFailToLoadAd:error:.

Expired ads

A loaded ad that is not shown before it expires is reloaded automatically on the same ad object. The current ad stays ready and can still be shown until the replacement is ready.

  • To be told when a replacement is ready, set an expirationDelegate. A replacement that loads on its own does not call didLoadAd: (Swift didLoad(_:)) again.
  • If you show the ad while the replacement loads, the replacement is kept. If it is ready when the ad closes, or no load comes before it is ready, it becomes ready on the ad object and the expirationDelegate is called then. If you call load after the ad closes while the replacement is still loading, that load runs its own request and gets didLoadAd:, and no expirationDelegate call follows for that replacement.
  • If you call load while the expired ad is still loaded, no new request starts. didLoadAd: fires at once with the expired ad. The replacement keeps loading, and didReloadExpiredAd:withNewAd: (Swift didReloadExpiredAd(_:with:)) is called when it is ready.
  • If the replacement fails to load while the expired ad is still loaded, didFailToLoadAd:error: (Swift didFailToLoadAd(_:error:)) fires and the ad is no longer ready. Reload and its retries are set per ad unit by CloudX, and retries are off by default, so one no-fill ends here. This is the normal outcome, not an integration error: call load again after a delay rather than in a tight loop.
// Add CLXAdExpirationDelegate to the protocols YourViewController adopts
self.rewardedAd.expirationDelegate = self;

- (void)didReloadExpiredAd:(CLXAd *)expiredAd withNewAd:(CLXAd *)newAd {
    NSLog(@"Expired rewarded ad replaced by an ad from %@", newAd.networkName);
}