Thumbnail Ad

This article will go through all the steps required to display a Thumbnail Ad in your application.

Thumbnail Ads are small rectangle ads that are displayed as overlays to your application content. They are closable and draggable by the user, and can be used to (i) monetize your application through new incremental inventories and (ii) push cross-promotion campaigns.

Unlike our other ad formats, there is no equivalent ad format in AdMob mediation. To integrate Thumbnail Ads, the Ogury SDK uses Google Mobile Ads SDK custom events to present them as banner to the mediation.

You must create a dedicated AdMob banner ad unit and mediation group for the Thumbnail Ad in order to prevent undesired side-effect (blank banner, etc.).

Requirements

You have a registered application on your Ogury Dashboard and initialize the Ogury SDK. If not, please refer to the Getting started section before the next steps.

Step 1: Create a Thumbnail Ad ad unit

• Create a Thumbnail Ad ad unit.
• Copy the Ad unit id as you will need this information later to finish the integration.

In all the following code samples, we will refer to this Ad unit id by using the string YOUR_OGURY_AD_UNIT_ID.

Step 2: Create a dedicated AdMob Banner ad unit

• Go to your AdMob dashboard.

• Go to the list of ad units and click on the Add ad unit button.

• Click on Banner.

• Configure the banner ad unit as following:

  • Set the ad unit name: Thumbnail Ad.

  • Click on Advanced settings link to unfold them.

  • In Automatic refresh setting, select Disabled.

  • In eCPM floor, set the global eCPM floor to $1000.

The eCPM floor must be set to prevent AdMob to serve an ad on this dedicated ad unit.

We recommend to disable auto-refresh to avoid having Thumbnail Ads popping in front of the user every X seconds.

Step 3: Create a dedicated Mediation Group

In order to display Ogury Thumbnail Ad through AdMob mediation, you need to configure a Custom Event for Ogury in a dedicated mediation group.

• Go on the Mediation Group page.

• Click on CREATE MEDIATION GROUP.

• Select Banner as ad format.

• Set a Name for the mediation group.

• In Ad units section, click on ADD AD UNITS.

• Select the dedicated ad unit you created above.

• Click on ADD CUSTOM EVENT, in the Waterfall section

• Enter Ogury as Label, set an eCPM and click on CONTINUE.

For eCPM, you need to set the value that you agreed with your Ogury Account Manager.

• Next to the name of your Thumbnail ad ad unit, enter the following configuration and click on DONE:

Class Name:

com.ogury.mobileads.OguryThumbnailAdCustomEvent

In case you are already using the old custom event class (com.admob.mobileads.OguryThumbnailAdCustomEventBanner),do not update your existing ad unit mapping to use the new custom event class (com.ogury.mobileads.OguryThumbnailAdCustomEvent).A new ad unit and a new mapping should be created in order to not impact the users already using an older library. Ads will be served with the new SDK even if the custom event class is not updated.

Parameter:

{"assetKey":"OGY-XXXXXXXXXXXX","adUnitId":"YOUR_OGURY_AD_UNIT_ID"}

• Click on SAVE.

Step 4: Load a Thumbnail Ad

The Ogury SDK provides the OguryThumbnailAdForAdmob object that lets you load, display and control your Thumbnail Ad.

Instantiate a Thumbnail Ad

• Declare an OguryThumbnailAdForAdmob instance variable in the Activity where you want to display a Thumbnail Ad:

private OguryThumbnailAdForAdmob thumbnailAd;

• In the onCreate method of the Activity, instantiate the Thumbnail Ad:

@Override protected void onCreate (Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    thumbnailAd = new OguryThumbnailAdForAdmob(this, "YOUR_ADMOB_UNIT_ID");
}

OguryThumbnailAdForAdmob takes the following parameters:

• a reference to any kind of Context.

• the Ad unit id of the Thumbnail Ad. If you do not have one yet, you can refer to the first step to create it.

Load a Thumbnail Ad

To start loading an ad, call the load method:

thumbnailAd.load();

The ad is loaded with a default max size of 180x180dp. The max size can be changed by following the instructions in this section.

Since it may take a few seconds to fetch the ad resources (video, image, ...) from the network, you should call the load method as soon as possible.

Ideally, you should implement one of the two following examples depending on your use case:

