Config API migration

This guide provides examples for migrating from legacy configuration methods to the new Google Publisher Tag (GPT) library setConfig and getConfig APIs.

The setConfig and getConfig APIs provide a centralized way to manage both page- and slot-level configuration.

Set page-level configuration

The following table maps legacy PubAdsService configuration methods to their setConfig replacements.

Feature Legacy method setConfig replacement
AdSense attributes set(key, value) googletag.setConfig({ adsenseAttributes: { [key]: value } })
Category exclusion clearCategoryExclusions() googletag.setConfig({ categoryExclusion: null })
setCategoryExclusion(label) googletag.setConfig({ categoryExclusion: [label] })
Centering setCentering(centerAds) googletag.setConfig({ centering: centerAds })
Collapse empty divs collapseEmptyDivs(collapseBeforeFetch) googletag.setConfig({ collapseDiv: collapseBeforeFetch ? 'BEFORE_FETCH' : 'ON_NO_FILL' })
Initial load and Single Request Architecture (SRA) disableInitialLoad() googletag.setConfig({ disableInitialLoad: true })
enableSingleRequest() googletag.setConfig({ singleRequest: true })
Lazy loading enableLazyLoad(config) googletag.setConfig({ lazyLoad: config })
Location setLocation(address) googletag.setConfig({ location: address })
SafeFrame setForceSafeFrame(force) slot.setConfig({ safeFrame: { forceSafeFrame: force } })
setSafeFrameConfig(config) slot.setConfig({ safeFrame: config })
Targeting clearTargeting(key) googletag.setConfig({ targeting: { [key]: null } })
setTargeting(key, value) googletag.setConfig({ targeting: { [key]: value } })
Video ads enableVideoAds() googletag.setConfig({ videoAds: { enableVideoAds: true } })
setVideoContent(contentId, cmsId) googletag.setConfig({ videoAds: { videoContentId: contentId, videoCmsId: cmsId } })

AdSense attributes

Legacy:

googletag.pubads().set('document_language', 'en');

New:

googletag.setConfig({
  adsenseAttributes: {
    document_language: 'en'
  }
});

Category exclusion

Legacy:

googletag.pubads().setCategoryExclusion('AirlineAd');
googletag.pubads().clearCategoryExclusions();

New:

// Set category exclusion
googletag.setConfig({
  categoryExclusion: ['AirlineAd']
});

// Clear category exclusions
googletag.setConfig({
  categoryExclusion: null
});

Centering

Legacy:

googletag.pubads().setCentering(true);

New:

googletag.setConfig({
  centering: true
});

Collapse empty divs

Legacy:

googletag.pubads().collapseEmptyDivs(true); // Collapse before fetch
googletag.pubads().collapseEmptyDivs(false); // Collapse on no fill

New:

// Collapse before fetch
googletag.setConfig({
  collapseDiv: 'BEFORE_FETCH'
});

// Collapse on no fill
googletag.setConfig({
  collapseDiv: 'ON_NO_FILL'
});

// Don't collapse
googletag.setConfig({
  collapseDiv: 'DISABLED'
});

Initial load and Single Request Architecture (SRA)

Legacy:

googletag.pubads().disableInitialLoad();
googletag.pubads().enableSingleRequest();

New:

googletag.setConfig({
  disableInitialLoad: true,
  singleRequest: true
});

Lazy loading

Legacy:

googletag.pubads().enableLazyLoad({
  // Fetch slots within 5 viewports.
  fetchMarginPercent: 500,
  // Render slots within 2 viewports.
  renderMarginPercent: 200,
  // Double the above values on mobile.
  mobileScaling: 2.0,
});

New:

googletag.setConfig({
  lazyLoad: {
    // Fetch slots within 5 viewports.
    fetchMarginPercent: 500,
    // Render slots within 2 viewports.
    renderMarginPercent: 200,
    // Double the above values on mobile.
    mobileScaling: 2.0,
  },
});

Location

Legacy:

googletag.pubads().setLocation('10001,US');

New:

googletag.setConfig({
  location: '10001,US'
});

SafeFrame

Legacy:

googletag.pubads().setForceSafeFrame(true);
googletag.pubads().setSafeFrameConfig({sandbox: true});

New:

googletag.pubads().setConfig({
  safeFrame: {
    forceSafeFrame: true,
    sandbox: true
  }
});

Targeting

Legacy:

googletag.pubads().setTargeting('interests', 'sports');
googletag.pubads().setTargeting('interests', ['sports', 'music']);
googletag.pubads().clearTargeting('interests');
googletag.pubads().clearTargeting();

New:

// Set targeting
googletag.setConfig({
  targeting: {
    interests: 'sports'
  }
});

// Set multiple values
googletag.setConfig({
  targeting: {
    interests: ['sports', 'music']
  }
});

// Clear a specific key
googletag.setConfig({
  targeting: {
    interests: null
  }
});

// Clear all targeting
googletag.setConfig({
  targeting: null
});

Video ads

Legacy:

googletag.pubads().enableVideoAds();
googletag.pubads().setVideoContent('video123', 'cms456');

New:

googletag.setConfig({
  videoAds: {
    enableVideoAds: true,
    videoContentId: 'video123',
    videoCmsId: 'cms456'
  }
});

Set slot-level configuration

The following table maps legacy Slot configuration methods to their setConfig replacements.

