Native Placements

Native ads are different from inline and interstitial ads in that rather than being a single, self-contained entity from the perspective of a publisher, they are a collection of components that can be laid out and interacted with individually, so the publisher can control the user experience of each element of the ad along with its layout. Upon retrieving a Native Ad, the SDK returns an object that contains information about the ad along with a list of components that represent the contents of the ad.

Here is a list of the supported native ad components.

  • NativeTextComponent - This is a view that contains text.
  • NativeImageComponent - This is a view that contains an image.
  • NativeVideoComponent - This is a view that contains a video.

Different types of Native Ads may contain different components. In order to know the components that are available in an ad, the Ad Type must be known, Ad Type can be requested using the following method:

Language Method
Android String getAdType()
Kotlin adType: String!
iOS (NSString*) adType
Swift adType: String

Native Types and Definitions

“simpleImage”

Native Ad Type “simpleImage” is the most common type of native ad. The components listed in the Advertiser Required section below must be displayed in order to get credit for an ad impression.

Component ID Component Type Advertiser Required
“title” NativeTextComponent Yes
“body” NativeTextComponent No
“iconImage” NativeImageComponent No
“mainImage” NativeImageComponent Yes
“callToAction” NativeTextComponent Yes
“rating” NativeTextComponent No
“disclaimer” NativeTextComponent Yes

“simpleVideo”

Native Ad Type “simpleVideo” are native ads that contain a video. The components listed in the Advertiser Required section below must be displayed in order to get credit for an ad impression.

Component ID Component Type Advertiser Required
“title” NativeTextComponent Yes
“body” NativeTextComponent No
“iconImage” NativeImageComponent No
“video” NativeVideoComponent Yes
“callToAction” NativeTextComponent Yes
“rating” NativeTextComponent No

Accessing Components

All components are accessed with the same method, regardless of their type. You can cast them to a more specific type after retrieving them if needed.

Accessing Native Components

Component  getComponent(final Context context, final String componentId)
fun getComponent(context: Context!, componentId: String!): Component!
- (nullable id<YASComponent>)component:(NSString *)componentId;
func component(componentId : String) -> YASComponent?

Accessing Components for ‘simpleImage’ and ‘simpleVideo’ Native Ads

The following are examples of accessing some of the components found in Native Ads. Note that the video component will only be available for “simpleVideo” type creatives. Please refer to the sample application for examples of implementing a Native Ad within an App.

NativeTextComponent callToAction = (NativeTextComponent) nativeAd.getComponent(context, "callToAction");
NativeTextComponent title = (NativeTextComponent) nativeAd.getComponent(context, "title");
NativeImageComponent icon = (NativeImageComponent) nativeAd.getComponent(context, "iconImage");
NativeVideoComponent video = (NativeVideoComponent) nativeAd.getComponent(NativeActivity.this, "video");
val callToAction = nativeAd!!.getComponent(context, "callToAction") as? NativeTextComponent
val title = nativeAd!!.getComponent(context, "title") as? NativeTextComponent
val icon = nativeAd!!.getComponent(context, "iconImage") as? YASNativeImageComponent
val video = nativeAd!!.getComponent(context, "video") as? NativeVideoComponent
id<YASNativeTextComponent> ctaComponent = (id<YASNativeTextComponent>)[nativeAd component:@"callToAction"];
id<YASNativeTextComponent> titleComponent = (id<YASNativeTextComponent>)[nativeAd component:@"title"];
id<YASNativeImageComponent> iconComponent = (id<YASNativeImageComponent>)[nativeAd component:@"iconImage"];
id<YASNativeVideoComponent> videoComponent = (id<YASNativeVideoComponent>)[nativeAd component:@"video"];
let ctaComponent = nativeAd.component("callToAction") as? YASNativeTextComponent
let titleComponent = nativeAd.component("title") as? YASNativeTextComponent
let iconComponent = nativeAd.component("iconImage") as? YASNativeImageComponent
let videoComponent = nativeAd.component("video") as? YASNativeVideoComponent

Integrating Native Ad Placements

To add a native ad to an app, follow the steps below.

1. Import the required classes

