Thumbnail Ad (Legacy)
This article will go through all the steps required to display a Thumbnail Ad in your application.
Use the recommended API for the Thumbnail Ad format.
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 registered an application on your Ogury Dashboard. If not, please refer to the Getting started section before the next steps.
Step 1: Create an Ogury Thumbnail Ad ad unit
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:
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:
Click on SAVE.
Step 4: Integrate the Thumbnail Ad as a AdMob banner
Compared to a standard integration of a banner ad from AdMob, you must adapt your integration in order to take care of the particularities of the Thumbnail Ad ad format.
Instantiate a Thumbnail Ad
You need to change the code to instantiate the banner ad from AdMob to pass the maximum size of the Thumbnail Ad:
The ad is loaded with a default max size of 180x180dp. The max size can be changed by following the instructions in this section.
Show a Thumbnail Ad
To display an ad, create an adRequest
and call the loadAd()
method:
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.
The Thumbnail Ad will display either:
Once attached to your
Activity
layout if it is loaded.Once loaded if it already attached to your
Activity
layout.
The Thumbnail Ad displays outside of the AdView
and will leave the AdView
empty. To solve this issue you can either:
Set the size of the
AdView
to be 0x0.
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 5: Test your integration
After a successful integration, the first impressions of your application will be replaced by a Congratulations Ad, regardless of the ad format you have chosen to integrate.
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.
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, call setAdSize()
method with maxWidth
and maxHeight
parameters:
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
andmaxHeight
must not be greater than the size of the screen.maxWidth
andmaxHeight
must be greater than or equal to 101dp.longest side, either
maxWidth
ormaxHeight
, must be greater than or equal to180dp.
Customize Thumbnail Ad position
You can set the position where the Thumbnail Ad will be displayed in the AdRequest
. The position is passed using custom event extras:
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
x_margin
: distance on the x axis from the gravity corner to thumbnail. Value must be in dp.y_margin
: 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.
You can set the whitelisted packages by setting the "whitelist"
attribute in the extras:
Blacklist activities
You can prevent Thumbnail Ads from being displayed on given Activity
by setting the "blacklist"
attribute in the extras:
The parameter log_whitelisted_activities
can be set inside the adRequest
to display all whitelisted activities:
log_whitelisted_activities
is false
by default.
The parameter log_whitelisted_activities
should not be set in release because it can impact the performance of the host application.
After sending log_whitelisted_activities
, 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. ThumbnailAd 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.
You can override these default settings using whitelists and blacklists for fragments.
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 for fragments
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.
You can set the whitelisted packages by setting the "whitelist_fragments"
attribute in the extras:
Blacklist fragments
You can prevent Thumbnail Ads from being displayed on a given Fragment
by setting the "blacklist_fragments"
attribute in the extras:
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.
Last updated