宏

广告单元宏会在广告投放时，将 Google 发布商代码中的广告单元路径插入到广告素材代码中。

下面展示了如何将 ADUNIT 宏添加到第三方广告素材代码段中：

广告单元宏会展开为初始广告请求中包含的完整广告单元路径（包括广告资源网代码）。下例说明了广告投放时广告单元路径会如何展开：

<script type="text/javascript">
document.write('<sc'+'ript type="text/javascript" src="http://www.3rdparty.com/?dfpAdUnit=/1234/site/section"<>/scr'+'ipt>');
</script>

目标网址宏会展开为广告素材的点击后到达网址，此网址既可以是订单项的点击后到达网址，也可以是订单项内广告素材的替换设置值。

目标网址宏在自定义广告素材和广告素材模板中非常有用。如果广告素材代码需要包含广告素材的点击后到达网址，且广告素材或模板在不同订单项中使用时该点击后到达网址会随之发生变化，此时这类宏会非常有用。

点击后到达网址宏分为 3 种：一次转义、两次转义和不转义。通常情况下，转义次数（添加一次还是两次转义，亦或是根本不添加）视第三方点击跟踪公司而定。有些第三方点击跟踪公司要求对此网址进行转义，而有些则不要求这样做。对于 Ad Manager 中的第三方广告代码或自定义广告素材代码，第三方点击跟踪公司所要求的转义级别通常是在代码中通过 click= 字符串来指定：

• click=：转义一次 (%%DEST_URL_ESC%%)。

• click0=：不转义 (%%DEST_URL_UNESC%%)。

• click1=：转义一次 (%%DEST_URL_ESC%%)。

• click2=：转义两次 (%%DEST_URL_ESC_ESC%%)。

文件服务器宏 %%FILE:file_display_name%% 会展开为已为广告素材上传的广告素材资源的完整网址。使用此宏可以通过自定义广告素材代码调用已上传的素材资源（例如图片）。

要使用此宏，请将 file_display_name 替换为广告素材资源的显示名，即您在查看广告素材详情时在 Ad Manager 中看到的名称。

在广告投放过程中，这些宏会将 Ad Manager 广告素材的“目标广告单元尺寸”字段值中定义的广告素材高度和宽度插入到广告素材的自定义代码中。

如果您要创建一个广告素材模板，并想将该模板重复用于不同尺寸的广告素材，便会发现高度宏和宽度宏特别有用。您可以使用这些高度和宽度宏将尺寸值动态插入每个广告素材中，而不用对每个广告素材的尺寸进行硬编码。

模式匹配宏可用于向广告素材传递一个或多个自定义变量（如定位值）。您可以使用此类宏传递键值对、替换整个定位字符串或展开引荐来源网址。如果您希望根据所了解的用户信息（如用户的内容偏好）投放不同的广告素材，则会发现此类宏非常有用。

对于每个广告素材，模式匹配宏最多只能替换 100 次。

%%PATTERN:key%%

例如，您的某个订单项中包含两个广告素材：一个旨在吸引女性用户，另一个旨在吸引男性用户。此宏中使用的“key”必须是字母数字字符或下划线 (_)。

下面就是此流程的工作方式：

1. 您需要使用键值对向网页上的广告代码传递自定义值（在本示例中，传递的是用户性别信息）：
   googletag.defineSlot("/1234/adunit1/adunit2", [728, 90], "div-gpt-ad-123456789-0")
.addService(googletag.pubads())
.setTargeting("gender", "male");
2. 在自定义或第三方广告素材中，使用下面的宏动态传递自定义值（用户性别信息）：<此处为一些广告素材脚本>...&gender=%%PATTERN:gender%%
3. %%PATTERN:gender%% 整个宏都会被替换为“male”。
4. Ad Manager 会调用标签为“male”的广告素材文件，并将该文件投放给此用户。

%%PATTERN:TARGETINGMAP%%

您可以使用 %%PATTERN:TARGETINGMAP%% 替换整个定位地图并动态创建回传代码。

下面展示了如何将 TARGETINGMAP 宏添加到广告代码中：

.updateTargetingFromMap(%%PATTERN:TARGETINGMAP%%).display();

下面是广告投放时完整键值字符串的示例：

.updateTargetingFromMap({"key1":["value1"], "key2": ["value2","value3"]}).display();

%%PATTERN:url%%

您还可以使用预留键 url 来展开为引荐页面的网址。

请注意，url 是预留键；Campaign Manager 360 代码中键名称为 url 的所有键值对都会被替换为引荐来源网址。