//Required Yahoo Mobile SDK imports for native ads
import com.yahoo.ads.Component;
import com.yahoo.ads.ErrorInfo;
import com.yahoo.ads.nativeplacement.NativeAd;
import com.yahoo.ads.nativeplacement.NativePlacementConfig;
import com.yahoo.ads.yahoonativecontroller.NativeImageComponent;
import com.yahoo.ads.yahoonativecontroller.NativeTextComponent;
//Required Yahoo Mobile SDK imports for native ads
import com.yahoo.ads.Component
import com.yahoo.ads.ErrorInfo
import com.yahoo.ads.nativeplacement.NativeAd
import com.yahoo.ads.nativeplacement.NativePlacementConfig
import com.yahoo.ads.yahoonativecontroller.NativeImageComponent
import com.yahoo.ads.yahoonativecontroller.NativeTextComponent
//Required Yahoo Mobile SDK imports for native ads
#import <YahooAds/YahooAds.h>
//Required Yahoo Mobile SDK imports for native ads
import YahooAds

2. Create a native ad placement configuration

An instance of the native placement config is required to load an ad. The config is created once, typically when the app’s activity or view controller is created.

// Create placement config required to load the ad
String[] adTypes = new String[]{"simpleImage", "simpleVideo"};
NativePlacementConfig nativePlacementConfig = new NativePlacementConfig(PLACEMENT_ID, null, adTypes);
// Create placement config required to load the ad
val adTypes = arrayOf("simpleImage", "simpleVideo")
val placementConfig = NativePlacementConfig(PLACEMENT_ID, null, adTypes)
// Create placement config required to load the ad
YASNativePlacementConfig *nativeConfig = [[YASNativePlacementConfig alloc] initWithPlacementId:placementID requestMetadata:nil nativeAdTypes:@[@"simpleImage", @"simpleVideo"]];
// Create placement config required to load the ad
let nativeConfig = YASNativePlacementConfig(placementId: placementID,
                                            requestMetadata: nil,
                                            nativeAdTypes: ["simpleImage", "simpleVideo"])

3. Load and show an ad

Create an instance of a NativeAd, then load the assets for that ad

// Instantiate NativeAd and Listen for Native Ad callbacks
NativeAd nativeAd = new NativeAd(PLACEMENT_ID, nativeAdListener);
runOnUiThread(() -> {
    // Load the ad
    nativeAd.load(nativePlacementConfig);
});
// Instantiate NativeAd and Listen for Native Ad callbacks
val nativeAd = NativeAd(PLACEMENT_ID, nativeAdListener)
runOnUiThread {
    // Load the ad
    nativeAd.load(nativePlacementConfig)
}
// Instantiate a YASNativeAd
YASNativeAd *nativeAd = [[YASNativeAd alloc] initWithPlacementId:placementID];
// Retain the ad object
self.nativeAd = nativeAd;
// Listen for native ad callbacks
self.nativeAd.delegate = self;
// Load the ad
[self.nativeAd loadWithPlacementConfig:nativeConfig];
// Instantiate a YASNativeAd
let nativeAd = YASNativeAd(placementId: placementID)
// Retain the ad object
self.nativeAd = nativeAd
// Listen for native ad callbacks
self.nativeAd.delegate = self
// Load the ad
self.nativeAd.load(with: nativeConfig)

Native ad callbacks

The Native ad callbacks provide the state of an ad that has been displayed. For example, callbacks can signal user actions or errors. Please refer to the API documentation for Android and iOS for a complete list of available callbacks.

//Native ad callbacks
@Override
public void onLoaded(final NativeAd nativeAd) {
    //Retrieve ad components
}

@Override
public void onLoadFailed(final NativeAd nativeAd, final ErrorInfo errorInfo) {
    // Handle load error
    Log.e(TAG, errorInfo.toString());
}

@Override
public void onClicked(final NativeAd nativeAd, final Component component) {
    Log.i(TAG, "Native ad was clicked");
}
//etc...
//Native ad callbacks
override fun onLoaded(nativeAd: NativeAd) {
    //Retrieve ad components
}

override fun onLoadFailed(nativeAd: NativeAd, errorInfo: ErrorInfo) {
    // Handle load error
    Log.e(TAG, errorInfo.toString())
}

