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 mediation group for the Thumbnail Ad in order to prevent undesired side-effect of the integration as banner (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

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

Step 2: Create a dedicated Google Ad Manager ad unit

Go to your Google Ad Manager dashboard.
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 200x200 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 the Size you can choose:

width and height must be greater than or equal to 45dp.
longest side, either width and height, must be greater than or equal to 80dp.

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

OguryThumbnailCustomEvents

Parameter:

{"assetKey":"ASSET_KEY","adUnitId":"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.

let adSize = GADAdSizeFromCGSize(CGSize(width: maxWidth, height: maxHeight))
let adView = DFPBannerView(adSize: adSize)
adView.adUnitID = "GOOGLE_AD_MANAGER_AD_UNIT_ID"

DFPBannerView* adView = [[DFPBannerView alloc] initWithAdSize:
    GADAdSizeFromCGSize(CGSizeMake(maxWidth, maxHeight))
];
adView.adUnitID = @"GOOGLE_AD_MANAGER_AD_UNIT_ID";

maxWidth and maxHeight are the size you have configured in your Google Ad Manager dashboard in step 2.

Show a Thumbnail Ad

The Thumbnail Ad will display either:

Once attached to your ViewController if it is loaded.
Once loaded if it already attached to your ViewController layout.

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

The Thumbnail Ad displays outside of the DFPBannerView and will leave the DFPBannerView empty. To solve this issue you can set the frame of the view to be 0x0.

By default the Thumbnail Ad remains on screen while the user is navigating between View Controllers of your application. A Thumbnail Ad is displayed in a ViewController if bundle identifier of the ViewController corresponds to the main bundle of application.

You can customize where Thumbnail Ads are displayed in this section.

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.

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.

Advanced Topics

Customize Thumbnail Ad position

You can set the position where the Thumbnail Ad will be displayed in the GADAdRequest. The position is passed using custom event extras:

"rect_corner" : the corner based on which the thumbnail will be positioned, it can have the following values:
- "top_left"
- "top_right"
- "bottom_left"
- "bottom_right"
"x_margin": distance on the x axis from the gravity corner to thumbnail. Value must be in points.
"y_margin": distance on the y axis from the gravity corner to thumbnail. Value must be in points.

let extras = GADCustomEventExtras()
extras.setExtras([
    "rect_corner": "bottom_right",
    "left_margin": xMargin,
    "top_margin": yMargin
], forLabel:"Ogury")

let request = DFPRequest()
request.register(extras)
adView.load(request)

GADCustomEventExtras* extras = [GADCustomEventExtras new];
[extras setExtras:@{
    @"rect_corner": @"bottom_right",
    @"left_margin": xMargin,
    @"top_margin": yMargin,
} forLabel:@"Ogury"];
    
DFPRequest* request = [DFPRequest new];
[request registerAdNetworkExtras:extras];
[adView loadRequest:request];

Customize where the Thumbnail Ad is displayed

Thumbnail Ad remains on screen while the user is navigating between ViewController of your application.

By default, a Thumbnail Ad is displayed in an ViewController only if this bundle identifier are the main bundle of application.

You can override these default settings using whitelists and blacklists.

Whitelist bundles

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

You can set the whitelisted packages by setting the "whitelist" attribute in the extras:

let extras = GADCustomEventExtras()
extras.setExtras([
    "left_margin": leftMargin,
    "top_margin": topMargin
    // Set whitelisted packages.
    "whitelist": ["com.example.bundle", "com.example.bundle2"]
], forLabel:"Ogury")

let request = DFPRequest()
request.register(extras)
adView.load(request)

GADCustomEventExtras* extras = [GADCustomEventExtras new];
[extras setExtras:@{
    @"left_margin": leftMargin,
    @"top_margin": topMargin,
    // Set whitelisted packages.
    @"whitelist": @[@"com.example.bundle", @"com.example.bundle2"]
} forLabel:@"Ogury"];
    
DFPRequest* request = [DFPRequest new];
[request registerAdNetworkExtras:extras];
[adView loadRequest:request];

Blacklist View Controllers

You can prevent Thumbnail Ads from being displayed on given ViewController by setting the "blacklist" attribute in the extras:

let extras = GADCustomEventExtras()
extras.setExtras([
    "left_margin": leftMargin,
    "top_margin": topMargin
    // Set blacklisted view controllers.
    "blacklist": [
        NSStringFromClass(TermsAndConditionsViewController.classForCoder()),
        NSStringFromClass(SettingsViewController.classForCoder())
    ]
], forLabel:"Ogury")

let request = DFPRequest()
request.register(extras)
adView.load(request)

GADCustomEventExtras* extras = [GADCustomEventExtras new];
[extras setExtras:@{
    @"left_margin": leftMargin,
    @"top_margin": topMargin,
    // Set blacklisted view controllers.
    @"blacklist": @[
        NSStringFromClass([TermsAndConditionsViewController class]),
        NSStringFromClass([SettingsViewController class])
    ]
} forLabel:@"Ogury"];
    
DFPRequest* request = [DFPRequest new];
[request registerAdNetworkExtras:extras];
[adView loadRequest:request];

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

Last updated 5 months ago