“代码参数”宏可与其他广告代码参数结合使用，且只能与以下参数配合使用：

• pmad
• pmxd
• pmnd
• correlator
• scor
• pod
• vpos
• mridx
• ppos
• lip
• us_privacy

在受支持的情况下，该参数会扩展为参数值。

例如，%%TAG_PARAM:correlator%%（受支持）会扩展为广告代码中的 correlator 值，但 %%TAG_PARAM:ppid%%（不受支持）不会扩展为任何值。

“目标是否为新窗口”宏用于指明，为广告素材投放到的广告单元指定的目标窗口是否设置为“_blank”（新窗口）。

• 如果目标窗口设置为 _blank，则此宏会展开为 1。

• 如果目标窗口设置为任何其他值，或者没有指定目标窗口，则此宏会展开为 0。

如果要插入实际的目标窗口设置值，请使用 %%TARGET_WINDOW%% 宏。

目标窗口宏会展开为针对广告素材所投放的目标广告单元指定的目标窗口。您可以在广告素材代码内使用此宏，以指定用户在点击广告素材后是转到新窗口还是在同一窗口中加载着陆页，具体取决于向用户展示广告的各个网站的设置。

例如，AdManager_News.com 广告单元的目标窗口设为了 _top，而 AdManager_Fashion.com 广告单元的目标窗口则设为了 _new。如果广告素材的代码中包含 %%TARGET_WINDOW%% 宏，则对于访问 AdManager_News.com 的用户，此宏会展开为 _top；而对于访问 AdManager_Fashion.com 的用户，此宏会展开为 _new。

下面是一个实现示例：

<a href="%%CLICK_URL_UNESC%%%%DEST_URL%%" target="%%TARGET_WINDOW%%"><img src="my ad"></a>

如果要确定目标窗口设置值是“_blank”还是其他值，请使用 %%TARGET_IN_NEW_WINDOW%% 宏。

通过面向儿童的内容标记 (TFCD)，您可以让第三方知道，发出特定广告请求的网页中包含面向儿童的内容。此宏旨在协助遵守儿童在线隐私保护法 (COPPA)。

您可以在第三方广告素材的任何重定向或请求中添加此宏（采用 coppa=%%TFCD%% 或类似格式）。您还可以在 JavaScript 中使用此宏，以便将 GPT 回传代码请求设为面向儿童的内容。对于面向儿童的内容，此类宏会展开为 1；对于其他内容，此类宏会展开为 0（系统会根据将请求向 Ad Manager 提出请求的网页、网站或移动应用来判断内容性质）。

如果您使用 Google 的广告服务，并且希望在网站级或应用级实现面向儿童的内容，请参阅将网站或应用标记为面向儿童。

URI 编码宏能够正确转换广告素材模板变量值中的空格和其他特殊字符，以便在 URI（也称为网址）中使用。

使用广告素材模板变量定义点击后到达网址或重定向网址时，此宏尤其有用。如果没有进行正确编码，广告素材中的完整网址可能无法正常打开。

缓存无效化宏可确保系统在每次执行代码时都会向广告服务器发送新的调用，以便准确统计展示次数。如果您不向广告素材代码添加缓存无效化宏，那么 Google Ad Manager 和第三方广告服务器之间很可能会出现展示次数统计差异。请注意，并非所有的第三方广告代码都需要缓存无效化宏。

大多数的广告素材供应商都会在各自的代码中提供一个占位符，以供插入缓存无效化宏。例如，如果第三方广告素材代码的部分内容如下所示：

http://abc.3rd-party-serving.com/Targeting/;adServer.php?ab=cd&e=12fg=click&ord=[RANDOM_NUMBER]

您需要选择 [RANDOM_NUMBER]，然后点击插入缓存无效化宏，以便其替换占位符：

http://abc.3rd-party-serving.com/Targeting/adServer.php?ab=cd&e=12fg=click&ord=%%CACHEBUSTER%%

VAST 响应中的缓存无效化宏

对于给定广告素材中的所有事件，%%CACHEBUSTER%% 宏均会展开为同一随机数。此宏对视频广告特别有用，因为对于一个 VAST 响应中的每一个视频跟踪事件，此宏均展开为同一随机数。

Click 宏会展开为特殊网址，以便您在 Ad Manager 中跟踪第三方广告素材的点击次数。此宏通常在锚标记 (<a>) 中与广告素材的点击后到达网址一同出现。请勿输入 Click 宏作为图片或 iframe 的来源。否则，每当图片或 iframe 呈现时，系统都会记录一次点击，但此类点击并不合法，因而会被当作无效点击过滤掉。

