Configuration

Contents

• Demo
• Overview
• Global GPT Configuration
  • Path
  • Targeting
  • Size Mappings
  • Custom Events
  • Lazy Loading
• Global Prebid Configuration
• Global Amazon TAM Configuration
• Slot GPT Configuration
  • ID
  • Slot Path
  • Collapse Empty Div
  • Slot Targeting
  • Sizes
  • Size Mapping Name
  • Lazy Loading
• Out of Page Slot GPT Configuration
  • ID
• Slot Prebid Configuration
  • Prebid Media Types
  • Bids
    • Bidder
    • Bid Parameters

Demo

You can check if your configuration is valid online in our react-advertising config validator:

Overview

To configure Google Publisher Tags (GPT) and Prebid and/or Amazon TAM, you create one central configuration object which you pass as config prop to the AdvertisingProvider component.

The overall structure of your configuration is as follows:

const config = {
  // global ad unit path, used if not specified in a slot (string)
  path,

  // global GPT targeting parameters and other key-values (object)
  targeting,

  // GPT size mapping definitions (object)
  sizeMappings,

  // global Amazon TAM configuration (object)
  aps,

  // global Prebid configuration (object)
  prebid,

  // Turn use of Prebid on or off (boolean)
  usePrebid,

  // configuration of custom events dispatched by the creatives (object)
  customEvents,

  // configuration to lazy load all ads (boolean or object)
  enableLazyLoad,

  // array of slot configurations
  slots: [
    {
      // slot ID
      id,

      // slot's ad unit path
      path,

      // configuration for removing empty slots
      collapseEmptyDivs,

      // targeting parameters and other key-values specific to the slot
      targeting,

      // slot size configuration for GPT
      sizes,

      // slot size configuration for GPT
      sizeMappingName,

      // configuration to lazy load this ad slot (boolean or object)
      enableLazyLoad,

      // array with slot's Prebid configuration objects
      prebid: [
        {
          // media types object for this Prebid config
          mediaTypes,

          // array of bid objects
          bids: [
            {
              // bidder ID
              bidder,

              // object with bidder-specific config
              params,
            },
          ],
        },
      ],
    },
  ],

  // array of outOfPageSlot configurations
  outOfPageSlots: [
    {
      // outOfPageSlot ID
      id,
    },
  ],
};

Hint: For an example of a complete, valid configuration, refer to testAdvertisingConfig.js in the source code, which is used for the unit tests of react-advertising.

Global GPT Configuration

Path

config.path

The ad unit path that is used for defining GPT slots, if there is no path specified in the GPT slot config.

You can also paths for individual slots (see section Slot Path in section “Slot GPT Configuration” below).

Type: String

Example:

const config = {
  path: "/19968336/header-bid-tag",
};

Targeting

config.targeting

An object of arbitrary parameters that are used to define global targeting parameters (also called key-values) for the slots using pubads.setTargeting of the GPT API.

Note that you can also define targeting parameters for individual slots (see section Slot Targeting in section “Slot GPT Configuration” below).

Type: Object

Example:

const config = {
  targeting: {
    gender: "female",
  },
};

See also: !googletag.PubAdsService setTargeting(key, value) (GPT reference)

Size Mappings

config.sizeMappings

An object with size mapping definitions to be used for responsive ads.

The object's keys are the size mapping names referenced from the configuration of each slot (see section Size Mapping Name in section “Slot GPT Configuration” below).

The object's values are arrays of objects with two properties:

• viewPortSize: The target view port size of the size mapping; array with two numbers for width and height
• sizes: Array of ad sizes to be displayed in this view port; array of arrays with two numbers for width and height
  • ⚠️ important: this needs to be an array, even if you have only one ad size to display for this viewport size
  • If you want to display no ads for this size, specify an empty array ([])

Type: Object

Example:

const config = {
  sizeMappings: {
    pageheader: [
      {
        // no ads default (mobile phones)
        viewPortSize: [0, 0],
        sizes: [],
      },
      {
        // tablets
        viewPortSize: [640, 60],
        sizes: [[468, 60]],
      },
      {
        // desktop
        viewPortSize: [1000, 250],
        sizes: [
          [800, 250],
          [970, 250],
        ],
      },
    ],
  },
};

The example above defines the following sizes:

• If less than 640 pixels screen width or less than 60 pixels screen height are available, display no ads (using [0, 0] acts as a default that is used if no other sizes fix)
• If at least 640 x 60 pixels are available, display a full size banner (468 x 60 pixels)
• If at least 1000 x 250 pixels are available, display a billboard (800 x 250 or 970 x 250, whichever is available and yields more revenue)

See also: Build Responsive Ads (Google Ad Manager documentation)

Custom Events

config.customEvents

Custom events allow you to pass callback functions to your AdvertisingSlot components using the customEventHandlers prop.

With these callback functions, you can trigger layout changes using events dispatched from the iframes delivered by the ad server. This is useful, for example, to set the page's background color to match a creative.

Type: Object

Example:

