Direct integration

Direct integration of Ogury Exclusive Demand Tag into publisher's web pages

Ogury Exclusive Demand Tag handles the delivery of video and display thumbnail ads and helps you monetize your websites with a simple integration.

This document will guide through the integration process.

Prerequisites

  • If your website will be trafficked in a country where GDPR applies, you must have implemented a consent management platform (CMP) which is compliant with TCF v2 and includes the Ogury vendor ID (31).

Supported Environments

  • Android

    • Chrome (v83 and above)

    • Samsung browser

    • Facebook browser

  • iOS

    • Chrome (v83 and above)

    • Safari (v10 and above)

    • Facebook browser

Step 1: Register your website and your ad unit

Please contact your publisher manager to register your website and ad unit into Ogury Dashboard. After this registration, you will receive an asset key and ad unit identifier that will be needed for the following steps.

Step 2: Configure the ad unit

For all the pages where you want to display an Ogury ad, copy the following snippet on the placement of your choice inside the page's body.

<script type='text/javascript'>
window.top.OG_ad_units = window.top.OG_ad_units || [];
window.top.OG_ad_units.push({
ad_unit_id: '$OGURY_AD_UNIT',
asset_key: '$OGURY_ASSET_KEY',
params:{
max_width: 180,
max_height: 180
}
});
</script>

This code snippet has to be placed before the snippet of Step 3.

You need to replace $OGURY_AD_UNIT and $OGURY_ASSET_KEY by the values you received at Step 1.

Please adapt the max_width and max_height to best fit your needs.

We recommend to use max_width= 180 and max_height= 180 to improve the readability of the content of the Thumbnail Ad.

Example: when given max_width= 180 and max_height= 180, the Ogury Exclusive Demand Tag may decide to display a 16:9 ad inside. In this case the Thumbnail Ad size will be 180x102 to match the ratio of the 16:9 ad.

The following constraints apply on the values you can pass to these parameters:

  • max_width and max_height must not be greater than the size of the viewport.

  • max_widthandmax_height must be greater than or equal to 101.

  • longest side, either max_width or max_height, must be greater than or equal to 180.

Step 3: Plug Ogury Exclusive Demand

In order to plug Ogury Exclusive Demand (OED) in your website, the following snippet has to be copied right before the closing </body> tag of your HTML pages.

<script src="https://mwtw.presage.io/v1/tag.js" async></script>

It is recommended to add this snippet in all the pages of your website.

Step 4: Update your ads.txt

Make sure to add your Ogury ID to your ads.txt file.

Optional configuration

Customizing Thumbnail Ad Position

To customize the Thumbnail Ad position, set params fields with gravity, x_margin and y_margin parameters:

params:{
gravity: 'BOTTOM_RIGHT',
x_margin: 20,
y_margin: 20
}
  • gravity : the area based on which the thumbnail will be positioned and it can have the following values:

    • 'TOP_LEFT'

    • 'TOP_RIGHT'

    • 'TOP_CENTER'

    • 'BOTTOM_LEFT'

    • 'BOTTOM_RIGHT'

    • 'BOTTOM_CENTER'

    • 'CENTER'

Default value: 'BOTTOM_RIGHT'

  • x_margin: distance on the x axis from the gravity area to thumbnail. Value must be in px.

Default value : 20

This value is ignored if the gravity is set to 'CENTER', 'TOP_CENTER' or 'BOTTOM_CENTER'

  • y_margin: distance on the y axis from the gravity corner to thumbnail. Value must be in px.

Default value : 20

This value is ignored if the gravity is set to 'CENTER'

You cannot configure the time until the closing button for the ad appears. The default value is set to 7 seconds.

Callbacks

Callbacks provide a way to handle these Ad Response situations:

  • An ad has started to be displayed.

  • No ad to serve ('no fill', 'passback').

  • An ad has been completed (display finished).

  • An error when prerequisites are not met.

callbacks: {
on_ad_show: onAdShowCallback,
on_no_ad: onNoAdCallback,
on_ad_complete: onAdCompleteCallback,
on_error: onErrorCallback,
}

To use the callbacks, you'll need to create the JavaScript Functions that are supposed to be called for the different statuses first. Afterwards you can pass them as values for on_ad_show, on_no_ad, on_ad_complete , on_error or all together, and they'll be executed for the particular event:

  • on_ad_show : the function that is set for this parameter will be triggered when an ad has started to be shown by the Ogury Tag.

  • on_no_ad : the function that is set for this parameter will be triggered when the Ogury Tag has no ads to serve.

  • on_ad_complete : the function that is set for this parameter will be triggered when the ad is closed. This happens:

    • if the user clicks on the ad,

    • if the user clicks on the closing button,

    • if the ad is closed automatically after a predefined timeout.

  • on_error : the function that is set for this parameter will be triggered when there is an error preventing the ad delivery (unsupported environment, user consent conditions, network errors ...).

