Rewarded Video Ads

Rewarded Video Ad

1. Integration Suggestions

1.1 Display the Rewarded Video Ad

Before displaying, we recommend checking whether the ad is ready, and only display it after it is ready
If you need to display the ad in the callback for a successful Ad Placement load (didFinishLoadingADWithPlacementID), you must first check (UIApplicationState==UIApplicationStateActive) before calling the display method; otherwise, the ad may fail to display properly and affect revenue.

1.2 Ad Preloading

You can call the load method to request the ad ahead of the display scenario (for example, start loading the ad when UIApplicationState==UIApplicationStateActive after the app launches), so that you can display it quickly when you reach the scenario where the ad needs to be shown

1.3 Server-Side Callback

Rewarded Video supports the server-side callback reward delivery mechanism, and also supports the server-side callback feature of each ad platform. Please refer to Server-Side Reward
The custom parameters used by the client for server-side reward callbacks can be passed in when loading the ad, or when displaying the ad. One benefit of passing in custom parameters when displaying the ad is that it makes it easy to map the user ID to the reward. See Section 5 of this document for details.

1.4 Sample Code

For detailed Rewarded Video ad sample code, please refer to RewardedVC.m in the Demo

2. Load the Rewarded Video Ad

objc Copy

//Import the header file
#import <AnyThinkSDK/AnyThinkSDK.h>

@interface RewardedVC () <ATAdLoadingDelegate, ATRewardedVideoDelegate>

@property (nonatomic, assign) NSInteger retryAttempt; // Retry attempt counter

@end

@implementation RewardedVC

//Ad Placement ID
#define RewardedPlacementID @"b67f4ab93eb3a7"

//Scene ID, optional, can be generated in the backend. Pass an empty string if none
#define RewardedSceneID @""

#pragma mark - Load Ad
- (void)loadAd {

    NSMutableDictionary * loadConfigDict = [NSMutableDictionary dictionary];
    // Optional integration. The following key parameters are applicable to the ad platform's server-side reward verification and will be passed through
    [loadConfigDict setValue:@"media_val_RewardedVC" forKey:kATAdLoadingExtraMediaExtraKey];
    [loadConfigDict setValue:@"rv_test_user_id" forKey:kATAdLoadingExtraUserIDKey];
    [loadConfigDict setValue:@"reward_Name" forKey:kATAdLoadingExtraRewardNameKey];
    [loadConfigDict setValue:@3 forKey:kATAdLoadingExtraRewardAmountKey];
     
    // Initiate ad load
    [[ATAdManager sharedManager] loadADWithPlacementID:RewardedPlacementID extra:loadConfigDict delegate:self];
}

/// Ad Placement load completed
/// - Parameter placementID: Ad Placement ID
- (void)didFinishLoadingADWithPlacementID:(NSString *)placementID {
    // Reset retry attempts
    self.retryAttempt = 0;
}
 
/// Ad Placement load failed
/// - Parameters:
///   - placementID: Ad Placement ID
///   - error: Error info
- (void)didFailToLoadADWithPlacementID:(NSString *)placementID error:(NSError *)error { 
    // Retries have reached 3 times, no longer retry loading
    if (self.retryAttempt >= 3) {
       return;
    }
    self.retryAttempt++;
    
    // Calculate delay time: power of 2, maximum 8 seconds
    NSInteger delaySec = pow(2, MIN(3, self.retryAttempt));

    // Delayed retry loading ad
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, delaySec * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
        [self loadAd];
    });
}

3. Show the Rewarded Video Ad

Track Scene Reach Rate, presented in the backend under Data Report -> Funnel Analysis Report -> Reached Ad Scenario, called before displaying the ad.

objc Copy

#pragma mark - Show Ad
/// Show the ad
- (void)showAd {
    
    //Scene statistics feature, presented in the backend under Data Report -> Funnel Analysis Report -> Reached Ad Scenario, called before displaying the ad. Optional integration
    [[ATAdManager sharedManager] entryRewardedVideoScenarioWithPlacementID:RewardedPlacementID scene:RewardedSceneID];

    //Check whether it is ready
    if (![[ATAdManager sharedManager] rewardedVideoReadyForPlacementID:RewardedPlacementID]) {
        [self loadAd];
        return;
    }
    
    //Display config. Scene takes the backend Scene ID; pass an empty string if none. The showCustomExt parameter can take a custom parameter string
    ATShowConfig *config = [[ATShowConfig alloc] initWithScene:RewardedSceneID showCustomExt:@"testShowCustomExt"];
 
    //Show the ad
    [[ATAdManager sharedManager] showRewardedVideoWithPlacementID:RewardedPlacementID config:config inViewController:self delegate:self];
}

#pragma mark - ATRewardedVideoDelegate
/// Reward succeeded
/// - Parameters:
///   - placementID: Ad Placement ID
///   - extra: Extra info dictionary
- (void)rewardedVideoDidRewardSuccessForPlacemenID:(NSString *)placementID extra:(NSDictionary *)extra {}

/// Rewarded ad video started playing
/// - Parameters:
///   - placementID: Ad Placement ID
///   - extra: Extra info dictionary
- (void)rewardedVideoDidStartPlayingForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra {}
 