• Call the load method right after the Ogury.start() method in the Activity:

  public class MyActivity extends Activity {
  
      private OguryThumbnailAdForAdmob thumbnailAd;
    
    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        OguryConfiguration.Builder oguryConfigurationBuilder = new OguryConfiguration.Builder(this, "OGY-XXXXXXXXXXXX");
        Ogury.start(oguryConfigurationBuilder.build());
        
        thumbnailAd = new OguryThumbnailAdForAdmob(this, "YOUR_ADMOB_UNIT_ID");
        thumbnailAd.load();
    }
        
}

• Call the load method in the onCreate method of your other Activity:

@Override protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState)
    
    thumbnailAd = new OguryThumbnailAdForAdmob(this, "YOUR_ADMOB_UNIT_ID");
    thumbnailAd.load();
}

Additionally, if you want to follow the lifecycle of the Thumbnail Ad, you can attach a listener.

Step 5: Show a Thumbnail Ad

To display the ad, call the show method:

thumbnailAd.show(activity);

The show method takes the following parameter:

• activity: reference to the Activity in which you want to display the Thumbnail Ad.

Thumbnail Ads are displayed bottom-right aligned, with a margin of 20 dp on the right and 70 dp on the bottom. More details on how to set the thumbnail position can be found in this section.

If the method fails to show the ad, the onAdError callback is called.

By default the Thumbnail Ad remains on screen while the user is navigating between activities of your application. A Thumbnail Ad is displayed in an Activity if the two first packages of its classname match the two first packages of the classname of the Activity passed as parameter to the show method.

You can customize in which activities or fragments Thumbnail Ads are displayed.

Step 6: Test your integration

As our algorithm works with personified targeting, you may not receive any ad while testing your application.

You can test your integration by adding the suffix _test to your interstitial ad unit id, for more details go to Test your implementation page.

Note that if you have just registered your application in the Ogury Dashboard, it will take around 15 minutes until you can successfully load an ad.

If you are not able to display any Thumbnail Ad, we recommend you to log every callbacks on your OguryThumbnailAdForAdmob interface to follow the lifecycle of the Thumbnail Ad. If you encounter the onAdError callback, you can check the Error codes section below to understand the error and get some advice on how to solve the issue.

Additionally, you can follow the integration logs to get useful information on your integration status and any issue that might occur when displaying ads. Connect your device to Android Studio. Then filter the logs after the OGURY keyword to separate them from everything else.

Advanced Topics

Customize Thumbnail Ad size

In order to control the thumbnail size, set the size when initialising the OguryThumbnailAdForAdmob object with maxWidth and maxHeight parameters before calling load method

thumbnailAd = new OguryThumbnailAdForAdmob(this, "YOUR_ADMOB_UNIT_ID", maxWidth, maxHeight);

maxWidth and maxHeight parameters define the maximum size that the Thumbnail Ad will take on the screen. Both values are in dp.

We recommend to use maxWidth = 180 and maxHeight = 180 to improve the readability of the content of the Thumbnail Ad.

Example: when given maxWidth= 180 and maxHeight= 180, the Ogury SDK may decide to display a 16:9 video ad inside. In this case the Thumbnail Ad size will be 180x102dp to match the ratio of the 16:9 video.

The following constraints apply on the values you can pass to these parameters:

• maxWidth and maxHeight must not be greater than the size of the screen.

• maxWidthandmaxHeight must be greater than or equal to 101dp.

• longest side, either maxWidth or maxHeight, must be greater than or equal to

  180dp.

Check if a Thumbnail Ad is loaded

Call the following method to check if a Thumbnail Ad is ready to be displayed:

thumbnailAd.isLoaded();

If you want to be informed when the ad is ready to be displayed, you can also register a listener and override the onAdLoaded method.

Customize Thumbnail Ad position

To set the thumbnail position, call the setPosition method with gravity and margin parameters before calling the show method:

thumbnailAd.setPosition(gravity, xMargin, yMargin);

The setPosition method takes the following parameters:

• gravity : the corner based on which the thumbnail will be positioned, it can have the following values:

  • OguryThumbnailGravity.TOP_LEFT

  • OguryThumbnailGravity.TOP_RIGHT

  • OguryThumbnailGravity.BOTTOM_LEFT

  • OguryThumbnailGravity.BOTTOM_RIGHT

• xMargin: distance on the x axis from the gravity corner to thumbnail. Value must be in dp.

