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.
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 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_AD_UNIT_ID
.
Step 2: Load a Thumbnail Ad
The Ogury SDK provides the OguryThumbnailAd
object that lets you load, display and control your Thumbnail Ad.
Instantiate a Thumbnail Ad
Declare an
OguryThumbnailAd
instance variable in theActivity
where you want to display a Thumbnail Ad:
In the
onCreate
method of theActivity
, instantiate the Thumbnail Ad:
OguryThumbnailAd
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:
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 theOgury.start()
method in theActivity
:
Call the
load
method in theonCreate
method of your otherActivity
:
Additionally, if you want to follow the lifecycle of the Thumbnail Ad, you can attach a listener.
Step 3: Show a Thumbnail Ad
To display the ad, call the show
method:
The show
method takes the following parameter:
activity
: reference to theActivity
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 4: Test your integration
Ogury exclusively serves ads to users who have given consent. It is essential to have responded to a valid TCFv2 consent form before conducting any tests.
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 of the OguryThumbnailAdListener
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.
Advanced Topics
Customize Thumbnail Ad size
In order to control the thumbnail size, call load
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.
Check if a Thumbnail Ad is loaded
Call the following method to check if a Thumbnail Ad is ready to be displayed:
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.
Set Thumbnail Ad position
To set the thumbnail position, call the show
method with gravity
and margin
parameters:
The show
method takes the following parameters:
activity
: reference to theActivity
in which you want to display the Thumbnail Ad.gravity
: the corner based on which the thumbnail will be positioned and 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:
Blacklist activities
You can prevent Thumbnail Ads from being displayed on a given Activity
by using the setBlackListActivities
method:
The method logWhiteListedActivities
can be used to display all whitelisted activities. It should be called only after setting the whitelist and blacklist.
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 ThumbnailAd 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:
Blacklist fragments
You can prevent Thumbnail Ads from being displayed on a given Fragment
by using the setBlackListFragments
method:
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.
Listeners
Listen to the lifecycle of ads
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 OguryThumbnailAd
:
The OguryThumbnailAdListener
exposes the following methods:
Method | Definition |
| The SDK is ready to display the ad provided by the ad server. |
| The ad has been displayed on the screen. |
| The ad has been clicked by the user. |
| The ad has been closed by the user. |
| The ad failed to load or display. The |
Listen to the ad impressions
The Ogury SDK also provides the OguryAdImpressionListener
interface to listen and count the ad impressions.
To register an OguryAdImpressionListener
, add the following code before calling the show
method:
The OguryAdImpressionListener
exposes the following method:
Methods | Definition |
| The ad has triggered an impression. |
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 The device has no Internet connection. Try again once the device is connected to the Internet. |
|
| Load failed The ad failed to load for an unknown reason. |
|
| Ad disabled Ad serving has been disabled for this placement/application. |
|
| Profig not sync An internal SDK error has occurred. |
|
| Ad expired The loaded ad is expired. You must call the |
|
| SDK init not called The |
|
| Another ad already displayed Another ad is already displayed on the screen. |
|
| SDK init failed An error occurred during the initialization of the SDK. |
|
| Activity in background You tried to |
|
| Ad not available The server returns no ads. |
|
| Ad not loaded The server returns an ad but something went wrong with the ad precaching. |
Some 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 behavior 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:
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:
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:
Last updated