參考資料

參數

網頁層級參數說明

這些參數只需在每個網頁上設定一次，就會影響網頁上所有單元。

必填

參數 說明和範例
adPage 使用者前往下一個或上一個結果頁面時，即為必要參數。

adPage 參數指明目前顯示廣告的結果頁面。當使用者已經瀏覽過搜尋結果的第一頁之後，系統即會使用這個參數。舉例來說，如果廣告請求數量為 5，且 adPage 參數設為 2，則傳回的廣告會是搜尋結果第二頁的五則廣告。

pubId 必要
這是您的 AdSense 用戶端 ID。您的 pubId 是用戶端 ID 的一部分，即「partner-」後方的字串。舉例而言，如果您的用戶端 ID 為「partner-test-property」，那麼 pubId 就是「test-property」。這是 CSA 的標準通訊協定。

範例：

'pubId' : 'test-property'
query 除了內容網頁的相關搜尋外，皆為必填。
這是使用者輸入的搜尋查詢。查詢參數的值需未經編碼。

注意：在內容網頁的相關搜尋中使用這個參數會導致意外結果。

例如：

'query' : 'flowers'
 
'query' : 'black & decker'
 
'query' : myQuery // myQuery is a variable containing the search query
resultsPageBaseUrl 網頁上有相關搜尋單元時，即為必要參數。
用來指定使用者按下相關搜尋字詞時顯示的搜尋結果網頁網址。resultsPageBaseUrl 可以包含本身的參數，但自動附加的搜尋查詢除外。

範例：

'resultsPageBaseUrl' : 'http://www.example.com/search?a=v1&b=v2'
relatedSearchTargeting 網頁上有相關搜尋單元時，即為必要參數。
要求相關搜尋單元時，必須使用這個參數。這項屬性會根據網頁內容，控管要顯示哪種類型的相關搜尋體驗：
  • 'content' 將這個選項用於內容網頁 (例如文章、部落格文章) 中的相關搜尋。
  • 'query' 請僅在搜尋結果網頁上使用這個選項，用於相關搜尋。

注意：根據預設，「relatedSearchTargeting」頁面參數會自動設為「query」。不過，請務必注意，這個預設值「僅」適用於搜尋結果網頁 (搜尋中的相關搜尋)。如果您在任何其他類型的網頁 (例如文章、網誌文章) 上使用相關搜尋，則必須明確將參數設為「content」。

注意：使用這個參數時必須遵守下列規範：

  • 視這個頁面參數的值而定，系統可能會啟用或停用特定的相關搜尋功能。
  • 在非搜尋結果網頁上誤用網頁類型，或使用預設的「查詢」設定來設定 relatedSearchTargeting 參數，都會被視為違反這些書面指示。
  • 無論是手動設定或使用預設值，Google 都會定期驗證這個值的準確性。

範例：

'relatedSearchTargeting' : 'content'
 
'relatedSearchTargeting' : 'query'
styleId 必要
用來指定網頁上廣告或相關搜尋單元所要套用自訂搜尋樣式的 ID。 進一步瞭解如何使用自訂搜尋樣式。請注意，如果已為要求設定 styleId，系統將以該樣式顯示廣告或相關搜尋，並略過舊有的樣式參數。如未在要求中指定 styleId，則會顯示系統預設樣式。

範例：

'styleId': '1234567890'

選用

參數 說明和範例
linkTarget 選用
用來指定獲得點擊的廣告會在同一個視窗還是新視窗中開啟。預設值為「_top」。您也可以在單元層級使用這個參數。
  • '_top'：在同一個視窗中開啟。
  • '_blank' 在新視窗中開啟。

範例：

'linkTarget' : '_blank'
referrerAdCreative 選用
如果使用者在其他網站上按下廣告或連結後抵達您的內容頁面，而該頁面包含「內容相關搜尋」單元，且該廣告或連結是由您控制，那麼這個參數應設為該廣告或連結的廣告素材文字 (一字不差)。