• yMargin: distance on the y axis from the gravity corner to thumbnail. Value must be in dp.

Customize in which activities Thumbnail Ad is displayed

Thumbnail Ad remains on screen while the user navigates across the activities of your application.

By default, a Thumbnail Ad is displayed in an Activity only if the two first packages of its classname match the two first packages of the classname of the Activity passed as parameter to the show method.

Example: If you pass com.ogury.game.GameActivity as parameter of the show method, the Thumbnail Ad will stay on screen in all the activities in the com.ogury package and all packages at any level under it.

You can override these default settings using whitelists and blacklists.

Whitelist packages

You can increase the number of whitelisted packages where Thumbnail Ads are displayed and stay on screen. This can be useful if you have Activity provided by a library like a game engine, in this case you need to whitelist the package associated to this library.

Call the setWhiteListPackages method to whitelist packages:

thumbnailAd.setWhiteListPackages("org.games.ui", "com.settings.activities");

Blacklist activities

You can prevent Thumbnail Ads from being displayed on a given Activity by using the setBlackListActivities method:

thumbnailAd.setBlackListActivities(
    TermsAndConditionsActivity.class, 
    SettingsActivity.class);

When the user navigates to an Activity that is not in a whitelisted package or that is explicitly blacklisted, the Thumbnail Ad is hidden and paused. It comes back on the screen when the user navigates back to anActivitythat is allowed.

The method logWhiteListedActivities can be used to display all whitelisted activities. It should be called only after setting the whitelist and blacklist.

thumbnailAd.logWhiteListedActivities(true)

After calling the method logWhiteListedActivities, connect your device to Android studio and filter the logs by OGURY tag. You will see logs that start with Whitelisted:, for example Whitelisted: com.ogury.HomeActivity

Customize in which fragments Thumbnail Ad is displayed

Filtering by fragments is supported for androidx fragments and v4 support fragments, but is not supported for native fragments. Thumbnail Ad needs FragmentLifecycleCallbacks to work and the native fragments have lifecycle callbacks only starting with android 8.

In case the application is based mostly on fragments and there are fragments in which the thumbnail ad should not be displayed, a filtering on fragments instead of activities can be done. In order to change the filtering from activities to fragments, setBlackListFragments or setWhiteListFragmentPackages must be called.

By default, a Thumbnail Ad is displayed in a Fragment only if the two first packages of its classname matches the two first packages of the classname of the Activity passed as parameter to the show method.

Example: If you pass com.ogury.game.GameFragmentActivity as parameter of the show method, the Thumbnail Ad will stay on screen as long as a fragment is visible to the user and is part ofcom.ogury package and all packages at any level under it.

You can override these default settings using whitelists and blacklists.

Whitelist packages

You can increase the number of whitelisted packages where Thumbnail Ads are displayed and stay on screen. This can be useful if you have a Fragment provided by a library like a game engine, in this case you need to whitelist the package associated to this library.

Call the setWhiteListFragmentPackages method to whitelist packages:

thumbnailAd.setWhiteListFragmentPackages("org.games.ui", "com.settings.fragments");

Blacklist fragments

You can prevent Thumbnail Ads from being displayed on a given Fragment by using the setBlackListFragments method:

thumbnailAd.setBlackListFragments(
    BannerAdsFragment.class, 
    SettingsFragment.class);

When fragment filters are set, Thumbnail Ad is displayed only if the top activity contains no blacklisted visible fragment and it contains at least one whitelisted visible fragment. This condition is checked every time a fragment's onResume or onPause is called and if the condition is not true anymore, Thumbnail Ad is hidden.

Listener

The Ogury SDK provides the OguryThumbnailAdListener to listen to the lifecycle of a Thumbnail Ad instance.

To register an OguryThumbnailAdListener, add the following code just after instantiating the OguryThumbnailAdForAdmob:

thumbnailAd.setListener(new OguryThumbnailAdListener() {
    // ...
});

The OguryThumbnailAdListener exposes the following methods:

Method	Definition
onAdLoaded	The SDK is ready to display the ad provided by the ad server.
onAdDisplayed	The ad has been displayed on the screen.
onAdClicked	The ad has been clicked by the user.
onAdClosed	The ad has been closed by the user.
onAdError	The ad failed to load or display. The oguryError parameter contains the reason of the failure. All error codes are detailed in the section below.

Error codes