/// Rewarded ad video finished playing
/// - Parameters:
///   - placementID: Ad Placement ID
///   - extra: Extra info dictionary
- (void)rewardedVideoDidEndPlayingForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra {}

/// Rewarded ad video failed to play
/// - Parameters:
///   - placementID: Ad Placement ID
///   - error: Error info
///   - extra: Extra info dictionary
- (void)rewardedVideoDidFailToPlayForPlacementID:(NSString*)placementID error:(NSError *)error extra:(NSDictionary *)extra {
     // Preload
    [self loadAd];
}

/// Rewarded ad closed
/// - Parameters:
///   - placementID: Ad Placement ID
///   - rewarded: Whether the reward has succeeded; YES means the reward success has already been called back
///   - extra: Extra info dictionary
- (void)rewardedVideoDidCloseForPlacementID:(NSString *)placementID rewarded:(BOOL)rewarded extra:(NSDictionary *)extra {
    // Preload
    [self loadAd];
}
 
/// Rewarded ad clicked
/// - Parameters:
///   - placementID: Ad Placement ID
///   - extra: Extra info dictionary
- (void)rewardedVideoDidClickForPlacementID:(NSString*)placementID extra:(NSDictionary *)extra {}

/// Rewarded ad opened or jumped to the deep link page
/// - Parameters:
///   - placementID: Ad Placement ID
///   - extra: Ad Placement ID
///   - success: Whether it succeeded
- (void)rewardedVideoDidDeepLinkOrJumpForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra result:(BOOL)success {}

4. Deliver the Reward

This is done by registering the following delegate method in ATRewardedVideoDelegate

objc Copy

/// Reward delivery
- (void)rewardedVideoDidRewardSuccessForPlacemenID:(NSString *)placementID extra:(NSDictionary *)extra {
}

5. Passing Server-Side Reward Client Parameters

5.1 Passing In During Load

The methods and descriptions for passing in custom parameters when loading the ad are as follows:

Field Key	Description	Example Value	Type
`kATAdLoadingExtraMediaExtraKey`	Custom string	`@"media_val_RewardedVC"`	NSString
`kATAdLoadingExtraUserIDKey`	User ID	`@"rv_test_user_id"`	NSString
`kATAdLoadingExtraRewardNameKey`	Reward name	`@"reward_Name"`	NSString
`kATAdLoadingExtraRewardAmountKey`	Reward amount	`@3`	NSNumber

Code example:

ojbc Copy

NSMutableDictionary * loadConfigDict = [NSMutableDictionary dictionary];
// Optional integration. The following key parameters are applicable to the ad platform's server-side reward verification and will be passed through to the third-party ad platform SDK
[loadConfigDict setValue:@"media_val_RewardedVC" forKey:kATAdLoadingExtraMediaExtraKey];
[loadConfigDict setValue:@"rv_test_user_id" forKey:kATAdLoadingExtraUserIDKey];
[loadConfigDict setValue:@"reward_Name" forKey:kATAdLoadingExtraRewardNameKey];
[loadConfigDict setValue:@3 forKey:kATAdLoadingExtraRewardAmountKey];
 
// Initiate ad load
[[ATAdManager sharedManager] loadADWithPlacementID:RewardedPlacementID extra:loadConfigDict delegate:self];

5.2 Passing In During Display

objc Copy

//Display config. Scene takes the backend Scene ID; pass an empty string if none. The showCustomExt parameter can take a custom parameter string
ATShowConfig *config = [[ATShowConfig alloc] initWithScene:RewardedSceneID showCustomExt:@"testShowCustomExt"];

//Show the ad
[[ATAdManager sharedManager] showRewardedVideoWithPlacementID:RewardedPlacementID config:config inViewController:self delegate:self];

Note: When using TopOn server-side reward, if you need to pass in custom parameters during display, you need to add &ilrd={ilrd} to the reward callback URL configured in the backend, and the server parses the show_custom_ext field. If you choose to use showCustomExt of ATShowConfig to pass in custom parameters during display, you must also pass in parameters using our Key when loading the ad. The parameter content passed in during display can differ from that passed in during load; both will be sent to the server.

6. API Reference

Class Name/File Name	Introduction
ATAdManager	The base operation class for ads, including ad loading, ad filtering, scene statistics, and other features.
ATAdManager (RewardedVideo)	An operation extension for Rewarded Video ads, providing ad display, cache checking, checking whether the ad is ready, scene statistics, and other features. It also defines the Rewarded Video Extra keys.
ATAdLoadingDelegate	The base delegate callback declarations for ads, including Ad Placement-level and Ad Source-level load success or failure callbacks, as well as the bidding end and bidding failure callbacks for bidding Ad Sources.
ATRewardedVideoDelegate	The delegate callbacks for the Rewarded Video ad type, including display, click, close, etc.
ATSDKGlobalSetting	A general settings class, providing features such as clearing the ad cache in memory, custom traffic grouping settings, Test Mode, and setting third-party ad SDK-related info. It also declares some general properties.

7. Common Troubleshooting

8. Advanced Settings

Ad Scenario: Helps developers understand data such as impressions, clicks, and the ad Ready rate when reaching the ad scenario, along the ad scenario dimension.

Preset Strategy: By configuring a preset strategy, you can improve the ad loading performance on the first cold start.

AD Formats

Interstitial Ads

Last modified: 2026-07-09Powered by

Outline