override fun onClicked(nativeAd: NativeAd, component: Component) {
       Log.i(TAG, "Native ad was clicked")
}
//etc...
//Native ad callbacks
- (void)nativeAdDidLoad:(YASNativeAd *)nativeAd
{
    // Retrieve ad components
}

- (void)nativeAdLoadDidFail:(YASNativeAd *)nativeAd withError:(YASErrorInfo *)errorInfo
{
    // Handle load error
    NSLog(@"Native ad load did fail: %@", errorInfo);
}

-(void)nativeAdClicked:(nonnull YASNativeAd *)nativeAd withComponent:(nonnull id<YASComponent>)component
{
    NSLog(@"Native ad was clicked");
}
// etc...
//Native ad callbacks
func nativeAdDidLoad(_ nativeAd: YASNativeAd) {
    // Retrieve ad components
}

func nativeAdLoadDidFail(_ nativeAd: YASNativeAd, withError errorInfo: YASErrorInfo) {
    // Handle load errror
    print("Native ad load did fail: \(errorInfo)")
}

func nativeAdClicked(_ nativeAd:YASNativeAd, with component:YASComponent) {
    print("Native ad was clicked")
}
// etc...

4. Retrieve ad components

Once an Ad has been loaded successfully, components can be retrieved for subsequent display. The number, type of components, and structure of these will vary based on the Native Ad Type that is returned.

//Retrieve ad components
NativeTextComponent callToAction = (NativeTextComponent) nativeAd.getComponent(context, "callToAction");
NativeTextComponent title = (NativeTextComponent) nativeAd.getComponent(context, "title");
NativeImageComponent icon = (NativeImageComponent) nativeAd.getComponent(context, "iconImage");
// Etc...
//Retrieve ad components
val callToAction = nativeAd!!.getComponent(this, "callToAction") as? NativeTextComponent
val title = nativeAd!!.getComponent(this, "title") as? NativeTextComponent
val icon = nativeAd!!.getComponent(this, "iconImage") as? NativeImageComponent
// Etc...
//Retrieve ad components
id<YASNativeTextComponent> ctaComponent = (id<YASNativeTextComponent>)[nativeAd component:@"callToAction"];
id<YASNativeTextComponent> titleComponent = (id<YASNativeTextComponent>)[nativeAd component:@"title"];
id<YASNativeImageComponent> iconComponent = (id<YASNativeImageComponent>)[nativeAd component:@"iconImage"];
// etc.
//Retrieve ad components
let ctaComponent = nativeAd.component("callToAction") as? YASNativeTextComponent
let titleComponent = nativeAd.component("title") as? YASNativeTextComponent
let iconComponent = nativeAd.component("iconImage") as? YASNativeImageComponent
// etc...

5. Display the ad

Once the ad components have been retrieved, styling can be applied, and they can be laid out within the app. In order to retrieve the actual view for a component, you must call getView (Android) or access the view property (iOS) prior to attaching the view.

View callToActionView = callToActionTextComponent.getView(context);
val callToActionView = callToActionTextComponent?.getView(context)
UIView *view = ctaComponent.view;
let view = ctaComponent?.view

6. Register the Ad Container View

The Native Ad’s container view must be registered with the NativeAd instance in order to track impressions. To register the ad container view you must call registerContainerView with your view that has the Native Ad components (i.e. Main Image, Call to Action, etc.) as descendants. Impressions will not be counted if you do not register your container view or if your container view does not have all the Native Ad components as descendants.

boolean registered = nativeAd.registerContainerView(containerViewGroup);
val registered = nativeAd?.registerContainerView(containerViewGroup);
BOOL registered = [nativeAd registerContainerView:containerView];
let registered = nativeAd.registerContainerView(containerView)

7. Android Only - Destroy the ad

When the ad instance is no longer needed or when the activity is finished, the instance must be destroyed to free up resources.

//Destroy the ad
nativeAd.destroy()
//Destroy the ad
nativeAd?.destroy()

Next Steps

  • If you were able to successfully load an ad, congratulations! Now, step outside and get some fresh air.
  • If you would like a complete example of implementing an Native Ad within an app, please review the sample application.
  • If you are still having trouble, please contact your account manager.
©2023 Yahoo. All rights reserved.
Site last generated: Mar 7, 2023 13:23