const config = {
  customEvents: {
    blueBackground: {
      eventMessagePrefix: "BlueBackground:",
    },
  },
};

See also: Custom Events

Lazy Loading

“Lazy loading” is a performance optimization technique to improve the page speed of your website. For more information and a code sandbox demo, refer to section “Lazy Loading” on page “Advanced Usage”.

config.enableLazyLoad

Type: Boolean or object

If you set enableLazyLoad to boolean value true, simple lazy loading is used for all slots, i.e. the slots are filled with ads as soon as they are scrolled into the browser viewport.

For advanced configuration, you can also specify an object, with the following properties:

• marginPercent: number; use this to add a margin to fill the ad slots before they move into the browser's viewport; this is a percentage of the current viewport height – for example, if you want to fill ad slots when they are half a viewport away from becoming visible, specify value 50
• mobileScaling: number; on mobile devices (phones), users tend to scroll through a page more quickly, so it makes sense to set a higher margin percentage for these users; the mobileScaling value is a factor in reference to the marginPercent – example: to fill ad slots when they are one viewport away from becoming visible on phones and half a viewport on desktop browsers, specify marginPercent: 50 and mobileScaling: 2

Examples:

// basic configuration:
// fill ad slots when they enter the browser viewport
const config = {
  enableLazyLoad: true,
};

// advanced configuration:
// fill ad slots when they are half a viewport height away on
// a desktop browser or one viewport height away on a mobile phone
const config = {
  enableLazyLoad: {
    marginPercent: 50,
    mobileScaling: 2,
  },
};

See also: Section “Lazy Loading” on page “Advanced Usage”.

Global Prebid Configuration

config.prebid

Allows you to specify global configuration options for Prebid.js, which are passed along using pbjs.setConfig.

Please refer to the Prebid documentation for details on which options you can provide.

Type: Object

Example:

const config = {
  prebid: {
    bidderTimeout: 1500,
    priceGranularity: "high",
    bidderSequence: "fixed",
  },
};

See also: pbjs.setConfig (Prebid.js API reference)

config.usePrebid

Optional, for rare use cases – allows you to control if Prebid is used or not.

Note that react-advertising automatically detects if the Prebid.js library has been loaded or not and enables Prebid accordingly, so usually, you do not have to set this yourself. It is intended for rare use cases where you don't want react-advertising to use Prebid, even though Prebid.js has been loaded.

Type: Object

Example:

const config = {
  usePrebid: false,
};

Global Amazon TAM Configuration

config.aps

Allows you to specify global configuration options for apstag.js.

Please refer to the Amazon TAM documentation for details on which options you can provide.

Type: Object

Example:

const config = {
  aps: {
    pubID: "yourPubId",
    bidTimeout: 2e3,
    deals: true
  },
};

config.useAPS

Allows you to enable or disable Amazon TAM globally. By default, Amazon TAM is enabled if you pass a valid config to config.aps. At present, there is no functionality in React Advertising to disable Amazon TAM at a slot level.

Type: boolean

Slot GPT Configuration

config.slots

An array of slot config objects, which are explained in the following sub-sections.

Type: Array of objects

ID

config.slots.id

The element ID of the div in your HTML code that is filled with the creative from the ad server. This ID corresponds to the id prop of the AdvertisingSlot component.

Required

Type: String

Example:

const config = {
  slots: [
    {
      id: "div-gpt-ad-1460505748561-0",
    },
  ],
};

See also: AdvertisingSlot component

Slot Path

config.slots.path

The ad unit path for this specific slot. If it is omitted, the ad unit path from the global GPT configuration is used. You must have either a slot specific or global ad unit path.

Type: String

Example:

const config = {
  slots: [
    {
      path: "'/19968336/header-bid-tag-0",
    },
  ],
};

See also: global ad unit path

Collapse Empty Div

config.slots.collapseEmptyDiv

Use this to remove div elements from the DOM when the ad server has no matching ad to serve for this slot.

The value is an array of one or two booleans, which determine the collapsing of empty div elements as follows:

• First bool: Whether to collapse the slot if no ad is returned
• Second bool: Whether to collapse the slot even before an ad is fetched; ignored if collapse is not true

Type: Array of booleans

Example:

const config = {
  slots: [
    {
      collapseEmptyDiv: [true, false],
    },
  ],
};

See also: !googletag.Slot setCollapseEmptyDiv(collapse, opt_collapseBeforeAdFetch) (GPT reference)

Slot Targeting

config.slots.targeting

An object of arbitrary parameters that are used to define targeting parameters (key-values) for the slot using slot.setTargeting of the GPT API.

Note that you can also define global targeting parameters for all slots (see section Targeting in section “Global GPT Configuration” below).

Type: Object

Example:

const config = {
  slots: [
    {
      targeting: {
        age: 27,
      },
    },
  ],
};

See also: !googletag.Slot setTargeting(key, value) (GPT reference)

Sizes

config.slots.sizes

Define one or more sizes for the ad slot. This is the size that is used in the ad request if no responsive size mapping is provided, or the size of the viewport is smaller than the smallest size provided in the mapping.