在链接的开头使用 %%CLICK_URL_UNESC%%。当点击跟踪广告代码是另一个网址的参数时，使用 %%CLICK_URL_ESC%%。

<a href="%%CLICK_URL_UNESC%%http://www.google.com">链接</a>

<a href="http://www.google.com?rd_url=%%CLICK_URL_ESC%%">链接</a>

详细了解转义和不转义的宏。

验证 Click 宏是否正确实现

Click 宏添加不当会导致系统无法跟踪点击次数。要确认 Ad Manager 是否按预期正常记录点击次数，请按以下步骤操作。

1. 预览相应的广告素材。
2. 点击“预览”。

此时，Ad Manager 会显示一条确认消息，提醒您系统将记录点击次数。如果您没有看到这条确认消息，则表明 Click 宏未正确实现。

如果在自定义广告素材代码或点击后到达网址中使用展开宏，便可以在向网页投放广告素材时显示 Ad Manager 中的 ID 值。这通常用于将 Ad Manager 中的 ID 与发布商自己数据库中的 ID 进行匹配，以进行问题排查或生成报表。

您可以在点击后到达网址中分隔各个展开宏，分隔符可以是任何能在 Ad Manager 点击后到达网址中放心使用的字符。例如：http://www.site.com/?%eaid!;%ecid! 会展开为 http://www.site.com/?1234567;4265598。

借助 %%ADVERTISING_IDENTIFIER_PLAIN%% 宏，应用内广告资源发布商可以向广告合作伙伴发送可重置的设备 ID，以便针对用户兴趣投放合作伙伴的广告。这样，您就可以更轻松地向广告客户和代理机构授予可重置的设备 ID 访问权限。

应用内广告资源发布商还可以使用 %%ADVERTISING_IDENTIFIER_TYPE%% 宏来发送设备类型，使用 %%ADVERTISING_IDENTIFIER_IS_LAT%% 宏来发送限制广告跟踪 (LAT) 设置，这项设置用于指明来自设备的“限制广告跟踪”信号。

详细了解用于用户定位的可重置设备 ID，其中包括受支持的设备类型。

前提条件

为广告素材设置 HTTPS 加密。对于广告素材以及您用于转化跟踪的所有第三方像素而言，这一步都必不可少。如果广告素材未进行 HTTPS 加密，或者如果您替换 SSL 合规性自动检查设置，则此宏将不会展开相应值，但广告素材仍会投放。

运作方式

1. 在 Ad Manager 中，发布商将相应宏添加到自己的广告素材和/或跟踪网址中。

2. 这些宏会展开为用户的设备 ID、设备类型和/或 LAT 设置，然后系统会在这些内容向第三方发起调用时将其添加到相应广告素材中。

   如果广告请求来自面向儿童的应用 (TFCD)，或如果限制广告跟踪 (LAT) 处于启用状态，标识符宏将不会展开。在这种情况下，此宏会返回一个空字符串 ("")。

格式

此宏会发送由 32 个大写字母数字组成的十六进制数值，采用连字符分五组显示，格式为 8-4-4-4-12，共计 36 个字符（32 个字母数字字符和 4 个连字符）。

示例：201F2EB1-8041-9E39-CD07-FCBBA5A29B41

了解支持的设备类型和限制广告跟踪 (LAT) 的可能值。

您可以在自定义广告素材代码中使用预览模式宏，以防止后端系统或第三方系统统计预览展示次数。如果广告素材处于 Ad Manager 预览观看模式，则此宏会展开为 true；如果是常规展示，则此宏会展开为 false。

协议宏会展开为 http: 或 https:，具体取决于哪一个与广告素材投放网页的安全协议匹配。您可以在网址的开头插入此宏。

<img src=%%SCHEME%%//www.website.com/img/logo.gif>

会展开为广告代码中网址参数的网域（例如，google.com）。此宏可用于根据请求的来源修改广告素材。不适用于标记为匿名的 Ad Exchange 广告。

借助“查看的展示”宏，每当广告素材已下载到用户的设备上且已开始加载时，Ad Manager 都会将此计为一次展示。请仅在页外广告素材中使用此宏。

您可以通过多种方式发送查看 ping。我们建议使用 <img> 代码：

<!-- 此 img 代码不可见。但会让浏览器向 VIEW_URL 发送请求。-->
<img src="%%VIEW_URL_UNESC%%" style="display:none">

