Yield Manager

Ad Units

Ad Units are representations of spaces on your website where you want ads to render/show up.

By defining your Ad Units in Yield Manager, you can specify the areas where advertising can be displayed to your audience, which sizes are valid for these areas, at which time, and under what conditions they should get rendered, and many other important and useful things that you can find below.

The Placements tab in the Yield Manager App is where you can handle Placements, Ad Units, and HTML Units. These are the basic blocks of your setup, and each one of them has its own table where you can define them.

Ad Units and Placements

In Yield Manager, the conceptual idea of Ad Units is split into two parts: Placements and Ad Units.

A Placement will hold information about places on your page, whereas Ad Units will hold information such as the size and the bidders that can bid on that Ad Unit. Once you have your Ad Units defined, you can associate them with the Placements you have.

Placements table

In the Placements table, you can define the following:

Ad Units table

In the Ad Units table, you can define the following:

Importing Ad Units from JSON

In both the Ad Units and Placements table, you can import units from a JSON object, which can be used to speed up the migration process of your current setup to Yield Manager.

How to import

In order to import Ad Units from a JSON object, click the upload icon () on the Ad Units table. This will bring up a modal where you can paste your JSON object to start the extraction process.

After you paste a valid JSON object, a preview component can be seen at the bottom of the modal. By expanding it, you should see which Ad Units and Placements will get added to the workspace if you decide to proceed.

Once you click Import, the Ad Units will get added to the Ad Units table.

JSON object format

The provided JSON object must be an array containing objects that conform to the Prebid Ad Units object. But every Ad Unit should also have an mandatory extra property: path. Additionally, you can also give every ad unit a name property.

With the exception of code and path, all other properties are optional. Ad Units can't be generated from invalid "code" and "path" values, but if you provide invalid values to optional fields (e.g. mediaTypes: null), these will get simply ignored.

Below is a basic example:

[
    {
        code: 'div-0',
        path: '/19968336/header-bid-tag-0',
        mediaTypes: {
            banner: { sizes: [[300, 250], [300, 600]] }
        },
        bids: [{
            bidder: 'appnexus',
            params: { placementId: 13144370 }
        }]
    },
    {
        code: 'div-1',
        path: '/19968336/header-bid-tag-1',
        mediaTypes: {
            banner: { sizes: [728, 90] }
        },
        bids: [{
            bidder: 'appnexus',
            params: { placementId: 13144370 }
        }]
    }
]

Bidders

In the Bidders tab, you can set up information about your Prebid Bidders adapters.

Prebid Bidders table

This is where you specify all of your Prebid Bidders at the Entity level. In this table, you can set up the parameters for each Bidder.

Adding a new Bidder

In order to add new Bidders to your setup, you can use the dropdown located at the right corner of the table. When expanded, you can see all built-in Bidders available. If you don't find a bidder, you can simply type in the name and create a new Bidder from it.

Bidders Parameters

In Yield Manager, you can specify Parameters for Bidders in multiple ways.

The simplest way to set them is by using the Params column in the Prebid Bidders table. By clicking on it, you can see and change which parameters will be used with that Bidder.

When adding a built-in Bidder, required parameters will already be selected, but you can also select any other optional parameters or even add custom ones if they are not listed.

Another more advanced way to specify the Params for a given Bidder is by changing the Params Template column value.

Params Template column

By clicking on it, a code editor will open, allowing you to manually define which parameters that Bidder should have.

Keep in mind that this will override any parameters that are specified in the Params column, which means that if you don't specify the same params that were previously set before saving the changes, you will lose all data on the Placement IDs table that were associated with these parameters. The same thing would happen if you unset the params column (by clicking on the icon on the top right corner of the cell) without adding the previous params to the Params column.

So, by manually editing this field, the Params column will be ignored, and only referenced params will be in the PlacementID table.

The Params Template column is very useful for scenarios where you have static parameters that don't change based on Ad Units or domains and you don't want them to show on the Placement Ids table. In this case, you can directly add param values that are static, e.g.: { floor: 0.5 }. In the case of params whose values change based on the Ad Unit ID or page Domain (e.g. placementId, siteId), you should add them as the following: { siteId: [[siteId]] }. Where each parameter name inside '[[' and ']]' will be available as a parameter column inside the Placement IDs table.