Feature Legacy method setConfig replacement
AdSense attributes set(key, value) Slot.setConfig({ adsenseAttributes: { [key]: value } })
Category exclusion clearCategoryExclusions() Slot.setConfig({ categoryExclusion: null })
setCategoryExclusion(label) Slot.setConfig({ categoryExclusion: [label] })
Click URL setClickUrl(url) Slot.setConfig({ clickUrl: url })
Collapse empty divs setCollapseEmptyDiv(collapse, collapseBeforeFetch) Slot.setConfig({ collapseDiv: collapse ? (collapseBeforeFetch ? 'BEFORE_FETCH' : 'ON_NO_FILL') : 'DISABLED' })
SafeFrame setForceSafeFrame(force) Slot.setConfig({ safeFrame: { forceSafeFrame: force } })
setSafeFrameConfig(config) Slot.setConfig({ safeFrame: config })
Targeting clearTargeting(key) Slot.setConfig({ targeting: { [key]: null } })
setTargeting(key, value) Slot.setConfig({ targeting: { [key]: value } })
updateTargetingFromMap(config) Slot.setConfig({ targeting: config })

AdSense attributes

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
slot.set('adsense_background_color', '#FFFFFF');

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');

slot.setConfig({
  adsenseAttributes: {
    adsense_background_color: '#FFFFFF'
  }
});

Category exclusion

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
slot.setCategoryExclusion('AirlineAd');
slot.clearCategoryExclusions();

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');

// Set category exclusion
slot.setConfig({
  categoryExclusion: ['AirlineAd']
});

// Clear category exclusions
slot.setConfig({
  categoryExclusion: null
});

Click URL

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
slot.setClickUrl('http://www.example.com?original_click_url=');

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');

slot.setConfig({
  clickUrl: 'http://www.example.com?original_click_url='
});

Collapse empty div

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
slot.setCollapseEmptyDiv(true, true); // Collapse before fetch

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');

slot.setConfig({
  collapseDiv: 'BEFORE_FETCH'
});

SafeFrame

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
slot.setForceSafeFrame(true);
slot.setSafeFrameConfig({sandbox: true});

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
slot.setConfig({
  safeFrame: {
    forceSafeFrame: true,
    sandbox: true
  }
});

Targeting

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
slot.setTargeting('allow_expandable', 'true');
slot.clearTargeting('allow_expandable');
slot.updateTargetingFromMap({
  color: 'red',
  interests: ['sports', 'music', 'movies']
});

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');

// Set targeting
slot.setConfig({
  targeting: {
    allow_expandable: 'true'
  }
});

// Clear targeting
slot.setConfig({
  targeting: {
    allow_expandable: null
  }
});

// Update targeting (only specified KVs are set/modified).
slot.setConfig({
  targeting: {
    color: 'red',
    interests: ['sports', 'music', 'movies']
  }
})

Get page-level configuration

The following table maps legacy PubAdsService getter methods to their getConfig replacements.

Feature Legacy method setConfig replacement
AdSense attributes get(key) googletag.getConfig('adsenseAttributes')
getAttributeKeys() googletag.getConfig('adsenseAttributes')
Initial load isInitialLoadDisabled() googletag.getConfig('disableInitialLoad')
Targeting getTargeting(key) googletag.getConfig('targeting')
getTargetingKeys() googletag.getConfig('targeting')

AdSense attributes

Legacy:

const documentLangauage = googletag.pubads().get('document_language');
const adsenseAttributes = googletag.pubads().getAttributeKeys();

New:

const adsenseConfig = googletag.getConfig('adsenseAttributes').adsenseAttributes;

// Get the value of a single AdSense attribute.
const documentLanguage = adsenseConfig.document_language || null;

// Get all configured AdSense attribute keys.
const adsenseAttributes = Object.keys(adsenseConfig);

Initial load

Legacy:

const isDisabled = googletag.pubads().isInitialLoadDisabled();

New:

const isDisabled = googletag.getConfig('disableInitialLoad').disableInitialLoad;

Targeting

Legacy:

const targeting = googletag.pubads().getTargeting('interests');
const keys = googletag.pubads().getTargetingKeys();

New:

const targetingConfig = googletag.getConfig('targeting').targeting;

// Get targeting for a specific key.
const targeting = targetingConfig.interests || [];

// Get all targeting keys.
const keys = Object.keys(targetingConfig);

Get slot-level configuration

The following table maps legacy Slot getter methods to their getConfig replacements.

Feature Legacy method setConfig replacement
AdSense attributes get(key) Slot.getConfig('adsenseAttributes')
getAttributeKeys() Slot.getConfig('adsenseAttributes')
Category exclusion getCategoryExclusions() Slot.getConfig('categoryExclusion')
Targeting getTargeting(key) Slot.getConfig('targeting')
getTargetingKeys() Slot.getConfig('targeting')

AdSense attributes

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
const bgColor = slot.get('adsense_background_color');
const adsenseAttributes = slot.getAttributeKeys();

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
const adsenseConfig = slot.getConfig('adsenseAttributes').adsenseAttributes;

// Get the value of a single AdSense attribute.
const bgColor = adsenseConfig.adsense_background_color || null;

// Get all configured AdSense attribute.
const adsenseAttributes = Object.keys(adsenseConfig);

Category exclusion

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
const exclusions = slot.getCategoryExclusions();

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
const exclusions = slot.getConfig('categoryExclusion').categoryExclusion || [];

Targeting

Legacy:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
const targeting = slot.getTargeting('allow_expandable');
const keys = slot.getTargetingKeys();

New:

const slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div');
const targetingConfig = slot.getConfig('targeting').targeting;

// Get targeting for a specific key.
const targeting = targetingConfig.allow_expandable || [];

// Get all targeting keys.
const keys = Object.keys(targetingConfig);