配置 API 迁移

本指南提供了一些示例，说明如何从旧版配置方法迁移到新的 Google 发布商代码 (GPT) 库 setConfig 和 getConfig API。

setConfig 和 getConfig API 提供了一种集中管理网页级和广告资源位级配置的方式。

设置页面级配置

下表列出了旧版 PubAdsService 配置方法与取代它们的新版 setConfig 方法之间的对应关系。

功能	旧版方法	setConfig 替换
AdSense 属性	set(key, value)	googletag.setConfig({ adsenseAttributes: { [key]: value } })
类别排除对象	clearCategoryExclusions()	googletag.setConfig({ categoryExclusion: null })
	setCategoryExclusion(label)	googletag.setConfig({ categoryExclusion: [label] })
居中	setCentering(centerAds)	googletag.setConfig({ centering: centerAds })
合拢空的 div	collapseEmptyDivs(collapseBeforeFetch)	googletag.setConfig({ collapseDiv: collapseBeforeFetch ? 'BEFORE_FETCH' : 'ON_NO_FILL' })
初始加载和单一请求架构 (SRA)	disableInitialLoad()	googletag.setConfig({ disableInitialLoad: true })
	enableSingleRequest()	googletag.setConfig({ singleRequest: true })
延迟加载	enableLazyLoad(config)	googletag.setConfig({ lazyLoad: config })
位置	setLocation(address)	googletag.setConfig({ location: address })
SafeFrame	setForceSafeFrame(force)	slot.setConfig({ safeFrame: { forceSafeFrame: force } })
	setSafeFrameConfig(config)	slot.setConfig({ safeFrame: config })
定位	clearTargeting(key)	googletag.setConfig({ targeting: { [key]: null } })
	setTargeting(key, value)	googletag.setConfig({ targeting: { [key]: value } })
视频广告	enableVideoAds()	googletag.setConfig({ videoAds: { enableVideoAds: true } })
	setVideoContent(contentId, cmsId)	googletag.setConfig({ videoAds: { videoContentId: contentId, videoCmsId: cmsId } })

AdSense 属性

旧版：

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

新：

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

---

类别排除

旧版：

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

新：

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

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

---

居中

旧版：

googletag.pubads().setCentering(true);

新：

googletag.setConfig({
  centering: true
});

---

收起空的 div

旧版：

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

新：

// 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'
});

---

初始加载和单一请求架构 (SRA)

旧版：

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

新：

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

---

延迟加载

旧版：

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,
});

新：

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,
  },
});

---

位置

旧版：

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

新：

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

---

SafeFrame

旧版：

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

新：

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

---

定位

旧版：

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

新：

// 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
});

---

视频广告

旧版：

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

新：

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

---

设置广告位级配置

下表列出了旧版 Slot 配置方法与取代它们的新版 setConfig 方法之间的对应关系。

功能	旧版方法	setConfig 替换
AdSense 属性	set(key, value)	Slot.setConfig({ adsenseAttributes: { [key]: value } })
类别排除对象	clearCategoryExclusions()	Slot.setConfig({ categoryExclusion: null })
	setCategoryExclusion(label)	Slot.setConfig({ categoryExclusion: [label] })
点击跟踪网址	setClickUrl(url)	Slot.setConfig({ clickUrl: url })
合拢空的 div	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 })
定位	clearTargeting(key)	Slot.setConfig({ targeting: { [key]: null } })
	setTargeting(key, value)	Slot.setConfig({ targeting: { [key]: value } })
	updateTargetingFromMap(config)	Slot.setConfig({ targeting: config })

AdSense 属性

旧版：

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

新：

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

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

---

类别排除

旧版：

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

新：

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

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

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

---

点击网址

旧版：

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

新：

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

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

---

合拢空的 div

旧版：

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

新：

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

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

---

SafeFrame

旧版：

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

新：

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

---

定位

旧版：

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']
});

新：

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']
  }
})

---

获取页面级配置

下表列出了旧版 PubAdsService getter 方法与取代它们的新 getConfig 方法之间的对应关系。

功能	旧版方法	setConfig 替换
AdSense 属性	get(key)	googletag.getConfig('adsenseAttributes')
	getAttributeKeys()	googletag.getConfig('adsenseAttributes')
初始加载	isInitialLoadDisabled()	googletag.getConfig('disableInitialLoad')
定位	getTargeting(key)	googletag.getConfig('targeting')
	getTargetingKeys()	googletag.getConfig('targeting')

AdSense 属性

旧版：

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

新：

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);

---

初始加载

旧版：

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

新：

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

---

定位

旧版：

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

新：

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);

---

获取广告位级配置

下表列出了旧版 Slot getter 方法与取代它们的新 getConfig 方法之间的对应关系。

功能	旧版方法	setConfig 替换
AdSense 属性	get(key)	Slot.getConfig('adsenseAttributes')
	getAttributeKeys()	Slot.getConfig('adsenseAttributes')
类别排除对象	getCategoryExclusions()	Slot.getConfig('categoryExclusion')
定位	getTargeting(key)	Slot.getConfig('targeting')
	getTargetingKeys()	Slot.getConfig('targeting')

AdSense 属性

旧版：

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

新：

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);

---

类别排除

旧版：

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

新：

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

---

定位

旧版：

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

新：

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);

---