Menu

Video Streaming Ad

1. Introduction

The TopOn iOS SDK v6.3.35 began supporting video streaming ads. Video streaming ads are played in a separate video player on top of the app's content video player. You control the content video playback, while the SDK handles the ad playback. The ad is played in a separate video player on top of the app's content video player. The specific rendering style is as follows:

2. API Description

2.1 Ad Loading

ATAdManager: The management class for Rewarded Video ads.

Method Description
- (void)loadADWithPlacementID:(NSString *)placementID extra:(NSDictionary *)extra controlDataParam:(NSDictionary * _Nullable)param playhead:(id _Nullable)playhead delegate:(idATMediaVideoDelegate>)delegate mediaVideoContainerView:(UIView *)containerView viewController:(UIViewController *)viewController placementID: Ad placement. controlDataParam: Parameters controlling the ad; see code example for details. playhead: If using IMA, this is the IMAAVPlayerContentPlayhead object. delegate: Callback object. mediaVideoContainerView: Ad playback container. viewController: ViewController for navigation.

Sample code:

Copy
#import 
#import 
// Load Rewarded Video ad
  - (void)loadAd {
    NSMutableDictionary *extra = @{}.mutableCopy;
    // Open in internal browser
    extra[kATAdMediaVideoExtraKeyInternalBrowser] = @YES;
    // Hide countdown
    extra[kATAdMediaVideoExtraKeyHideCountDown] = @NO;
    // Video ad load timeout duration
    extra[kATAdMediaVideoExtraKeyLoadVideoTimeout] = @8;
    // Whether the ad should auto-play; only effective for VMAP
    extra[kATAdMediaVideoExtraKeyAutoPlayAdBreaks] = @NO;
    // Disable current playback info
    extra[kATAdMediaVideoExtraKeyDisableNowPlayingInfo] = @YES;
    
    self.videoView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, self.view.bounds.size.width, 300)];
    self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
    [[ATAdManager sharedManager] loadADWithPlacementID:@"your rv placementId" extra:extra controlDataParam:@{@"your key":@"your url"} playhead:self.contentPlayhead delegate:self mediaVideoContainerView:self.videoView viewController:self];

}
Method Description
- (ATMediaVideoOffer*)mediaVideoObjectWithPlacementID:(NSString*)placementID showConfig:(ATShowConfig * _Nullable)showConfig; If you need the offer object, you can obtain it from this method.

ATMediaVideoOffer**:** The display operation class for MediaVideo streaming ads, obtained through the above method.

Method Description
- (void)showWithPlacementID:(NSString *)placementID; Display the ad.
- (id)customNetworkObj; Get the platform ad object.
- (void)start; Start playing the ad.
- (void)pause; Pause the ad.
- (void)resume; Resume the ad.
- (void)destory; Destroy the ad.
- (void)contentComplete; Content playback finished.

Sample code:

Copy
- (void)showMediaVideoAd {
    [_offer destory];
    _offer = nil;

    ATShowConfig *showConfig = ATShowConfig.new;
    showConfig.showCustomExt = @"testShowCustomExt";
    self.offer = [[ATAdManager sharedManager] mediaVideoObjectWithPlacementID:self.currentPlacementIDInfoModel.placementIDString showConfig:showConfig];
    [self.offer showWithPlacementID:self.currentPlacementIDInfoModel.placementIDString];
}
Copy

2.4 Delegate Protocol Callbacks

ATAdLoadingDelegate delegate methods

Method Description
didFinishLoadingADWithPlacementID: Callback for successful ad load for the corresponding placement. placementId: Placement ID.
didFailToLoadADWithPlacementID: error: Callback for failed ad load for the corresponding placement. placementId: Placement ID. error: Ad load failure information.
didStartLoadingADSourceWithPlacementID: extra: Callback for when a specific ad source within the placement starts loading the ad. placementId: Placement ID. extra: Ad extra parameters.
didFinishLoadingADSourceWithPlacementID: extra: Callback for when a specific ad source within the placement successfully loads the ad. placementId: Placement ID. extra: Ad extra parameters.
didFailToLoadADSourceWithPlacementID: extra: error: Callback for when a specific ad source within the placement fails to load the ad. placementId: Placement ID. extra: Ad extra parameters. error: Ad load failure information.
didStartBiddingADSourceWithPlacementID: extra: Callback for when a specific bidding ad source within the placement starts bidding. placementId: Placement ID. extra: Ad extra parameters.
didFinishBiddingADSourceWithPlacementID: extra: Callback for when a specific bidding ad source within the placement successfully completes bidding. placementId: Placement ID. extra: Ad extra parameters.
didFailBiddingADSourceWithPlacementID: extra: error: Callback for when a specific bidding ad source within the placement fails bidding. placementId: Placement ID. extra: Ad extra parameters. error: Bidding ad failure information.

ATMediaVideoDelegate delegate methods