使用這個參數時必須遵守下列規範：

  • 這個參數只能在有「內容相關搜尋」要求時提供；如果是其他要求，系統一律會略過這個參數。
  • 這個參數只能用於您刻意從其他網站導入的流量，不得用於自然流量。
  • 這個參數應包含廣告或連結廣告素材中的標題行、說明和/或任何其他文字。
  • 從廣告或連結廣告素材中省略值 (或加入其他值) 一事，會被視為違反這些書面指示。
  • 不須區分大小寫。
  • 這個參數接受有效的 UTF-8 編碼；可使用萬國碼 (Unicode) 字元 / 變音符號。
  • Google 可能會使用或略過您提交的參數。一旦使用該參數，字詞的選擇和排名可能就會受到影響。

注意：使用 terms 參數時，必須提供此參數。

例如：

'referrerAdCreative': 'search for ads related to dental implants'

'referrerAdCreative': 'The Early Signs of Psoriatic Arthritis'
resultsPageQueryParam 選用
用來為搜尋結果網頁上的搜尋查詢指定網址參數的名稱。若未指定，預設會使用「q」。

範例：

'resultsPageQueryParam' : 'query'
terms 選用
這個參數可讓您提供一份清單，當中包含要與相關搜尋要求一併傳回的自有相關搜尋字詞，但 Google 不一定會使用這裡提供的字詞。

注意：使用這個參數時，referrerAdCreative 也是必要條件，relatedSearchTargeting 也是必要條件，且必須設為「content」。

例如：

'terms' : 'cars rental, flight ticket'
ignoredPageParams 選用
指定含有「內容相關搜尋」單元的內容網頁網址參數清單，可安全地忽略，不會影響核心內容或使用者體驗。

注意：Google 必須先檢索你的網頁，確保字詞與內容相關，網站才會顯示相關搜尋字詞。如果網頁尚未檢索，或是遭到 AdSense 檢索器 (例如 robots.txt) 封鎖，我們就不會顯示你提供給 Google 的建議相關搜尋字詞。

「內容相關搜尋」產品會使用 Google 的內容檢索系統為網頁建立索引，並產生相關搜尋字詞。如果網頁內容網址包含追蹤變數、使用者 ID、工作階段 ID 或其他動態 ID 等查詢參數，可能會干擾檢索器評估網頁核心內容的能力，並導致相關搜尋字詞不準確或不相關。這個網頁參數會指示 Google 的檢索器忽略這些非必要參數，確保正確建立內容索引，並減少不必要的檢索負載。這樣一來，Google 就能更準確地識別某個網頁是否已被檢索，並開始顯示建議字詞 (Google 和合作夥伴的字詞，如果符合資格)。

使用這個參數時必須遵守下列規範：

  • 這個參數只能在有「內容相關搜尋」要求時提供；如果是其他要求，系統一律會略過這個參數。
  • 這個參數的值應為以半形逗號分隔的網址參數清單，這些參數可能會在任何使用者前往內容頁面時顯示。
  • 須區分大小寫。
  • 當您從內容網頁的網址中移除這份清單中的任何網址參數時，網頁內容、外觀或使用者體驗不應受到重大影響。
  • 如果網址參數確實會大幅影響網頁內容、外觀或使用者體驗，就會違反這些書面操作說明。
  • Google 可能會定期驗證忽略提供的網址參數的效果。

範例：
使用者造訪內容網頁，網址如下： 

http://example.com/content?utm_medium=social&page_id=123&click_id=456
 提供下列可忽略的網址參數： 
'ignoredPageParams' : 'utm_medium,click_id,session_ref'
 會將內容網頁的網址視為： 
http://example.com/content?page_id=123

配置設定

參數 說明和範例
adsafe 選用
指定 Google 在比對搜尋查詢時套用至廣告的篩選規則。下列為 adsafe 的有效設定，以及每個值對傳回廣告造成的效果：
  • 'high'：傳回闔家適用廣告。不會傳回非闔家皆宜或成人色情內容的廣告。
  • 'medium'：傳回闔家皆宜和非闔家皆宜的廣告。不會傳回成人色情內容的廣告。
  • 'low'：傳回所有類型的廣告。

預設情況下，adsafe 會設為 high。

範例：

'adsafe': 'medium'
adtest 選用
adtest 參數用來指明廣告請求僅為測試用途。如果 adtest 參數的值為 on，Google 會將該請求視為測試，且不會計入廣告曝光或追蹤點閱結果。

如果 adtest 參數的值為 on，您不會獲得任何收益。

如果廣告請求的 adtest 參數設為「on」，且來自尚未 在「網站」分頁核准的網域，系統會傳回含有「測試廣告」疊加層且無法點按的廣告。

這個參數僅供測試，不得用於實際的廣告放送，否則就算刊登了廣告也不會為您帶來任何收益。

adtest 預設值是 off。

範例：

'adtest' : 'on'
channel 選用
您可以加入 AdSense 搜尋廣告管道，以追蹤不同網頁的成效。請使用您在 AdSense 帳戶中建立或由技術客戶經理建立的不重複管道 ID。如要進一步瞭解頻道，請參閱這篇文章。

如有多個管道，應使用「+」符號來區隔。

例如：

'channel' :  'testA'  
'channel' :  'testA+testB'
hl 選用
這個參數表示所請求廣告或相關搜尋的指定語言。預設值為 en。

Google 支援所有 AdWords API 語言代碼。

注意：廣告的指定語言是由廣告客戶自行設定的。如果您在要求中加入此參數，Google 只會傳回指定該語言 (或所有語言) 的廣告，但不能保證廣告文字一定是以指定語言撰寫。

一般來說，您應該將 hl 參數設為發送該參數的網頁主要語言。

例如：

'hl' : 'es'
ie 選填

ie 參數會設定應用於解讀查詢字串的字元編碼配置。

預設 ie 值為 utf-8。

值 標準名稱 支援語言
latin1 ISO-8859-1 西歐 (加泰隆尼亞文、丹麥文、荷蘭文、英文、芬蘭文、法文、德文、印尼文、義大利文、挪威文、葡萄牙文、西班牙文、瑞典文)
latin2 ISO-8859-2 東歐 (克羅埃西亞文、捷克文、匈牙利文、波蘭文、羅馬尼亞文、塞爾維亞文、斯洛伐克文、斯洛維尼亞文)
latin3 ISO-8859-3  
latin4 ISO-8859-4 波羅的海 (愛沙尼亞文、拉脫維亞文、立陶宛文)
cyrillic ISO-8859-5 保加利亞文、俄文
arabic ISO-8859-6  
希臘 ISO-8859-7 希臘文
hebrew ISO-8859-8 希伯來文
latin5 ISO-8859-9  
latin6 ISO-8859-10 冰島文
euc-jp EUC-JP 日文
euc-kr EUC-KR 韓文
sjis Shift_JIS 日文
big5 Big5 繁體中文
gb GB2312 簡體中文
utf-8 UTF-8 全部
oe 選填

oe 參數將決定 Google 用來為廣告文字編碼的字元編碼配置。儘管嚴格說來，此參數並非必要，但建議您最好還是設定一個值。

預設 oe 值為 utf-8。

