Native block Android

Reading time 15 min

VK Ad SDK provides the ability to display ads in your application using its own visual components.

The SDK downloads data and provides the application with an ad model with specific properties to populate the visual component, as well as methods for counting impressions and processing clicks.

The SDK also provides a built-in custom visual component that you can use in your application, instead of creating your own.

The native banner does not support MediaAdView and therefore cannot display media content (video, cards, large image).

Initialization

To display native banners in your application, you must create an instance of the NativeBannerAd class. To create an instance of NativeBannerAd, you must specify your slotId.

private NativeAd ad;

private void initAd()
{
// Turn on debug mode
// MyTargetManager.setDebugMode(true);

// Creating instance of NativeBannerAd
ad = new NativeAd(YOUR_SLOT_ID, this);
}

Loading ads

To receive notifications (such as a successful data download or a download error, click on an advertisement), you must create an instance of NativeBannerAdListener and set it as an event listener, after which you can start the data download.

private NativeAd ad;

private void initAd()
{
// Creating instance of NativeBannerAd
ad = new NativeAd(YOUR_SLOT_ID, this);

// add listener
ad.setListener(new NativeAd.NativeAdListener()
{
@Override
public void onLoad(NativePromoBanner banner, NativeAd ad)
{
}

@Override
public void onNoAd(String reason, NativeAd ad)
{
}

@Override
public void onClick(NativeAd ad)
{
}

@Override
public void onShow(NativeAd ad)
{
}

@Override
public void onVideoPlay(NativeAd ad)
{
}

@Override
public void onVideoPause(NativeAd ad)
{
}

@Override
public void onVideoComplete(NativeAd ad)
{
}
});

// Start loading data
ad.load();
}

Autoloading images

By default, all banner images are loaded and cached. You can turn off the automatic loading of images, but keep in mind that they will take extra time to load, which will create an additional delay in displaying ads in your application.

ad.setCachePolicy(CachePolicy.NONE);
ad.load();

Valid values are CachePolicy.ALL (by default), CachePolicy.IMAGE, CachePolicy.NONE.

If preloading is enabled, then the corresponding images will be loaded and cached in parallel with the loading of the main data of the advertising banner.

If the preloading of images is turned off, they will be asynchronously and automatically loaded when the registerView method is called. No additional action required.

Successful asset loading notifications

It is possible to put a listener to receive notifications about the successful loading of the icon image file in case of automatic loading.

ad.setMediaListener(new NativeAdMediaListener() {
@Override
public void onIconLoad(@NonNull NativeAd ad)
{
// notification of successful loading of the icon
}

@Override
public void onImageLoad(@NonNull NativeAd ad)
{
// notification of successful loading of the main image
}
});
ad.load();

Displaying ads

After successfully loading the data, you can use the properties of the resulting banner instance to populate your visual component. The availability of properties depends on the type of advertised object - for applications and sites they differ.

To display the icon, use the IconAdView provided by the SDK.

Visual components (both standard and proprietary) should be placed inside the NativeAdContainer container.
At the same time, both the component itself and the container can be passed to the registerView method.
When creating the container, the visual component adView will be added as a subview to the container and stretched to fit the container.

Elements of the visual component must be assigned the corresponding id supplied with the SDK.

Ad View Element	id
Root View (ваш AdView)	R.id.nativeads_ad_view
Advertising Label	R.id.nativeads_advertising
Title	R.id.nativeads_title
Description	R.id.nativeads_description
Rating	R.id.nativeads_rating
Domain	R.id.nativeads_domain
Age Restrictions	R.id.nativeads_age_restrictions
Disclaimer	R.id.nativeads_disclaimer
Call-to-Action	R.id.nativeads_call_to_action
Icon	R.id.nativeads_icon
MediaAdView	R.id.nativeads_media_view

After filling in the visual component, you must register it with the NativeAd instance using the registerView method.

If you intend to use the same visual component to display other advertisements, you must first call the unregisterView method on the current NativeAd instance before calling registerView on the other instance.

Processing impressions and clicks is carried out automatically, while the application should not block or intercept user events on this visual component. Available properties are described below and examples of filling visual components for various types of advertised objects are given.