Callback Function Callback Function Meaning
- (void)mediaVideoDidStartPlayingForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; ad play starts
- (void)mediaVideoDidEndPlayingForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad playback ended
- (void)mediaVideoDidFailToPlayForPlacementID:(NSString *)placementID error:(NSError *)error extra:(NSDictionary *)extra; Ad playback failed
- (void)mediaVideoDidClickForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad clicked
- (void)mediaVideoAdPauseForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad paused
- (void)mediaVideoAdResumeForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad resumed
- (void)mediaVideoAdSkipedForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad skipped
- (void)mediaVideoAdForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra event:(id)event; Ad event callback
- (void)mediaVideoAdTappedForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad video area tapped
- (void)mediaVideoAdDidProgressForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra mediaTime:(NSTimeInterval)mediaTime totalTime:(NSTimeInterval)totalTime; Ad playback progress
- (void)mediaVideoAdDidStartBufferingForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad started buffering
- (void)mediaVideoAdDidBufferToMediaTimeForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra mediaTime:(NSTimeInterval)mediaTime; Ad buffered
- (void)mediaVideoAdPlaybackReadyForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Ad is ready
- (void)mediaVideoAdRequestContentPauseForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Request content pause
- (void)mediaVideoAdRequestContentResumeForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Request content resume
- (void)mediaVideoAdBreakReadyForPlacementID:(NSString *)placementID extra:(NSDictionary *)extra; Returns the IMA kIMAAdEvent_AD_BREAK_READY event

2.4 Other API Descriptions

  • For video streaming ads, you can obtain the custom extra content passed in when requesting the ad cache through the callback information.
  • The ad cache (MediaVideoAd) obtained by getMediaVideoAd is bound to the ATVideoAdPlayer object passed in during the request.

3. Sample Code

For details, refer to ATMediaVideoViewController.m in the Demo.

Copy
- (IMAAVPlayerContentPlayhead *)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];

  // Set up our content playhead and contentComplete callback.
    IMAAVPlayerContentPlayhead *contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
    return contentPlayhead;
}

- (void)loadAd {
    
    [[ATAPI sharedInstance] setCustomData:self.currentPlacementIDInfoRuleModel.groupRuleDic forPlacementID:self.currentPlacementIDInfoModel.placementIDString];

    if (!self.videoView.superview) {
        [self.view addSubview:self.videoView];
        self.contentPlayhead = [self setUpContentPlayer];
    }
    
    [self.contentPlayer seekToTime:kCMTimeZero completionHandler:^(BOOL finished) {
        
    }];
    NSMutableDictionary *extra = @{}.mutableCopy;
    // Open in internal browser
    extra[kATAdMediaVideoExtraKeyInternalBrowserViewController] = self;
    // Hide countdown
    extra[kATAdMediaVideoExtraKeyHideCountDown] = @NO;
    // Video ad load timeout duration
    extra[kATAdMediaVideoExtraKeyLoadVideoTimeout] = @8;
    // Whether the ad should auto-play; only effective for VMAP
    extra[kATAdMediaVideoExtraKeyAutoPlayAdBreaks] = @NO;
    // Disable current playback info
    extra[kATAdMediaVideoExtraKeyDisableNowPlayingInfo] = @YES;
    
    [[ATAdManager sharedManager] loadADWithPlacementID:self.currentPlacementIDInfoModel.placementIDString extra:extra controlDataParam:@{@"description_url":@"description_url"} delegate:self mediaVideoContainerView:self.videoView viewController:self];
}

- (void)showAd {
    if (![[ATAdManager sharedManager] adReadyForPlacementID:self.currentPlacementIDInfoModel.placementIDString]) {
        return;
    }
    
    ATShowConfig *showConfig = [[ATShowConfig alloc] initWithScene:nil showCustomExt:@"testShowCustomExt"];
    self.offer = [[ATAdManager sharedManager] mediaVideoObjectWithPlacementID:self.currentPlacementIDInfoModel.placementIDString showConfig:showConfig delegate:self];
    
    [[ATAdManager sharedManager] entryMediaVideoScenarioWithPlacementID:self.currentPlacementIDInfoModel.placementIDString scene:@"11"];
    
    id customNetworkObj = [self.offer customNetworkObj];
    id adsManager = [self.offer adsManager];
    
    [self.contentPlayer seekToTime:kCMTimeZero completionHandler:^(BOOL finished) {
        
    }];
    
    UIView *myTransparentTapOverlay = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 300, 250)];
    myTransparentTapOverlay.backgroundColor = [UIColor yellowColor];
    UIButton *myPauseButton = [[UIButton alloc] initWithFrame:CGRectMake(0, 0, 50, 10)];
    // Substitute "myTransparentTapOverlay" and "myPauseButton" with the elements
    // you want to register as video controls overlays.
    // Make sure to register before ad playback starts.
    IMAFriendlyObstruction *overlayObstruction =
          [[IMAFriendlyObstruction alloc] initWithView:myTransparentTapOverlay
                                               purpose:IMAFriendlyObstructionPurposeNotVisible
                                        detailedReason:@"This overlay is transparent"];
    IMAFriendlyObstruction *pauseButtonObstruction =
          [[IMAFriendlyObstruction alloc] initWithView:myPauseButton
                                               purpose:IMAFriendlyObstructionPurposeMediaControls
                                        detailedReason:@"This is the video player pause button"];
    
    [self.offer registerFriendlyObstruction:overlayObstruction];
    [self.offer registerFriendlyObstruction:pauseButtonObstruction];
    [self.offer unregisterAllFriendlyObstructions];
    if (self.offer.type == ATMediaVideoOfferTypeVMAP) {
        [self.offer contentPlayhead:self.contentPlayhead];
    } else if (self.offer.type == ATMediaVideoOfferTypeVAST) {
        [self.offer start];
    }
}

Notes

  • Please manage the display and destruction logic of the mediaVideoContainerView parameter passed during load yourself to avoid confusion.
  • Please manage the destruction logic of the ATMediaVideoOffer object yourself to avoid confusion.
  • VMAP ads need to wait for the IMA Event AD_BREAK_READY to be triggered before calling ATMediaVideoOffer start to display the ad.
Previous
Self-Rendering Ad Integration Notes
Next
Callback Delegate Parameters
Last modified: 2026-07-08Powered by