When an ad fails to load or to be displayed, the SDK calls the onAdError callback with an OguryError object. The OguryError object contains the cause of the failure. You can get the error code by calling the getErrorCode method and a more explicit message by calling the getMessage method.

The error codes that you can encounter are defined in the OguryAdFormatErrorCode object:

Name	Value	Definition
NO_INTERNET_CONNECTION	0	No Internet connection The device has no Internet connection. Try again once the device is connected to the Internet.
LOAD_FAILED	2000	Load failed The ad failed to load for an unknown reason.
AD_DISABLED	2001	Ad disabled Ad serving has been disabled for this placement/application.
PROFIG_NOT_SYNCED	2002	Profig not sync An internal SDK error has occurred.
AD_EXPIRED	2003	Ad expired The loaded ad is expired. You must call the show method within 4 hours after the load.
SDK_INIT_NOT_CALLED	2004	SDK init not called The Ogury.start() method has not been called before a call to the load or show methods.
ANOTHER_AD_ALREADY_DISPLAYED	2005	Another ad already displayed Another ad is already displayed on the screen.
SDK_INIT_FAILED	2006	SDK init failed An error occurred during the initialization of the SDK.
ACTIVITY_IN_BACKGROUND	2007	Activity in background You tried to show an ad while the application was in background. Make sure to only call theshow method when the application is visible to the user.
AD_NOT_AVAILABLE	2008	Ad not available The server returns no ads.
AD_NOT_LOADED	2009	Ad not loaded The server returns an ad but something went wrong with the ad precaching.

Examples

Show an ad to a user entering your application

You may want to show a Thumbnail Ad to a user as soon as they enter your application.

You can achieve this behaviour by using the onAdLoaded callback to display the Thumbnail Ad as soon as it is displayable. In the onCreate of the first Activity you can append the following lines:

thumbnailAd = new OguryThumbnailAdForAdmob(this, "YOUR_ADMOB_UNIT_ID");

thumbnailAd.setListener(new OguryThumbnailAdListener() {
    @Override public void onAdLoaded() {
        thumbnailAd.show(MyActivity.this);
    }
    // ...
});

thumbnailAd.load();

You can also use this snippet to display the Thumbnail Ad when the user reaches a given Activity.

Show an ad after the user scrolled

You may want to delay the display of the Thumbnail Ad until the user scrolls in your content (e.g. in a news feed).

You can achieve this behavior by using the OnTouchListener of your RecyclerView. In the onCreate of the first Activity you can append the following lines:

thumbnailAd = new OguryThumbnailAdForAdmob(this, "YOUR_ADMOB_UNIT_ID");
thumbnailAdHasBeenShown = false;

recyclerView.setOnTouchListener(new View.OnTouchListener() {
    @Override public boolean onTouch(View v, MotionEvent event) {
        if (event.getAction() == MotionEvent.ACTION_UP) {
            if (!thumbnailAdHasBeenShown && thumbnailAd.isLoaded()) {
                thumbnailAdHasBeenShown = true;
                thumbnailAd.show(MyActivity.this);
            }
        }
        return false;
    }
});

thumbnailAd.load();

Show an ad after the user scrolled X items

In addition to the previous example, you may want to delay the display of the Thumbnail Ad until the user reached a given item in the feed.

You can achieve this behavior by using the OnTouchListener and the layout manager to determine which items are being displayed. In the onCreate of the first Activity you can append the following lines:

final int MIN_SCROLL_ITEMS_BEFORE_DISPLAYING = 20;

thumbnailAd = new OguryThumbnailAdForAdmob(this, "YOUR_ADMOB_UNIT_ID");
thumbnailAdHasBeenShown = false;

final LinearLayoutManager layoutManager = recyclerView.getLayoutManager(); 
//GridLayoutManager can also be used

recyclerView.setOnTouchListener(new View.OnTouchListener() {
    @Override
    public boolean onTouch(View v, MotionEvent event) {
        if(event.getAction() == MotionEvent.ACTION_UP){
            if (!thumbnailAdHasBeenShown
                && thumbnailAd.isLoaded() 
                && layoutManager.findFirstVisibleItemPosition() > MIN_SCROLL_ITEMS_BEFORE_DISPLAYING) {
                thumbnailAdHasBeenShown = true;
                thumbnailAd.show(activity);
            }
        }
        return false;
    }
});

thumbnailAd.load();