参考文档

参数

页面级参数说明

这些参数只需为每个网页指定一次。 它们会影响网页上的所有广告单元。

必需

参数 说明和示例
adPage 当用户前往下一个结果页或上一个结果页时,必须提供。

adPage 参数用于指定显示广告的结果页。当用户越过搜索结果的第一页时,系统就会使用此参数。例如,如果系统请求了 5 个广告,且 adPage 参数设为 2,则返回的广告将会是 5 个广告的第二页。

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'

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 设为“high”。

示例:

'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 将仅返回定位到相应语言或所有语言的广告,但 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 All
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 All
ivt 可选
借助此参数,您可以提供一个布尔值,以告知 Google 您希望允许针对已征得用户同意和未征得用户同意的流量使用仅用于检测无效流量的 Cookie 和本地存储的广告。
  • true如果此参数不存在或您将其设为“true”,我们会设置仅用于检测无效流量的 Cookie,并仅针对已征得用户同意的流量使用本地存储。
  • false如果您将此参数设为“false”,我们会设置仅用于检测无效流量的 Cookie,并同时针对已征得用户同意和未征得用户同意的流量使用本地存储。

IVT 默认设为 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:对于相关搜索块,包含发布商提供的字词到这些字词在响应中零索引位置的映射<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