Thumbnail
This article will guide you through all the steps necessary to display an Thumbnail ad in your application.
Last updated
Was this helpful?
This article will guide you through all the steps necessary to display an Thumbnail ad in your application.
Last updated
Was this helpful?
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.
Ensure you have registered your application on the Ogury Dashboard. If not, please refer to the page before proceeding.
on your asset page in the Ogury Dashboard.
, as you will need it for integration. It is in the form of a UUID, which consists of a 36-character string formatted as follows: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
, where each x
represents a hexadecimal digit.
To load a Thumbnail ad, instantiate an OguryThumbnailAd
object and call its load()
method.
By default, the ad loads with a maximum size of 180x180 . If needed, you can customize the maximum size by following the guidelines provided in section.
OguryThumbnailAd
requires the following parameters:
If you are developing a mediation adapter, you must pass an additional parameter, OguryMediation
which should be instantiated with:
name
: the name of the mediation.
version
: the version of the mediation SDK.
You can monitor the lifecycle of your Thumbnail ad by implementing the OguryThumbnailAdListener
interface. This listener provides real-time updates on key events, such as successful ad loading, display, or errors.
To use it, set the listener on the instance of OguryThumbnailAd
by calling the setListener()
method before invoking the load()
method. Implement the necessary methods in your class to ensure timely notifications, allowing you to manage the ad experience effectively.
To display an loaded Thumbnail ad, invoke the show()
method on the instantiated OguryThumbnailAd
object.
The show
method takes the following parameter:
Since our algorithm uses personalized targeting, you may not receive ads during testing. To obtain test ads, you can append _test
to your Thumbnail ad unit ID in the code, for example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_test
.
To adjust the size of a Thumbnail ad, use the load()
method with maxWidth
and maxHeight
parameters:
Constraints:
maxWidth
and maxHeight
cannot exceed the device’s screen size.
To specify the position of a Thumbnail ad, invoke the show()
method with additional parameters: OguryThumbnailGravity, xMargin
and yMargin
.
The show()
method takes the following parameters:
gravity
: the corner from which the Thumbnail ad will be positioned. The OguryThumbnailGravity
enum includes the following values:
TOP_LEFT
TOP_RIGHT
BOTTOM_LEFT
BOTTOM_RIGHT
Thumbnail ad remains on screen while the user navigates across the activities of your application.
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:
Call the setWhiteListPackages
method to whitelist packages:
Blacklist activities:
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
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.
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:
Call the setWhiteListFragmentPackages
method to whitelist packages:
Blacklist fragments:
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.
If you are unable to load or display any Thumbnail ads, we recommend logging callbacks from the OguryThumbnailAdListener
to monitor the ad's lifecycle, especially the onAdError
callback. This method provides an OguryAdError
instance containing important error details:
type
: indicates the error type through the OguryAdError.Type
enum, which distinguishes between loading errors (Load
) and showing errors (Show
).
code
: An integer that identifies the specific error. Errors that can occur during ad loading or displaying are defined in the OguryLoadErrorCode
and OguryShowErrorCode
classes. Detailed explanations of these error codes are provided in the tables below to assist you in troubleshooting effectively.
message
: A descriptive message that provides additional context about the error.
You can utilize these details to diagnose the issue and take appropriate action to resolve it.
SDK_NOT_STARTED
The load could not proceed because the SDK appears to have not been started.
SDK_NOT_PROPERLY_INITIALIZED
The load could not proceed because the SDK is not properly initialized.
NO_ACTIVE_INTERNET_CONNECTION
The load could not proceed because there is no active Internet connection.
INVALID_CONFIGURATION
The load could not proceed due to an invalid SDK configuration.
AD_DISABLED_COUNTRY_NOT_OPENED
The load could not proceed because ads are disabled; the user’s country is not yet available for advertising.
AD_DISABLED_CONSENT_DENIED
The load could not proceed because ads are disabled; the user has denied consent for advertising.
AD_DISABLED_CONSENT_MISSING
The load could not proceed because ads are disabled; the user consent is missing or has not been provided.
AD_DISABLED_UNSPECIFIED_REASON
The load could not proceed because ads are disabled for an unspecified reason.
AD_REQUEST_FAILED
The load failed because the ad request encountered an error, and the server returned an unexpected response.
NO_FILL
No ad is currently available for this placement (no fill).
AD_PARSING_FAILED
The ad could not be loaded due to a failure in parsing.
AD_PRECACHING_FAILED
The ad could not be loaded due to a failure in ad precaching.
AD_PRECACHING_TIMEOUT
The ad could not be loaded as precaching exceeded the time limit and timed out.
SDK_NOT_STARTED
The ad could not be displayed because the SDK appears to have not been started.
SDK_NOT_PROPERLY_INITIALIZED
The ad could not be displayed because the SDK is not properly initialized.
NO_ACTIVE_INTERNET_CONNECTION
The ad could not be displayed because there is no active Internet connection.
INVALID_CONFIGURATION
The ad could not be displayed due to an invalid SDK configuration.
AD_DISABLED_COUNTRY_NOT_OPENED
The ad could not be displayed because ads are disabled; the user’s country is not yet available for advertising.
AD_DISABLED_CONSENT_DENIED
The ad could not be displayed because ads are disabled; the user has denied consent for advertising.
AD_DISABLED_CONSENT_MISSING
The ad could not be displayed because ads are disabled; the user consent is missing or has not been provided.
AD_DISABLED_UNSPECIFIED_REASON
The ad could not be displayed because ads are disabled for an unspecified reason.
AD_EXPIRED
The ad could not be displayed because the retention time of the loaded ad has expired.
NO_AD_LOADED
No ad has been loaded.
VIEW_IN_BACKGROUND
The ad could not be displayed because the application was running in the background.
ANOTHER_AD_ALREADY_DISPLAYED
The ad could not be displayed because another ad is currently being displayed.
WEBVIEW_TERMINATED_BY_SYSTEM
The ad could not be displayed because the WebView was terminated by the system, resulting in the ad being unloaded due to high resource consumption by the application.
You may want to show a Thumbnail Ad to a user as soon as they enter your application.
You may want to delay the display of the Thumbnail Ad until the user scrolls in your content (e.g. in a news feed).
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.
context
: a reference to any kind of .
adUnitID
: the ad unit ID for the Thumbnail ad. If you do not have one, please refer to the to create it.
If the onAdError
callback is triggered, refer to the section below for detailed information on troubleshooting.
By default, Thumbnail ad is aligned to the bottom-right corner, maintaining a margin of 20 dp from the right edge and 70 dp from the bottom. For more information on configuring the ad's position, please refer to the section.
Additionally, a Thumbnail ad stays visible while the user navigates between the activities of your application. It is displayed in an activity only if the first two packages of its class name match the first two packages of the class name of the activity specified in the show()
method. For details on how to customize these default settings using whitelists and blacklists, please see the section.
activity
: a reference to the in which you want to display the Thumbnail ad.
Ogury exclusively serves ads to users who have provided their consent. Before conducting any tests, it is essential to ensure that your implementation complies with applicable privacy regulations. For more information on the regulations supported by Ogury, please visit the page.
For further details on test mode and enabling debug logs, please refer to the page.
The maxWidth
and maxHeight
parameters specify the maximum dimensions, in , that the Thumbnail ad will occupy on the screen.
For optimal readability and ad display quality, we recommend setting maxWidth = 180
and maxHeight = 180
. For instance, if you set these values and the Ogury SDK decides to show a 16:9 video ad, the Thumbnail ad will resize to 180x101 to maintain the 16:9 ratio.
Both maxWidth
and maxHeight
must be at least 101 .
The longest side, either maxWidth
or maxHeight
, must be at least 180 .
activity
: a reference to the in which you want to display the Thumbnail ad.
xMargin
: the horizontal distance from the x-axis to the Thumbnail ad, expressed in .
yMargin
: the vertical distance from the y-axis to the Thumbnail ad, expressed in .
By default, a Thumbnail ad is displayed in an only if the two first packages of its classname match the two first packages of the classname of the passed as parameter to the show
method.
You can increase the number of whitelisted packages where Thumbnail ads are displayed and stay on screen. This can be useful if you have provided by a library like a game engine, in this case you need to whitelist the package associated to this library.
You can prevent Thumbnail ads from being displayed on a given by using the setBlackListActivities
method:
When the user navigates to an 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 anthat is allowed.
Filtering by fragments is supported for and , but is not supported for . Thumbnail ad needs to work and the native fragments have lifecycle callbacks only starting with android 8.
By default, a Thumbnail ad is displayed in a only if the two first packages of its classname matches the two first packages of the classname of the passed as parameter to the show
method.
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 provided by a library like a game engine, in this case you need to whitelist the package associated to this library.
You can prevent Thumbnail ads from being displayed on a given by using the setBlackListFragments
method:
You can achieve this behavior by using the onAdLoaded
to display the Thumbnail Ad as soon as it is displayable. In the onCreate
of the first you can append the following lines:
You can also use this snippet to display the Thumbnail Ad when the user reaches a given .
You can achieve this behavior by using the OnTouchListener
of your RecyclerView
. In the onCreate
of the first you can append the following lines:
You can achieve this behavior by using the and the layout manager to determine which items are being displayed. In the onCreate
of the first you can append the following lines: