參考資料

參數

網頁層級參數說明

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

需要

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

adPage 參數會指定要顯示廣告的結果頁面。當使用者已經離開搜尋結果的第一頁時，即會使用此參數。舉例來說，如果請求五則廣告，且 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 如果網頁上有相關搜尋單元，則為必填。
指定搜尋查詢是使用者所按下相關搜尋字詞的搜尋結果網頁網址。resultPageBaseUrl 可能包含本身的參數，但會自動附加的搜尋查詢除外。

範例： 

'resultsPageBaseUrl' : 'http://www.example.com/search?a=v1&b=v2'
relatedSearchTargeting 如果網頁上有相關搜尋單元，則為必填。
要要求相關搜尋單元時，這個參數為必要。這項功能可依據網頁情境，控管要顯示的相關搜尋體驗類型：
  • 'content' 這個選項適用於內容網頁上的相關搜尋 (例如文章、網誌文章)。
  • 'query'請為搜尋結果網頁上的相關搜尋使用專屬選項。

注意：relatedSearchTarget 網頁參數預設會自動設為「query」。不過請務必注意，這個預設值「只」是針對搜尋結果網頁 (「搜尋」上的相關搜尋) 所設計。如要在任何其他類型的網頁 (例如文章、網誌文章) 上使用相關搜尋，則必須明確將參數設為「content」。

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

  • 視這個網頁參數的值而定，某些相關的搜尋功能可以啟用或停用。
  • 在非搜尋結果網頁中，針對相關搜尋指定參數的不實陳述或行為，或依賴相關搜尋指定參數的預設「查詢」設定，即視為違反這些書面指示。
  • 無論是手動設定或使用預設值，Google 都會定期驗證這個值的準確率。

例：

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

範例： 

'styleId': '1234567890'

選用

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

範例： 

'linkTarget' : '_blank'
maxTermLength 選用
指定相關搜尋字詞的字元數上限 (含空格)。 如未設定，則無上限。

範例： 

'maxTermLength' : 50
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 封鎖 (例如遭到 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 預設為高。

範例： 

'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 希臘文
希伯來曆 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 希臘文
希伯來曆 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，並將本機儲存空間用於已同意和未同意的流量。

無效流量預設為 true。

範例： 

'ivt': false

廣告單元層級參數說明

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

需要

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

範例： 

'container' : 'afscontainer1'
maxTop 如果廣告單元位於搜尋結果上方，則為必填。

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

注意：此參數可用來取代「number」參數。這個廣告單元的寬度必須夠寬，這樣廣告第一行就不會換行。在網頁上任何其他刊登位置使用 maxTop 參數都違反政策。

示例：

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

範例： 

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

配置設定

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

回呼函式採用下列參數：

containerName 廣告或相關搜尋單元的容器名稱。
adsLoaded 有至少一個廣告或相關搜尋字詞可以顯示時，設為「是」；沒有傳回任何廣告或相關搜尋時，則設為「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