Please note that if the param is a string you should add the reference inside quotes: { siteId: "[[siteId]]" }.

Overriding Bidders Params for an Ad Unit

If you need, you can override what should be the Bidder Params for a given Ad Unit.

In the Ad Unit table, each Ad Unit has an expandable row where you can see all the bidders and params for that Ad Unit. If the value is grayed out, it is using the params specified in the Prebid Bidders table, otherwise, the Prebid Bidders table params are being overridden. If you want to use the default ones, you can simply click on the button located at the top right corner of the cell.

If you override the params with an empty object (i.e. {}), you will disable that bidder for that Ad Unit. Another way to achieve that is by letting all params in the Placement IDs table empty (i.e. "") for that Ad Unit.

Placement IDs table

The Placement IDs table is where you specify the values for params that are set in the Prebid Bidders table. All params that were defined there will show here as columns under each respective Bidder.

The table allows you to directly modify parameters in a seamless spreadsheet-like experience. Additionally, it allows you to create multiple groups to override your default/base parameters based on a condition, for example, domain name.

The default group (the first-row group) needs to have all its values set (even if you want to use an empty value, e.g. ""). Other params groups, on the other hand, can have their cells inherit values from the default params group. You can do that by double-clicking on a cell that is not from the Default group and clicking on the button on the right side of the input. If you don't see it, then that cell is already inheriting its value from the Default group.

Import params from JSON

Similar to how you can import ad units from JSON data, you can also import bidders' params for params groups from JSON data.

First, you need a group that is not the default one. Then, you can proceed by clicking on the icon located at the right side of the group name.

The JSON structure is similar to the ad units one, but the only mandatory fields are 'code' and the 'bids' array.

For ad units, you can also provide a 'name' field, in which case it will match the ad unit by the exact name and ignore the 'code' field. If the ad unit's 'name' is not provided, it will match all ad units by finding the Placement with the provided code and targeting all Ad Units that are associated with that Placement.

For the bids array, entries must have the mandatory 'bidder' and 'params' fields. And you can also specify an optional 'name' field, this is especially useful for scenarios where you have duplication of bidders in your JSON. By specifying the 'name' field for bidders, the match will be done by the name, otherwise, the match will be done by the order in which your bidders were added to the Bidders table, from the most recent one to the oldest.

Params that are not specified in the Bidders Params table will be ignored as well as Ad Units or Bidders that don't exist in your setup.

Below is a basic example:

[
    {
        code: 'header',
        bids: [{
            bidder: 'pubmatic',
            params: { publisherId: '13144370' }
        }]
    },
    {
        code: 'ignored',
        name: 'my-ad-unit-2',
        bids: [{
            bidder: 'appnexus',
            params: { placementId: 13144370 }
        },{
            name: 'appnexus-2'
            bidder: 'appnexus',
            params: { placementId: 13144371 }
        }]
    }
]

Namespace

The Namespace is the aggregation of Variables, Conditions, and Triggers.

Variables

Variables are a very important part of Yield Manager, they can be used both inside values (e.g. inside the style field of Ad Units) and inside conditions.

In Yield Manager, you have a great number of built-in variables and you can also add your own custom variables.

Condition sets

A condition set is defined by a name and a set of inner conditions. Each of these inner conditions is an expression constituted by a name, an operator, and a value.

Operators

There are many available operators for inner conditions: equal, less than, less than or equal, greater than, greater than or equal, not equal, contains, starts with, ends with, regex, does not contain, does not start with, does not end with, and not regex. Note that numeric comparison operators will cast the provided string values to Number before evaluation.

Triggers

On each page change, all enabled Ad Units will get injected on the page, meaning that the HTML code associated with each ad unit will get added to the page. However, an Ad Unit will only be activated and rendered when its trigger fires.

So a trigger decides when a given Ad Unit/HTML Unit should be activated on the page. They contain an event and 0 or more condition sets.

When the associated event fires, if all condition sets evaluate to be true, the ad unit will be activated and begin to participate in auctions.

If no trigger is specified for an ad unit, it will use the default trigger: onLoad.

Trigger Events

A trigger can use one of the events below to decide when it will evaluate its condition sets to decide if it activates the associated Ad Units on the page.

Settings

In the settings tab, you can find general settings that will affect how the Yield Manager script works.

You can find more generic settings in the Yield Manager tab and settings that are specific to Prebid.js in the Prebid.js tab.

Yield Manager

General settings related to the Yield Manager script, which is the script that will run on the page and handle the auctions and the settings from deployed versions.

Yield Manager Script Version

You can select the desired Yield Manager script version by using the dropdown found on the settings page, under the Yield Manager tab.

Whenever new features are released that are not compatible with the selected Yield Manager script version, you will see a badge notifying you that you should change your current version to one that is compatible.

Prebid.js

Settings specific to Prebid.js.

Custom bid pool feature

With this feature, Yield Manager will gather all bids into a single pool and assign the highest ones to compatible Ad Units regardless of their original Ad Units association.

Yield Manager always takes the bid's TTL into consideration and only makes replacements when there's a match between the Ad Unit and bid sizes.

Filters can be provided to help Yield Manager decide which bidders and Ad Units should be considered when handling the custom bid pool.

Include and Exclude filters

• Include: If not provided, the inclusion set will be composed of all 'Ad Unit Identifier Names'/'bids'. Otherwise, the inclusion set will be composed of provided values.
• Exclude: If not provided, the inclusion set will be considered in totality. Otherwise, provided values will be used to filter the inclusion set.

Yield Manager Client Script

Ad unit instances

You define your Ad Units in the Ad Units and Placements Tables. But when the Yield Manager script is running, we have the concept of Ad Unit Instances. Each instance is based on a given Ad Unit you defined. But one Ad Unit can have multiple instances associated with it. As a result, the Ad Unit Instances will have something called Ad Unit Instance Code, which will always be variants of the Ad Unit Identifier Name you define in the table.

For example, when defining an Ad Unit and associating it with a Placement that have 'inject=false' and placing its 'manual placement code' multiple times on the page or when defining a 'placement' query string that matches several elements on the page, the Ad Unit will result in multiple Ad Unit Instances being placed on the page.

ayManagerEnv

The global namespace that Yield Manager uses for its API.

cmd

Reference to the command queue for asynchronous execution of Yield Manager's related calls.

In order to add asynchronous calls to Yield Manager's command queue, one must call the .push() method passing a function (with the desired code in it) as an argument.

When the Yield Manager script loads, it will loop through the ayManagerEnv.cmd array and execute all provided functions in order.

Note that you should make sure that there's an array on the page that you can push calls to. If it is possible that the Yield Manager script is not loaded yet at the time you are pushing these calls, you should initialize an empty array yourself as shown below.

<script>
    window.ayManagerEnv = window.ayManagerEnv || { cmd: [] };

    window.ayManagerEnv.cmd.push(() => {
        console.log("when the Yield Manager script finally loads, it will run this code.")
    });

</script>

ayManagerEnv.cmd

/** @type { Array<() => void> } */

refresh

Makes a new request for bids and refreshes the Ad Units slots with new ad content.

If a mode is provided through the options parameter, the given Ad Units will only be refreshed if they met the mode criteria. If no mode is provided, the 'page' mode is the default.

The available modes are:

• visible: Will refresh only Ad Units that are visible at the time.
• near: Will refresh only Ad Units that are inside the given offset.
• page: Will refresh only Ad Units whose container can be queried on the page.

ayManagerEnv.refresh([adUnitCodes], [options]);

/**
 * @param { Array<String> } [adUnitCodes]
 * @param { Object } [options]
 * @param { ("visible"|"near"|"page") } [options.mode]
 * @param { Number } [options.offset]
 * @param { Boolean } [options.useInstanceCodes]
 * @returns { void }
 */

reset

Destroy the ad unit slots, reset their status, and remove their container from the page.

If a mode is provided through the options parameter, the given Ad Units will only be reset if they meet the mode criteria. If no mode is provided, the 'page' mode is the default.

The available modes are:

