參考資料

參數

網頁層級參數說明

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

必要

參數 說明和範例
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 如果網頁上有相關搜尋單元,則為必填。
指定搜尋查詢頁面的網址,也就是使用者所點擊的相關搜尋字詞。resultPageBaseUrl 可能會包含自己的參數,但會自動附加的搜尋查詢除外。

範例:

'resultsPageBaseUrl' : 'http://www.example.com/search?a=v1&b=v2'

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

範例:

'styleId': '1234567890'

選用

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

範例:

'linkTarget' : '_blank'

maxTermLength 選用
指定相關搜尋字詞的字元數上限 (包含空格)。 如未設定,則無上限。

範例:

'maxTermLength' : 50

referrerAdCreative 選用
如果使用者點按其他網站的廣告或連結後到達您的內容頁面,而該網頁包含「內容相關搜尋」單元,而該廣告或連結為您所有,則應將這個參數設為該廣告或連結的廣告素材文字,或所有內容。

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

  • 這個參數只能在有「內容相關搜尋」要求時提供;如為其他要求,則系統會忽略這個參數。
  • 這個參數只能用於您刻意從其他網站取得的流量,且絕不會用於自然流量。
  • 這個參數可以包含廣告或連結廣告素材的標題行和/或說明。
  • 不須區分大小寫。
  • 這個欄位接受有效的 UTF-8 編碼;支援萬國碼 (Unicode) 字元 / 變音符號。
  • Google 可能會使用或忽略您提交的參數。使用該參數可能會影響字詞的選擇和排名。

範例:

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

'referrerAdCreative': 'The Early Signs of Psoriatic Arthritis'

resultsPageQueryParam 選用
用來指定搜尋結果網頁上搜尋查詢的網址參數名稱。 如未指定,則預設值為「q」。

範例:

'resultsPageQueryParam' : 'query'

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

範例:

'terms' : 'cars rental, flight ticket'

配置設定

參數 說明和範例
adsafe 選用
用來指定 Google 對符合搜尋查詢的廣告套用的篩選規則。以下是 adsafe 的有效設定,以及每個值對傳回廣告的影響:
  • 'high' 傳回闔家適用廣告。不會傳回非闔家皆宜或成人色情內容的廣告。
  • 'medium' 傳回闔家皆宜和非闔家適用的廣告。不會傳回成人色情內容的廣告。
  • 'low'傳回所有類型的廣告。

adsafe 預設為「高」。

範例:

'adsafe': 'medium'

adtest 選用
adtest 參數會指出廣告的請求為測試。如果 adtest 參數的值是 on,Google 會將廣告請求視為測試,因此不會計入廣告曝光或追蹤點閱結果。

如果 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 有至少一個廣告或相關搜尋字詞可顯示時,設為 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