<!-- 此 img 代码会显示实际广告。-->
<img src="[%Imagefile%]" border="0">

第一个 <img> 代码会检索来自 VIEW_URL 的 1x1 图片。您可以将样式设为“display:none”以将其隐藏，使其无法影响网页布局。

会展开为与请求关联的 gdpr= 的值

会展开为与请求关联的透明度和用户意见征求 (TC) 字符串。如果透明度和用户意见征求 (TC) 字符串为空白或无效，此宏将不会展开。使用此宏可通过非程序化广告素材中的网址将 TC 字符串传递给第三方广告素材提供商。

请将“XXXX”替换为第三方提供商的 IAB GVL ID。如果 TC 字符串为空白或无效，此宏将不会展开。

如果与您插入的 IAB GVL ID 关联的第三方提供商未征得用户同意，含有 ${GDPR_CONSENT_XXXX} 宏的广告素材可能会被屏蔽。

如果在 VAST 代码中使用且第三方提供商未征得用户同意，此宏将不会展开。

${GDPR_CONSENT_XXXX} 宏只能在网址内出现一次。请与您的第三方广告素材供应商联系，了解其关于传递 TC 字符串和网址长度限制的要求。在相关的 IAB 透明度和用户意见征求框架 (TCF) v2.0 请求中，此宏将被替换为未经修改的完整 TC 字符串。

在 HTML5 广告素材的 HTML 中实现的透明度和用户意见征求框架 (TCF) 宏不会扩展。只有重定向型展示广告素材和自定义展示广告素材分别支持通过“第三方网址”和“HTML 代码”字段扩展 TCF 宏。

会展开为与请求关联的更多意见征求方式 (AC) 字符串。

会展开为数值 1，以将请求标记为面向未达到同意年龄的欧洲经济区 (EEA) 用户和英国用户。

会展开为视频广告的时长（以毫秒为单位）。对于 VAST 封装容器/重定向，该宏会展开为广告在 Ad Manager 中所声明的时长。

如果此宏是在网址内，请使用 %%DESCRIPTION_URL_ESC%%（一次转义）；如果是在其他环境中，请使用 %%DESCRIPTION_URL_UNESC%%（不转义）。详细了解转义与不转义的宏

在重定向广告代码中，这些宏可根据原始 Google 发布商代码的 description_url 查询参数展开为说明网址参数。说明网址通常应与引荐来源网址相同。如果存在 IMA SDK 可能无法准确检测网页网址的嵌入内容，或者如果您在 Ad Exchange 视频广告或 AdSense 视频广告中使用视频，您就应该在 Google 发布商代码中指定 description_url。

如果此宏是在网址内，请使用 %%REFERRER_URL_ESC%%（一次转义）；如果是在其他环境中，请使用 %%REFERRER_URL_UNESC%%（不转义）。详细了解转义与不转义的网址宏

在重定向广告代码中，此宏会展开为引荐来源网址（即视频播放器所在网页的网址）。具体方式为：Ad Manager 解析广告代码中的网址查询参数，分离出引荐来源网址，然后使用此网址替换宏文本。此宏只能与 Google IMA SDK 配合使用，且必须满足以下条件：

• 要让此宏发挥作用，必须在网页上启用脚本访问权限。
• 此宏在 iframe 内不起作用。

会展开为视频的时长（以毫秒为单位）。

会展开为当前正在播放的视频内容的 ID，即 CMS 中的专属 ID 或 MRSS 中的 dfpvideo:ContentID 值。

根据与视频内容相关联的键值对，展开为其中正在投放广告素材的视频的相关元数据。您可以在 Ad Manager 的“视频”标签页中设置键值对。

定位视频元数据键后，即可通过视频元数据宏展开。此宏中使用的“key”必须是字母数字字符或下划线 (_)。

视频标题宏会展开为在 Ad Manager 中定义的视频标题。

要让此宏发挥作用，必须进行内容提取。

会展开为 FreeWheel 自定义广告 ID。

此宏仅适用于使用 FreeWheel 进行视频广告投放的发布商。

用于为您已使用标签手动分类的广告素材传递广告类别。此宏会返回一系列以英文逗号分隔的适用标准 IAB 类别（从 Google 分类类别转换而来）。

此宏可供与 FreeWheel 共享视频广告资源并希望将广告类别作为自定义参数来传递的发布商使用。例如，您可以向 VAST 重定向代码添加 &iab_categories=%%IAB_CATEGORIES%%。