@Override
public void onLoad(NativePromoBanner banner, NativeAd ad)
{
// Ad Title
String title = banner.getTitle();
// Main text
String description = banner.getDescription();
// Age restrictions. May be null
String ageRestrictions = banner.getAgeRestrictions();
// Disclamer. May be null
String disclaimer = banner.getDisclaimer();
// “Ad” disclaimer tag text
String advertisingLabel = banner.getAdvertisingLabel();

// Icon
ImageData icon = banner.getIcon();
// Text for the button
String ctaText = banner.getCtaText();
// Properties available only for ads that promote applications
if (banner.getNavigationType().equals(NavigationType.STORE))
{
// App Rating (0-5)
float rating = banner.getRating();
// Number of grades
int votes = banner.getVotes();
// Application Category
String category = banner.getCategory();
// Application Subcategory
String subcategory = banner.getSubcategory();
}
// Properties available only for ads that promote websites
else if (banner.getNavigationType().equals(NavigationType.WEB))
{
//Site domain
String domain = banner.getDomain();
}

// Example of filling a visual component
Context context = YourActivity.this;
LinearLayout adViewLayout = new LinearLayout(context);
adViewLayout.setId(R.id.nativeads_ad_view);
TextView titleView = new TextView(context);
titleView.setId(R.id.nativeads_title);
titleView.setText(title);
adViewLayout.addView(titleView);
TextView descriptionView = new TextView(context);
descriptionView.setId(R.id.nativeads_description);
titleView.setText(description);
adViewLayout.addView(descriptionView);
Button btn = new Button(context);
btn.setId(R.id.nativeads_call_to_action);
btn.setText(ctaText);
adViewLayout.addView(btn);

// Creating MediaAdView
MediaAdView mediaView = NativeViewsFactory.getMediaAdView(context);
mediaView.setId(R.id.nativeads_media_view);
// Creating IconAdView
IconAdView iconView = new IconAdView(context);
mediaView.setId(R.id.nativeads_icon);

adViewLayout.addView(mediaView);
adViewLayout.addView(iconView);

// Creating a container for creativity
NativeAdContainer nativeAdContainer = new NativeAdContainer(context);
// Adding advertising creative to the container
nativeAdContainer.addView(adViewLayout);

// Registering the visual component
ad.registerView(nativeAdContainer);

// Adding to the screen
mainLayout.addView(nativeAdContainer, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);
}

Native ad assets

The library contains both mandatory and optional elements. The rules of ad placement require only mandatory elements to be displayed.

However, layouts with a full set of components are more clickable, so we recommend using them.

Ad asset	Required
Advertising label	Yes
Age restrictions	Yes
Disclaimer	Yes
Domain	Yes
Title	Yes
Menu icon	Yes
Icon	Yes, for app ads
Call-to-action	Yes
MediaAdView	Yes
Description	No
Rating	No

Use a layout that displays the entire set of mandatory and optional ad components

Example of a native block for website advertising

Example of a native block for advertising mobile app

1 of 2

Example of a native block for website advertising

AdChoices icon

The VK Ad SDK automatically adds an adChoices icon to each visual component. By default, the icon is added to the top-right corner of the visual component, but you can choose your preferred corner with the adChoicesPlacement property:

...
ad.setAdChoicesPlacement(AdChoicesPlacement.TOP_RIGHT);
ad.load();

Manual setting of AdChoices

If you want to set your own image for AdChoices, you have to use the NativeAdChoicesView class and pass the image there using the setImageBitmap() or setImageDrawable() methods.

...
NativeAdChoicesView myAdChoicesView = createMyAdChoicesView(); // creating own NativeAdChoicesView
myAdChoicesView.setImageBitmap(bitmap);
myAdChoicesView.setImageDrawable(drawable);
...

In case manual positioning of AdChoicesView (setting gravity, margins) within its View is required to show native ads, AdChoicesPlacement.MANUAL must be specified.

...
ad.setAdChoicesPlacement(AdChoicesPlacement.MANUAL);
ad.load();

Customizing the AdChoices button

The developer can draw the AdChoices button himself as he wants, but in this case the AdChoicesPlacement.DRAWING_MANUAL property must be set for NativeBannerAd. You also need to call the ad.handleAdAdChoicesClick(context) method to handle clicking on the AdChoices.

...
ad.setAdChoicesPlacement(AdChoicesPlacement.DRAWING_MANUAL);
ad.load();
...
customAdChoicesView.setOnClickListener(v->{
ad.handleAdChoicesClick(context)
})

To get the AdChoices icon, you can call the ad object directly or use the NativeAdChoicesListener, the listener must be set before the ad is loaded.

//getting an AdChoises icon through a variable
ad.getBanner().getAdChoicesIcon();
...
//getting an AdChoises icon through the listener
ad.setAdChoicesListener(new NativeAd.NativeAdChoicesListener() {
@Override
public void onAdChoicesIconLoad(@Nullable ImageData imageData, boolean success, @NonNull NativeAd ad)
{
customAdChoicesView.setImageBitmap(imageData.getBitmap)
}
});

Customizing the rendering of AdChoices options

To change the design of drawing AdChoices options it's necessary in the NativeBannerAd constructor to pass an object implementing the MenuFactory interface, which in turn should return an object implementing the Menu interface.

MenuFactory menuFactory = new MenuFactory()
{
@Override
@NonNull public Menu createMenu()
{
return new Menu()
{
@Override
public void setListener(@Nullable Listener listener)
{
//the listener that needs to call the onActionClick(menuAction) method when you click on the UI element that was drawn with the corresponding menuAction title
}

@Override
public void addAction(@NonNull MenuAction menuAction)
{
// this is an object that contains the header and option type of AdChoices, these objects should be used when drawing
}

@Override
public void present(@NonNull Context context)
{
// this method is called when you want to display AdChoices options with those menuActions that were previously obtained from the addAction() method
}

@Override
public void dismiss()
{
// this method is called when it is necessary to close the rendering of the AdChoices options
}
};
}
};
...
ad = new NativeAd(YOUR_SLOT_ID, menuFactory, this);
ad.load();