The JavaScript Functions have to be defined before you initialize the Ogury Tag.

Callback Arguments

When calling the functions configured for on_ad_show , on_no_ad , on_ad_complete and on_erroran Ad Unit JavaScript Object will be returned as argument of these functions.

Ad Unit Object :

{
ad_unit_id: string,
asset_key: string,
params:{
max_width: number,
max_height: number,
gravity?: string,
x_margin?: number,
y_margin?: number,
},
callbacks?: {
on_ad_show?: function,
on_no_ad?: function,
on_ad_complete?: function,
on_error?: function,
}
}

Note that some parameters are optional (defined with ?) and may not be available if they are not configured for the Ogury Tag.

Callback Integration Example

<script type='text/javascript'>
function onAdShowCallback(adUnit) {
console.log(adUnit)
}
function onNoAdCallback(adUnit) {
// call another Advertising partner
}
function onAdCompleteCallback(adUnit) {
// call another Advertising partner
}
function onErrorCallback(adUnit) {
// call another Advertising partner
}
window.top.OG_ad_units = window.top.OG_ad_units || [];
window.top.OG_ad_units.push({
ad_unit_id: '$OGURY_AD_UNIT',
asset_key: '$OGURY_ASSET_KEY',
params:{
max_width: 180,
max_height: 180
},
callbacks: {
on_ad_show: onAdShowCallback,
on_no_ad: onNoAdCallback,
on_ad_complete: onAdCompleteCallback,
on_error: onErrorCallback,
}
});
</script>

Increase the Fill rate with a second Ad Unit

It is possible to implement a client side waterfall using the on_no_adcallback. Particularly, you may setup a sequence of Ogury Exclusive Demand Tag configurations to chain ad requests for distinct ad units.

A typical usage is to target an ad unit with a higher price and another one with a lower price afterwards. A waterfall involving these ad units allows to optimize your monetization and your fill rate.

Here is an example illustrating this usage:

<script type='text/javascript'>
function onNoAdCallback(adUnit) {
var adUnitConfigDisplay = document.createElement('script');
var adUnitConfigDisplayContent = `
window.top.OG_ad_units = window.top.OG_ad_units || [];
window.top.OG_ad_units.push({
ad_unit_id: '$OGURY_DISPLAY_AD_UNIT',
asset_key: '$OGURY_ASSET_KEY',
params:{
max_width: 180,
max_height: 180,
},
});`;
adUnitConfigDisplay.type = 'text/javascript';
adUnitConfigDisplay.text = adUnitConfigDisplayContent;
document.body.appendChild(adUnitConfigDisplay);
var tagJs = document.createElement('script');
tagJs.src = 'https://mwtw.presage.io/v1/tag.js';
tagJs.async = true;
document.body.appendChild(tagJs);
}
window.top.OG_ad_units = window.top.OG_ad_units || [];
window.top.OG_ad_units.push({
ad_unit_id: '$OGURY_VIDEO_AD_UNIT',
asset_key: '$OGURY_ASSET_KEY',
params:{
max_width: 180,
max_height: 180
},
callbacks: {
on_no_ad: onNoAdCallback,
}
});
</script>
  1. If you already have a video unit in place, ask your Publisher Manager to create a second Ad Unit or do so by yourself in the Publisher Cloud. Update your existing tag with the callback function for the new ad unit.

  2. If you don't use the Thumbnail yet, ask your Publisher Manager to create the necessary Assets and Ad Units, insert them into the tag above and integrate it in your website.

  3. If you already use the Thumbnail with a Passback, you can either add the second ad unit afterwards or before in the waterfall. If this solution doesn't serve you, please reach out to your Publisher Manager to discuss other options.

Configuration Parameters Details

Parameter

Required

Description

Example or Default Value

ad_unit_id

Yes

The ID of your ad unit

'97e72f94-91c2-4f16-acca-1b769146de3b'

asset_key

Yes

The asset key for your publisher account

'OGY-3FF6A2B9350D'

max_width

Yes

The desired max width in pixels the ad may take on your page

180

max_height

Yes

The desired max height in pixels, the ad may take on your page

180

gravity

No

The desired corner the ad may take on your page

'BOTTOM_RIGHT'

x_margin

No

The desired x axis margin in pixels the ad may take on your page

20

y_margin

No

The desired y axis margin in pixels the ad may take on your page

20

on_ad_show

No

Function that will be executed when the tag starts showing an ad

onAdShowCallback

on_no_ad

No

Function that will be executed when the tag has nothing to serve

onNoAdCallback

on_ad_complete

No

Function that will be executed when the tag has finished showing an ad

onAdCompleteCallback

on_error

No

Function that will be executed when an error prevents the ad delivery

onErrorCallback