Self-Rendering Ad Integration Notes

1. About Ad Material Object ATNativeAdOffer nativeAd

Since some ad platforms may not have all material information available, you may encounter null values when retrieving data. In this case, you need to pay attention to the successful display delegate callback. If the successful display callback is not triggered, the ad platform may consider it an invalid impression. You need to check whether UI materials are added or redesign the style layout to meet the requirements for successful display.

objc Copy

// Native ads displayed successfully
// Successful display delegate callback
- (void)didShowNativeAdInAdView:(ATNativeADView *)adView
                    placementID:(NSString *)placementID
                          extra:(NSDictionary *)extra;

2. Getting and Handling mediaView

objc Copy

    // Get mediaView
    UIView *mediaView = [nativeADView getMediaView];

    if (mediaView) {
        // Usually no need to bind mediaView to click events when there's video content
        //[clickableViewArray addObject:mediaView];
        
        mediaView.frame = CGRectMake(0, kNavigationBarHeight + 150.0f, kScreenW, kScreenH - kNavigationBarHeight - 150);
        // Add mediaView
        [selfRenderView addSubview:mediaView];
    }
   
    ......

    [nativeADView registerClickableViewArray:clickableViewArray];

Please execute the above mediaView retrieval operation. Whether there is a return value is determined by the ad platform.

When you don't retrieve mediaView, the following warning will appear in the console. When this warning is triggered, we will perform automatic fallback rendering. If you find discrepancies with your own layout code, please check the console log information.

The current integration is wrong, Please follow the document to integrate.

Possible reasons for the above integration error: not calling loadPrepareInfo, not calling getMediaView, ad offer is a template ad

If you don't want to add mediaView, you need to pay attention to whether there is a successful display callback after the ad is displayed to determine if it's a valid impression. If no callback is received, you need to add it and then observe again whether the display is successful.

3. Setting Ad Platform Logo

Due to requirements, TopOn SDK version 6.2.95 and later will internally add ad platform logo views within self-rendered native ad views.

3.1 Setting Layout

Code example:

objc Copy

1. Call to set preferred position after SDK initialization:
    [ATAPI sharedInstance].preferredAdLogoPosition = ATAdLogoPositionBottomRightCorner;

2. Adjust the logo position built into third-party ad platform SDKs

    ATNativeADConfiguration *config = [[ATNativeADConfiguration alloc] init];
    // Frame setting method, you can choose one from the Masonry setting method below
    config.logoViewFrame = CGRectMake(<#CGFloat x#>, <#CGFloat y#>, <#CGFloat width#>, <#CGFloat height#>);

    // Get native ad display container view
    ATNativeADView *nativeADView = [[ATNativeADView alloc] initWithConfiguration:config currentOffer:offer placementID:self.placementID];
    
   // Masonry method, choose one from the frame setting method above
    // Render ad
    [offer rendererWithConfiguration:config selfRenderView:selfRenderView nativeADView:nativeADView];
    
    // Precisely set logo size and position (Masonry method), choose one from the manual layout method above, call after rendering ad
    [nativeADView.logoImageView mas_remakeConstraints:^(MASConstraintMaker *make) {
        make.right.bottom.mas_equalTo(nativeADView).mas_offset(-10);
        make.width.height.mas_equalTo(20);
    }];
    // Call after Masonry precise logo setting
    [nativeADView setNeedsLayout];
    // Call after Masonry precise logo setting
    [nativeADView layoutIfNeeded];

3. Set logo contained in native ad materials. When logoUrl or logo has value, it can be set through layout in SelfRenderView
@implementation SelfRenderView
    if (self.nativeAdOffer.nativeAd.logoUrl.length) {
        ATDemoLog(@"🔥----logoUrl:%@",self.nativeAdOffer.nativeAd.logoUrl);
        [self.logoImageView sd_setImageWithURL:[NSURL URLWithString:self.nativeAdOffer.nativeAd.logoUrl]];
    } else if (self.nativeAdOffer.nativeAd.logo) {
        ATDemoLog(@"🔥----logo:%@",self.nativeAdOffer.nativeAd.logo);
        self.logoImageView.image = self.nativeAdOffer.nativeAd.logo;
    } else { // All of these are nil, set the default platform logo using networkFirmID. If all are empty, you can manually set one based on platform ID
        if (self.nativeAdOffer.networkFirmID == 15) {//CSJ
            self.logoImageView.image = [UIImage imageNamed:@"tt_ad_logo_new"];
        }
    }

If you don't set custom layout, the SDK will internally set a fixed-size square area to display the logo based on [ATAPI sharedInstance].preferredAdLogoPosition; (may cause style stretching, in which case it's recommended to use the layout code above).

