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 out-of-the-box in Google Ad Manager mediation. To integrate Thumbnail Ads, the Ogury SDK uses Google Mobile Ads custom events to present them as banner to the mediation.

You must create a dedicated Google Ad Manager banner ad unit and yield 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 Google Ad Manager ad unit

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

  • Configure the ad unit as following:

    • Set the Name of the ad unit: ex. Thumbnail Ad.

    • Set a Code for the integration.

    • Select Fixed size as Size mode.

    • In Sizes, select the different sizes of Thumbnail Ad you will use in your app.

    • In Refresh rate, select No refresh.

We recommend to use 180x180 to improve the readability of the content of the Thumbnail Ad.

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

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.

Step 3: Create a dedicated Yield Group

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

  • Click on Delivery > Yield groups in the left-menu of your Google Ad Manager dashboard.

  • Click on New yield group.

  • Configure the Details of the yield group as following:

    • Set the Name of the yield group: ex. Thumbnail Ad Android.

    • Set the Status as Active.

    • Select Banner as Ad format.

    • Select Mobile app as Inventory type.

  • Scroll to the Targeting section.

  • Unfold the Inventory size section.

    • Search for the size you have chosen in step 2.

    • Click on the checkbox next to this size to select it.

  • Unfold the Inventory section.

    • Click on the arrow next to Ad units.

    • Search for the ad units where you will display a Thumbnail Ad.

    • Click on the check mark to include them in the targeting.

  • Scroll to the Yield partners section at the very bottom of the page:

    • Click on Add yield partner.

    • Select Ogury under the Yield Partner dropdown.

  • In the New yield partner pop-up:

    • Select Custom Event as Integration type

    • Set up CPM that you agreed with your Ogury Account Manager as Default CPM.

  • Under Additional yield partner details:

    • Set up Label to match with your Ad unit name on Ogury dashboard (e.g. Ogury). This makes it easier for you to track the settings are matching on both sides - Ogury and GAM.

    • Configure Class Name and Parameter as following:

Class Name:

com.ogury.mobileads.OguryThumbnailAdCustomEvent

In case you are already using the old custom event class (com.admob.mobileads.OguryThumbnailAdCustomEventBanner),do not update the Class Name field to (com.ogury.mobileads.OguryThumbnailAdCustomEvent).A new yield group and partner 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: Integrate the Thumbnail Ad as a Google Ad Manager banner

Compared to a standard integration of a banner ad from Google Ad Manager, 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 Google Ad Manager to pass the maximum size of the Thumbnail Ad.

PublisherAdView adView = new PublisherAdView(this);
adView.setAdSizes(new AdSize(maxWidth, maxHeight));
adView.setAdUnitId("GOOGLE_AD_MANAGER_AD_UNIT_ID");

maxWidth and maxHeight are the size you have configured in your Google Ad Manager dashboard in step 2. More details about max size can be found in this section.

Show a Thumbnail Ad

To display an ad, create an adRequest and call loadAd method:

PublisherAdRequest adRequest = new PublisherAdRequest.Builder().build();
adView.loadAd(adRequest);

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 ad 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 PublisherAdView and will leave the PublisherAdView empty. To solve this issue you can either:

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

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.

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:

adView.setAdSizes(new AdSize(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.

Customize Thumbnail Ad position

You can set the position where the Thumbnail Ad will be displayed in the PublisherAdRequest. 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.

Bundle extras = new Bundle();
extras.putString("gravity", OguryThumbnailGravity.BOTTOM_RIGHT.toString());
extras.putInt("x_margin", xMargin);
extras.putInt("y_margin", yMargin);

PublisherAdRequest adRequest = new PublisherAdRequest.Builder()
    .addCustomEventExtrasBundle(OguryThumbnailAdCustomEventBanner.class, extras)
    .build();

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:

Bundle extras = new Bundle();
extras.putInt("left_margin", leftMargin);
extras.putInt("top_margin", topMargin);

// Set whitelisted packages.
extras.putSerializable("whitelist", new String[] {
    "org.games.ui", "com.settings.activities"
});

PublisherAdRequest adRequest = new PublisherAdRequest.Builder()
    .addCustomEventExtrasBundle(OguryThumbnailAdCustomEventBanner.class, extras)
    .build();

Blacklist activities

You can prevent Thumbnail Ads from being displayed on a given Activity by adding them in the extras:

Bundle extras = new Bundle();
extras.putInt("left_margin", leftMargin);
extras.putInt("top_margin", topMargin);

// Set blacklisted activities.
extras.putSerializable("blacklist", new Class[] { 
    TermsAndConditionsActivity.class, SettingsActivity.class 
});

PublisherAdRequest adRequest = new PublisherAdRequest.Builder()
    .addCustomEventExtrasBundle(OguryThumbnailAdCustomEventBanner.class, extras)
    .build();

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 parameter log_whitelisted_activities can be set inside the adRequest to display all whitelisted activities:

Bundle extras = new Bundle();
extras.putBoolean("log_whitelisted_activities", true);

PublisherAdRequest adRequest = new PublisherAdRequest.Builder()
    .addCustomEventExtrasBundle(OguryThumbnailAdCustomEventBanner.class, extras)
    .build();

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

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:

Bundle extras = new Bundle();
extras.putInt("left_margin", leftMargin);
extras.putInt("top_margin", topMargin);

// Set whitelisted packages for fragments.
extras.putSerializable("whitelist_fragments", new String[] {
    "org.games.ui", "com.settings.fragments"
});

PublisherAdRequest adRequest = new PublisherAdRequest.Builder()
    .addCustomEventExtrasBundle(OguryThumbnailAdCustomEventBanner.class, extras)
    .build();

Blacklist fragments

You can prevent Thumbnail Ads from being displayed on a given Fragment by setting the "blacklist_fragments" attribute in the extras:

Bundle extras = new Bundle();
extras.putInt("left_margin", leftMargin);
extras.putInt("top_margin", topMargin);

// Set blacklisted fragments.
extras.putSerializable("blacklist_fragments", new Class[] { 
    TermsAndConditionsFragment.class, SettingsFragment.class 
});

PublisherAdRequest adRequest = new PublisherAdRequest.Builder()
    .addCustomEventExtrasBundle(OguryThumbnailAdCustomEventBanner.class, extras)
    .build();

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