• visible: Will reset only Ad Units that are visible at the time.
• near: Will reset only Ad Units that are inside the given offset.
• page: Will reset only Ad Units whose container can be queried on the page.

ayManagerEnv.reset([adUnitCodes], [options]);

/**
 * @param { Array<String> } [adUnitCodes]
 * @param { Object } [options]
 * @param { ("visible"|"near"|"page") } [options.mode]
 * @param { Number } [options.offset]
 * @param { Boolean } [options.useInstanceCodes]
 * @returns { void }
 */

destroy

Destroy the ad unit instances. Additionally, Ad Units with inject=true will have the placement elements found by the ad unit's placement string marked with an attribute, so they get ignored in the following calls to ayManagerEnv.changePage(). In order to revert this, you have to call the ayManagerEnv.restore() API method.

If a mode is provided through the options parameter, the given Ad Units will only be reset if they met the mode criteria. If no mode is provided, the 'page' mode is the default.

The available modes are:

• visible: Will destroy only Ad Units that are visible at the time.
• near: Will destroy only Ad Units that are inside the given offset.
• page: Will destroy only Ad Units whose container can be queried on the page.

ayManagerEnv.destroy([adUnitCodes], [options]);

/**
 * @param { Array<String> } [adUnitCodes]
 * @param { Object } [options]
 * @param { ("visible"|"near"|"page") } [options.mode]
 * @param { Number } [options.offset]
 * @param { Boolean } [options.useInstanceCodes]
 * @returns { void }
 */

restore

This method is supposed to be called after one has called the destroy API method. It will revert the second step of the destroy method, that is, it will restore all the placement elements found by the ad unit's placement string. With that, future calls to ayManagerEnv.changePage will stop ignoring them.

ayManagerEnv.restore([adUnitCodes]);

/**
 * @param { Array<String> } [adUnitCodes]
 * @returns { void }
 */

changePage

Calling this function will trigger the page change flow, that is, it will:

1. reset Ad Units/HTML units whose 'enable if' conditions and trigger conditions are no longer valid
2. handle Ad Units/HTML units that have been removed from the DOM
3. inject all HTML units and inject Ad Units that have the inject column enabled

As a result, this method can be used with infinite scroll layouts to inject new Ad Units as the user scrolls further.

Important: This method should be called only when all the elements that compose the new page are placed in the DOM. Otherwise, when trying to inject new Ad Units, the 'Placement' string used by Yield Manager in its query will not be able to find these new elements.

ayManagerEnv.changePage();

/**
 * @returns { void }
 */

dispatchManualEvent

Fires the manual event used by triggers. Although this event will fire only after being called, it will only be fired after the DOMContentLoad event has been fired.

ayManagerEnv.dispatchManualEvent();

/**
 * @returns { void }
 */

onEvent

This allows the page to register a callback function that is invoked when events are fired.

ayManagerEnv.onEvent(eventName, callback);

/**
 * @param { ("error"|"beforePageChange"|"afterPageChange") } eventName
 * @param { Function } callback
 * @returns { void }
 */

offEvent

Turns off an event callback defined with onEvent.

ayManagerEnv.offEvent(eventName, callback);

/**
 * @param { ("error"|"beforePageChange"|"afterPageChange"|"beforeDefineSlot"|"afterDefineSlot"|"beforeRefresh"|"afterRefresh") } eventName
 * @param { Function } callback
 * @returns { void }
 */

Yield Manager Events

Below you can find a list of all events that Yield Manager emits. You can register listeners to these events by using the onEvent API method.

• Note: This events arguments and when it's being emitted may change in future versions.

Callback arguments

beforeDefineSlot

afterDefineSlot

beforeRefresh

afterRefresh

Turn on Yield Manager debug messages

You can enable debug messages in three ways:

URL Parameters

Add ay_manager_debug=true to the page’s URL Parameters.

For example:

www.my-page.com/my-page.html?ay_manager_debug=true

Local storage

Add the following entry in LocalStorage: ay_manager_debug=true

For example:

localStorage.setItem('ay_manager_debug', true)

ayManaverEnv

You can also set the debug property on Yield Manager's Namespace: ayManaverEnv.debug=true.