参考文档

参数

页面级参数说明

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

必填

参数 说明和示例
adPage 当用户导航到下一个结果页或上一个结果页时为必需参数。

adPage 参数用于指定显示广告的结果页。当用户的浏览范围超出搜索结果第一页时，此参数就会派上用场。例如，如果系统请求了五个广告，并且 adPage 参数设置为 2，那么返回的广告将会是第二页对应的五个广告。

pubId 必需参数
这是您的 AdSense Client-ID。pubId 是 Client-ID 中“partner-”之后的部分。例如，如果您的 Client-ID 为“partner-test-property”，则您的 pubId 为“test-property”。这是针对自定义搜索广告的标准书写方式。

示例：

'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”。不过，请务必注意，此默认值仅适用于搜索结果页（Google 搜索上的相关搜索）。如果您要在任何其他类型的页面（例如文章、博文）上使用相关搜索，则必须将该参数明确设置为“content”。

注意：使用此参数时需遵循以下准则：

  • 某些相关搜索功能可能会启用或停用，具体取决于此页面参数的值。
  • 在非搜索结果页上虚假陈述网页类型或依赖于 relatedSearchTargeting 参数的默认“query”设置，均会被视为违反这些书面说明。
  • 无论此值是手动设置还是使用默认值，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 或其他动态标识符）的内容网页网址可能会干扰抓取工具评估网页核心内容的能力，并可能导致相关搜索字词不准确或不相关。此网页参数会指示 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，或由您的技术支持客户经理创建的渠道 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  
greek 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  
greek 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 必需参数
作为广告展示位置的空广告容器 <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