Method signature
The method is meant to launch the cyclic search for banner ads in the game without them being displayed.
FAPI.invokeUIMethod("requestBannerAds")
Call example
function requestBannerAds() {
FAPI.invokeUIMethod("requestBannerAds")
}Principle of operation
This method launches the cyclic search for banner ads in games without them being displayed.
How to enable displaying of ads
- call the advertisement search method FAPI.invokeUIMethod(“requestBannerAds”);
- wait until this method finds the banner. If it finds an ad, a special callback with a notification on it will be returned;
- call the advertisement display method FAPI.invokeUIMethod(“showBannerAds”).
After that, the discovered banner will appear in the top or the bottom part of the screen.
Cyclic search and banner update
After the display of ads in the game has been enabled, you don’t have to update them on your side: the OK SDK does that.
From the moment the first discovered banner is displayed, the cyclic search and banner update is launched. They work as follows:
- a new banner is sought every 30 seconds (this time period may be changed in the future);
- if the banner was found via the repeated search, it will be updated automatically. The old banner will be replaced with a new one that will be displayed in the same position.
How to stop the cyclic search and the banner update
There are two ways to hide the banner:
- the user has closed it by pressing the special banner closing button;
- the banner hiding method FAPI.invokeUIMethod(“hideBannerAds”) has been called..
If the user closes the banner, it does not stop the cyclic search. It continues even after the user closed the banner. If a new banner will be found, it will appear in the same position as the banner hidden by the user before.
If the game closes the banner through the hiding method, the cyclic search stops. To continue searching, call the method FAPI.invokeUIMethod(“requestBannerAds”) again.
How views are counted
For banner ads, there are two types of ad view events:
- banner block view: an event when the banner block displayed on the user’s device screen. This includes repeated displays of advertisements found earlier in case if the user hid them, but the game initiated displaying them again. This is an information event meant to give you an opportunity to adjust the UI of the game in the moment when the banner block appears. When it happens, ad views on the basis of which the in-game income from banner ad views is calculated are not counted;
- banner ad view: an event when a new banner ad that appeared within the banner block on the user’s device screen is displayed for the first time. This is the event that is taken into consideration when calculating income from the game. This event is different from the previous one, because it is counted only when it is displayed for the first time per each advertisement banner.
Callback example
As a result of calling methods for all key events that happen to advertisement banners, you will receive callbacks.
Following events are registered:
- an ad was found;
- an ad was not found;
- a banner block was displayed (a service event, does not count as an ad view);
- an ad was displayed and counted (counts as an ad view, happens only when displaying the same banner for the first time);
- the user hid a banner ad;
- the user clicked a banner ad.
A callback for a case when the advertisement banner was found
method: “requestBannerAds”
result: “ok”
data: “ad_loaded”
A callback for a case when the advertisement banner was not found
method: “requestBannerAds”
result: “error”
data: “no_ads”
A callback for a case when the advertisement banner block was displayed
This event does not count as an ad view
method: “requestBannerAds”
result: “ok”
data: “banner_shown”
A callback for a case when the advertisement banner was displayed for the first time
This event counts as an ad view
method: “requestBannerAds”
result: “ok”
data: “ad_shown”
A callback for a case when the user hid the banner
method: “requestBannerAds”
result: “error”
data: “hidden_by_user”
A callback for a case when the user clicked the banner
method: “requestBannerAds”
result: “event”
data: “ad_clicked”
A callback for a case when the advertisement is not supported on the platform
method: “requestBannerAds”
result: “error”
data: “disabled”
A callback for a case when the advertisement is not supported on the user’s device
method: “requestBannerAds”
result: “error”
data: “not_supported”
Breakdown of advertisement errors on Android
A range of additional exceptions is supported on the Android platform. They will be returned to you in the following form: native ads failed: {error_code}.
The error_code parameter can have following values:
- -1: a limit of advertisement call frequency has been reached. You cannot call the method more than once per 30 seconds;
- -2: an error of calling the client callback;
- -3: the advertisement is unavailable on Android (for example, if the user has an older version of the application).