Note: More than one sizes is a DFP premium feature; if you use DoubleClick for Publishers Small Business, you can only specify one size.

Required

Type: Array of arrays (see examples)

Examples:

One size (array with width and height)

const config = {
  slots: [
    {
      sizes: [320, 50],
    },
  ],
};

Multiple sizes

const config = {
  slots: [
    {
      sizes: ["fluid", [300, 250], [320, 50], [320, 100]],
    },
  ],
};

See also: googletag.Slot googletag.defineSlot(adUnitPath, size, opt_div) (GPT reference)

Size Mapping Name

config.slots.sizeMappingName

The size mapping for responsive ads to be used for this slot. Corresponds to one of the size mappings you have configured in the global GPT configuration.

Type: String

Example:

const config = {
  slots: [
    {
      sizeMappingName: "pageheader",
    },
  ],
  sizeMappings: {
    pageheader: [
      {
        viewPortSize: [0, 0],
        sizes: [],
      },
      {
        viewPortSize: [640, 60],
        sizes: [[468, 60]],
      },
      {
        viewPortSize: [1000, 250],
        sizes: [
          [800, 250],
          [970, 250],
        ],
      },
    ],
  },
};

See also: Size Mappings

Lazy Loading

“Lazy loading” is a performance optimization technique to improve the page speed of your website. For more information and a code sandbox demo, refer to section “Lazy Loading” on page “Advanced Usage”.

config.slots.enableLazyLoad

Type: Boolean or object

If you set enableLazyLoad to boolean value true, simple lazy loading is used for this slot, i.e. the slot is filled with an ad as soon as it is scrolled into the browser viewport.

For advanced configuration, you can also specify an object, with the following properties:

• marginPercent: number; use this to add a margin to fill the ad slot before it moves into the browser's viewport; this is a percentage of the current viewport height – for example, if you want to fill the ad slot when it is half a viewport away from becoming visible, specify value 50
• mobileScaling: number; on mobile devices (phones), users tend to scroll through a page more quickly, so it makes sense to set a higher margin percentage for these users; the mobileScaling value is a factor in reference to the marginPercent – example: to fill the slot when it is one viewport away from becoming visible on phones and half a viewport on desktop browsers, specify marginPercent: 50 and mobileScaling: 2

Examples:

// basic configuration:
// fill ad slots when they enter the browser viewport
const config = {
  slots: [
    {
      enableLazyLoad: true,
    },
  ],
};

// advanced configuration:
// fill ad slots when they are half a viewport height away on
// a desktop browser or one viewport height away on a mobile phone
const config = {
  slots: [
    {
      enableLazyLoad: {
        marginPercent: 50,
        mobileScaling: 2,
      },
    },
  ],
};

See also: Section “Lazy Loading” on page “Advanced Usage”.

Out of Page Slot GPT Configuration

config.outOfPageSlots

An array of slot config objects, which are explained in the following sub-sections.

Type: Array of objects

ID

config.outOfPageSlots.id

The element ID of the div in your HTML code that is filled with the creative from the ad server. This ID corresponds to the id prop of the AdvertisingSlot component.

Required

Type: String

Example:

const config = {
  outOfPageSlots: [
    {
      id: "div-gpt-ad-oop-0",
    },
  ],
};

Slot Prebid Configuration

config.slots.prebid

An array of Prebid configuration objects, which are explained in the following sub-sections.

Note: In most cases, one Prebid config per slot will be sufficient (specify an array with just one object); you only need multiple ones if you have different bidders per media types configuration.

Required

Type: Array of objects, each with properties mediaTypes and bids

Prebid Media Types

config.slots.prebid.mediaTypes

Specify an object of media types for each Prebid configuration.

Refer to the Prebid media types documentation for details.

Required

Type: Object

Example:

const config = {
  slots: [
    {
      prebid: [
        {
          mediaTypes: [
            {
              banner: {
                sizes: [
                  [300, 250],
                  [300, 600],
                ],
              },
            },
          ],
        },
      ],
    },
  ],
};

See also: Prebid media types documentation

Bids

config.slots.prebid.bids

Specify an array of bids per slot and media types configuration.

Each bid object has a bidder and optional params property (see below).

Required

Type: Array of objects with properties bidder and optional params

Example:

const config = {
  slots: [
    {
      prebid: [
        {
          bids: [
            {
              bidder: "appnexus",
              params: {
                placementId: "10433394",
              },
            },
          ],
        },
      ],
    },
  ],
};

Bidder

config.slots.prebid.bids.bidder

The ID of the bidder (e.g. appnexus, ix, openex, etc.).

Refer to the Prebid bidder documentation to see which bidders are supported.

Required

Type: String

See also: Prebid bidder documentation

Bid Parameters

config.slots.prebid.bids.params

Parameters specific to the bidder. Refer to the Prebid bidder documentation to see which bidders uses which parameters.

Type: Object

See also: Prebid bidder documentation

---

← API | Custom Events →