Games Widgets API
Русский
Search results
OK for sites
Developing
Application
SDK
Methods
Graph API
Errors handling
Application limits
Application examples
OK Services Verification
Games Platform
Help

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:

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”

A callback for a case when a request was blocked by an ad blocker

method: “requestBannerAds”

result: “error”

data: “initialization_error”

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).