For some materials, the ad platform logo may be displayed in mediaView.

3.2 Hiding Logo

We recommend that you don't hide the logo images provided by ad platforms, as this may violate native ad specifications and affect your revenue.

objc Copy

// Get native ad display container view
ATNativeADView *nativeADView = [[ATNativeADView alloc] initWithConfiguration:config currentOffer:offer placementID:self.placementID];
// Render ad
[offer rendererWithConfiguration:config selfRenderView:selfRenderView nativeADView:nativeADView];
// Call after render
nativeADView.logoImageView.hidden = YES;

4. UI Element List

Reminder: When integrating native self-rendering due to different style requirements, pay close attention to whether there are display delegate callbacks after ad display to ensure the validity of ad display.

UI Material	Return Type	Description	Integration Recommendation
title	NSString	Ad title	Recommended
mainText	NSString	Ad description	Optional
ctaText	NSString	Ad CTA button text	Optional
advertiser	NSString	Advertiser name	Conditionally Required (Required for Yandex platform)
iconUrl	NSString	Ad icon url	Recommended
logoUrl	NSString	Ad platform logo url	Required
imageUrl	NSString	Large image url	Recommended
imageList	NSArray	Image array	Optional
mainImageWidth	CGFloat	Large image width	None
mainImageHeight	CGFloat	Large image height	None
icon	UIImage	Ad icon image	Recommended
logo	UIImage	Ad platform logo image	Required
mainImage	UIImage	Large image	Recommended (Native banner style needs to check display exposure callback)
isVideoContents	BOOL	Whether it's a video ad	None
videoUrl	NSString	Video url	Get getMediaView and add to view
videoDuration	NSInteger	Video duration	None
videoAspectRatio	CGFloat	Video aspect ratio	None
interactionType	NSInteger	Ad supported interaction type	None
mediaExt	NSDictionary	Media extension data	None
source	NSString	App source, market	None
rating	NSNumber	Ad rating	Optional
commentNum	NSInteger	Comment count	Optional
appSize	NSInteger	Ad app package size	Optional
appPrice	NSString	App purchase price	Optional
domain	NSString	Domain	Conditionally Required (Required for Yandex platform)
warning	NSString	Warning	Conditionally Required (Required for Yandex platform)

Video ads play videos through mediaView. You can get it through the following API. Some ad platforms display their coverImage in mediaView, while others display both mediaView and imageView simultaneously.

After some ad platforms finish playing videos, a mask layer will appear in mediaView. This may cause UI stretching. Ad platforms don't support setting the position and size of this mask, so you may need to redesign to avoid mask stretching.

objc Copy

// Get mediaView
UIView *mediaView = [nativeADView getMediaView];

5. Ad Platform Specification Requirement Examples

5.1 CSJ Feed Ads

CSJ needs to render titleLabel or textLabel
CSJ needs to render at least one image, i.e., needs to render iconImageView or mainImageView or mediaView
CSJ's AdLogo must be displayed

ATImageLoader: Provided by SDK for displaying network images (Optional)

Method	Parameters	Description
loadImageWithURL	(NSURL URL)	Display network image URL: Network image url

Native Ads

Advanced

Last modified: 2025-07-28Powered by

Outline