遷移至 Config 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 })`
初始載入和單一請求架構 (SRA)	`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 } })`
SafeFrame	`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 } })`

舊版：

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 } })`
SafeFrame	`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 })`

舊版：

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')`
AdSense 屬性	`getAttributeKeys()`	`googletag.getConfig('adsenseAttributes')`
初始載入	`isInitialLoadDisabled()`	`googletag.getConfig('disableInitialLoad')`
指定目標	`getTargeting(key)`	`googletag.getConfig('targeting')`
指定目標	`getTargetingKeys()`	`googletag.getConfig('targeting')`

舊版：

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')`
AdSense 屬性	`getAttributeKeys()`	`Slot.getConfig('adsenseAttributes')`
類別排除條件	`getCategoryExclusions()`	`Slot.getConfig('categoryExclusion')`
指定目標	`getTargeting(key)`	`Slot.getConfig('targeting')`
指定目標	`getTargetingKeys()`	`Slot.getConfig('targeting')`

舊版：

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

遷移至 Config API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

設定頁面層級設定

AdSense 屬性

類別排除

置中

收合空白 div

初始載入和單一請求架構 (SRA)

延遲載入

位置

SafeFrame

指定目標

影片廣告

設定版位層級設定

AdSense 屬性

類別排除

點擊網址

收合空白 div

SafeFrame

指定目標

取得網頁層級設定

AdSense 屬性

初始載入

指定目標

取得版位層級設定

AdSense 屬性

類別排除

指定目標

遷移至 Config API