Managing ad closures

In order to receive notifications about ad closures and manage ad closures, you need to pass an object that implements the NativeBannerAdChoicesOptionListener interface. The interface contains several methods.

boolean shouldCloseAutomatically() - informs SDK whether to automatically close ads. If the method returns true, the SDK will automatically hide the ads. If false, the ability to hide is left to the developer.
onCloseAutomatically() - notifies the developer that the ad has been automatically hidden by the SDK. So, this method will be called only if shouldCloseAutomatically returns true.
closeIfAutomaticallyDisabled() - notifies the developer that he needs to hide the ads himself. So this method will be called only if shouldCloseAutomatically returns false.

NativeAd.NativeAdChoicesOptionListener adChoicesOptionListener = new NativeAd.NativeAdChoicesOptionListener()
{
@Override
public boolean shouldCloseAutomatically()
{
return false;
}

@Override
public void onCloseAutomatically(@NonNull NativeBannerAd ad)
{

}

@Override
public void closeIfAutomaticallyDisabled(@NonNull NativeBannerAd ad)
{

}
};

ad.setAdChoicesOptionListener(adChoicesOptionListener);

Setting clickable area

In the above example, the visual component is registered using the registerView (View view) method. In this case, the entire area of the visual component is clickable. VK Ad SDK provides the ability to specify specific visual components that clicks will be tracked. To do this, use the registerView method (View view, List <View> clickableViews):

@Override
public void onLoad(NativePromoBanner banner, NativeAd ad)
{
...
...
...

// Create an array of clickable visual components, a title and a call to action button
ArrayList<View> clickableViews = new ArrayList<>();
clickableViews.add(titleView);
clickableViews.add(btn);
// Register the visual component, with a clickable title and a call to action button
ad.registerView(adViewLayout, clickableViews);

// Add to the screen
mainLayout.addView(adViewLayout, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);
}

Using a built-in visual component

VK Ad SDK provides a built-in custom visual component, the appearance of which you can customize to the design of your application.

The following are examples and the properties that are available for customization.

NativeAdView

public void onLoad(NativePromoBanner banner, NativeAd ad)
{
// Create a visual component
NativeAdView nativeAdView = NativeViewsFactory.getNativeAdView(ad, YourActivity.this);

// Customizable internal visual components
TextView advLabelView = nativeAdView.getAdvertisingTextView();
TextView ageRestrictionView = nativeAdView.getAgeRestrictionTextView();
TextView disclaimerView = nativeAdView.getDisclaimerTextView();
TextView titleView = nativeAdView.getTitleTextView();
TextView descriptionView = nativeAdView.getDescriptionTextView();
Button ctaBtn = nativeAdView.getCtaButtonView();
TextView votesView = nativeAdView.getVotesTextView();
StarsRatingView starsRatingView = nativeAdView.getStarsRatingView();
TextView domainView = nativeAdView.getDomainOrCategoryTextView();
MediaAdView mediaView = nativeAdView.getMediaAdView();
IconAdView iconView = nativeAdView.getIconImageView();

// Create a creative container
NativeAdContainer nativeAdContainer = new NativeAdContainer(context);
// Add ad creative to container
nativeAdContainer.addView(nativeAdView);

// Register the visual component
ad.registerView(nativeAdContainer);

// Add to the screen
mainLayout.addView(nativeAdContainer, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);
}

Loading of multiple banners

VK Ad SDK provides the NativeBannerAdLoader class, which makes it possible to load from 1 to 20 banners in one request. For NativeBannerAdLoader, you can configure all the same parameters that are available for setting in NativeBannerAd (for example, gender and age parameters of the user, autoload images and videos).

VK Ad SDK does not guarantee that the number of banners specified in the COUNT parameter will be loaded - this parameter indicates the maximum number of banners that you want to receive.

// Turn on debug mode
// MyTargetManager.setDebugMode(true);

// Creating NativeBannerAdLoader
NativeAdLoader nativeAdLoader = NativeAdLoader.newLoader(YOUR_SLOT_ID, COUNT, this);

// Install OnLoad callback and load banners
nativeAdLoader.setOnLoad(new OnLoad()
{
@Override
public void onLoad(@NonNull List<NativeAd> ads)
{
for (NativeAd ad : ads)
{
// add listener
ad.setListener(nativeAdListener);

NativePromoBanner promoBanner = ad.getBanner();
// Code similar to the onLoad method of the NativeAdListener interface
}
}
}).load();

The resulting array will contain from 0 to COUNT NativeBannerAd objects - each of them contains an already loaded NativeBanner and you need to work with each of them in the same way as described in this documentation above, starting with calling the onLoad method.