值 標準名稱 支援語言
latin1 ISO-8859-1 西歐 (加泰隆尼亞文、丹麥文、荷蘭文、英文、芬蘭文、法文、德文、印尼文、義大利文、挪威文、葡萄牙文、西班牙文、瑞典文)
latin2 ISO-8859-2 東歐 (克羅埃西亞文、捷克文、匈牙利文、波蘭文、羅馬尼亞文、塞爾維亞文、斯洛伐克文、斯洛維尼亞文)
latin3 ISO-8859-3  
latin4 ISO-8859-4 波羅的海 (愛沙尼亞文、拉脫維亞文、立陶宛文)
cyrillic ISO-8859-5 保加利亞文、俄文
arabic ISO-8859-6  
希臘 ISO-8859-7 希臘文
hebrew ISO-8859-8 希伯來文
latin5 ISO-8859-9  
latin6 ISO-8859-10 冰島文
euc-jp EUC-JP 日文
euc-kr EUC-KR 韓文
sjis Shift_JIS 日文
gb GB2312 簡體中文
utf-8 UTF-8 全部
ivt 選用
您可以透過這個參數提供布林值，告知 Google 您希望允許使用無效流量專用 Cookie 和本機儲存空間的廣告，向已取得和未取得同意聲明的流量放送。
  • true 如果沒有這個參數，或是您將其設為「true」，我們會設定無效流量專用 Cookie，並只在取得同意聲明的流量中使用本機儲存空間。
  • false 如果您將這個參數設為「false」，我們會設定無效流量專用 Cookie，並且在已取得和未取得同意聲明的流量中使用本機儲存空間。

預設情況下，IVT 會設為 true。

範例：

'ivt': false

廣告單元層級參數說明

這些參數會影響網頁上個別廣告單元向使用者呈現的方式，您可以分別為每個廣告單元設定各項參數。

必填

參數 說明和範例
container 必要
要顯示廣告的空廣告容器 ID <div>。

範例：

'container' : 'afscontainer1'
maxTop 廣告單元位於搜尋結果上方時，必須提供此參數。

使用這個參數來指定要在頂端廣告單元顯示的廣告數量。

注意：這個參數可用來取代「number」參數。廣告單元的寬度必須足以完整容納廣告第一行的文字，避免發生換行的情形。在網頁上任何其他刊登位置使用 maxTop 參數都算違反政策規定。

範例：

'maxTop' : 4
width 必要
用來指定廣告或相關搜尋單元的寬度 (以像素為單位)。

範例：

'width' : '700px'
 
'width' : 700

配置設定

參數 說明和範例
adLoadedCallback 選用
指定在已載入廣告或相關搜尋，或是沒有放送任何廣告或沒有任何相關搜尋帶出廣告時，要呼叫的 JavaScript 函式。這個參數應設為您導入的 JavaScript 回呼函式，以便在廣告呼叫完成時執行動作。

回呼函式採用下列參數：

containerName 廣告或相關搜尋單元的容器名稱。
adsLoaded 有至少一個廣告或相關搜尋字詞可顯示時，即會設為 true；沒有傳回任何廣告或相關搜尋時，則會設為 false。
isExperimentVariant 如果正在進行自訂樣式實驗，並選擇實驗變化版本來顯示廣告，則會設為 true。
callbackOptions 內含下列欄位的 JSON 物件：
termPositions：以相關搜尋區塊來說，包含發布商提供字詞的 map<string,int> (與這些字詞在回應中的零索引位置對應)。如果有提供但未傳回字詞，字詞就不會出現在地圖中。

注意：請測試回呼函式，確保不會產生任何錯誤，尤其是可能干擾網頁載入的錯誤。

JavaScript 回呼範例：

var adblock1 = {
  'container' : 'adblock1_div_id',
  'adLoadedCallback' : function(containerName, adsLoaded,
    isExperimentVariant, callbackOptions) {
    if (adsLoaded) {
       try {
         // most likely do nothing
       } catch (e) {
         alert ("Error in callback function");
         // Do something to handle error gracefully
       }
    } else {
       // as you always do when there is no ad coverage from Google
    }
  }
};
number 選用
這個單元中顯示的廣告數量。預設值為 2。

範例：

'number' : 4
relatedSearches 選用
這個單元中顯示的相關搜尋次數。若未指定，預設值為 0。

範例：

'relatedSearches' : 4