amp-ad-exit
Description | Provides configurable behavior for ad exits for AMPHTML ads. |
Required Script | <script async custom-element="amp-ad-exit" src="https://cdn.ampproject.org/v0/amp-ad-exit-0.1.js"></script> |
Supported Layouts | nodisplay or do not specify a layout |
Overview
The amp-ad-exit
element is configured with a JSON child script element and
exposes an "exit" action to other elements in the AMPHTML ad). Elements can be annotated to exit when tapped, passing a target name and extra URL parameter values to insert. The exit action performs these steps:
- Parse the JSON config (if it hasn't yet been parsed).
- Find the requested exit target.
- Determine whether the exit should be allowed by processing the click event through declared filters.
- Rewrite URL variables (see Variable Substitution)
- Ping any click tracking URLs.
- Perform the navigation by opening the target URL in a new tab.
Example
<amp-ad-exit id="exit-api"> <script type="application/json"> { "targets": { "landingPage": { "finalUrl": "https://example.com/artisan-baking/?from=_clickArea", "vars": { "_clickArea": { "defaultValue": "headline" } } }, "flour": { "finalUrl": "https://adclickserver.example.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y&adurl=https://example.com/artisan-baking/flour", "filters": ["3sClick", "borderProtection"], "behaviors": { "clickTarget": "_top" } }, "bannetons": { "finalUrl": "https://example.com/artisan-baking/bannetons", "trackingUrls": [ "https://adclickserver.example.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y", "https://tracker.adnetwork.example.com/?url=example.com" ], "filters": ["3sClick", "borderProtection"] } }, "filters": { "3sClick": { "type": "clickDelay", "delay": 3000 }, "borderProtection": { "type": "clickLocation", "top": 10, "right": 10, "bottom": 10, "left": 10 } } } </script> </amp-ad-exit> <h1 on="tap:exit-api.exit(target='landingPage')">Artisan Baking Supplies</h1> <div id="product0" on="tap:exit-api.exit(target='flour')"> <p>Rye flour</p> <amp-img src="..." width="..." height="..."></amp-img> </div> <div id="product1" on="tap:exit-api.exit(target='bannetons')"> <p>Bannetons</p> <amp-img src="..." width="..." height="..."></amp-img> </div> <div id="footer" on="tap:exit-api.exit(target='landingPage', _clickArea='footer')" > example.com/artisan-baking </div>
Filters
Filters are specified in the filters
section of the config. Targets reference
filters by their property name in the filters
section.
There are three types of filters: location-based, time-based, and element-based. Other filters (such as a confirmation prompt) could be added as needed.
clickLocation filter
The clickLocation
filter type specifies the minimum distance a click must be from the edges of the creative or the edges of a specific element in the creative. The clickLocation filter may have the following properties:
Property | Value | Meaning |
---|---|---|
top |
number |
Distance in px from the top edge. Default is 0. |
right |
number |
Distance in px from the right edge. Default is 0. |
bottom |
number |
Distance in px from the bottom edge. Default is 0. |
left |
number |
Distance in px from the left edge. Default is 0. |
relativeTo |
string |
Selects the element to use for edge boundaries. The full creative body is used if this is not specified. The selected element does not need to be the element that triggers the exit. The selected element must be in a fixed position for the life of the creative (no resizing, repositioning, etc.). Selector must use CSS selector syntax. |
clickDelay filter
The clickDelay
filter type specifies the time to wait before responding to clicks. The amp-ad-exit
element imposes a minimum delay of 1 second on all exits. The clickDelay
filter requires the following properties:
Property | Value | Meaning |
---|---|---|
delay |
number |
Time in ms to reject any clicks after entering the viewport. |
startTimingEvent |
string |
Based on window performance timing, name of event to use as delay start interval (e.g. navigationStart). |
Note that the default 1 second click delay uses time from extension load as interval. However, this can be overridden to use startTimingEvent value via options object in the root of the config. All other click filters will use the startTimingEvent if a value is not explicitly given. Example:
<amp-ad-exit id="exit-api"> <script type="application/json"> { "targets": { "flour": { "finalUrl": "https://adclickserver.example.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y&adurl=https://example.com/artisan-baking/flour", "filters": ["3sClick", "2sClick"] }, }, "options": { "startTimingEvent": "navigationStart" }, "filters": { "3sClick": { "type": "clickDelay", "delay": 3000, "startTimingEvent": "domContentLoadedEventStart" }, "2sClick": { "type": "clickDelay", "delay": 2000, } } } </script> </amp-ad-exit>
In this case, the default click protection will impose a 1 second delay from navigationStart with two additional, specified click protections of 2 seconds from navigationStart and 3 seconds from DOMContentLoaded start.
inactiveElement filter
The inactiveElement
filter type specifies elements that should not cause exits when they are the source of an event. The amp-ad-exit
element ignores clicks on the previous/next buttons of an amp-carousel
by default. The inactiveElement
filter requires the following properties:
Property | Value | Meaning |
---|---|---|
selector |
string |
A CSS selector. If the event that triggers an exit has a target that matches the selector, the exit will not be performed. |
Example: Using filters
{ "targets": { "ad": { "finalUrl": "...", "filters": ["2second", "huge-border"] } }, "filters": { "2second": { "type": "clickDelay", "delay": 2000 }, "small-border": { "type": "clickLocation", "top": 5, "right": 5, "bottom": 5, "left": 5 }, "huge-border": { "type": "clickLocation", "top": 100, "right": 100, "bottom": 100, "left": 100 }, "border-with-relative-to-element": { "type": "clickLocation", "top": 10, "right": 10, "bottom": 10, "left": 10, "relativeTo": "#headline" } } }
Click tracking URLs
Navigation targets can be associated with click tracking URLs in the config. Before navigation, amp-ad-exit attempts to ping the tracking URLs by using:
navigator.sendBeacon
, if available- image request
You can override this behavior with a "transport" object on the config:
{ "targets": { ... }, "filters": { ... }, "transport": { "beacon": false, } }
Variable Substitution
URL variable substitution works like standard AMP variable substitution with custom variables and a limited set of platform variables. Variable substitution applies to navigation URLs and click tracking URLs.
Platform variables
Name | Value |
---|---|
RANDOM | A random float. See RANDOM. |
CLICK_X | The x coordinate of the click in the viewport. |
CLICK_Y | The y coordinate of the click in the viewport. |
Custom variables
Custom variables must begin with an underscore. Define variables in the
config alongside the navigation target. Variables should have a "defaultValue"
property. The default value can be overridden in the exit
action invocation:
Variable values can also come from 3P analytics. Use
<amp-analytics type='example-3p-vendor'>
to install a 3P analytics
vendor iframe and reference it in the variable definition with the
"iframeTransportSignal"
property. The format of "iframeTransportSignal"
is
"IFRAME_TRANSPORT_SIGNAL(example-3p-vendor,collected-data)"
, where example-3p-vendor
is the name of the vendor and collected-data
is a key in the message from the
vendor iframe. There must not be a space after the comma.
Example:
<amp-ad-exit id="exit-api" ><script type="application/json"> { "targets": { "product": { "finalUrl": "http://example.com/?page=_productCategory&verification=_3pAnalytics", "vars": { "_productCategory": { "defaultValue": "none" }, "_3pAnalytics": { "defaultValue": "no_response", "iframeTransportSignal": "IFRAME_TRANSPORT_SIGNAL(example-3p-vendor,collected-data)" } } } } } </script></amp-ad-exit > <a on="tap:exit-api.exit(target='product', _productCategory='shoes')" >buy shoes</a > <a on="tap:exit-api.exit(target='product', _productCategory='hats')" >buy hats</a >
By convention, user-defined variables should be in _camelCase
. System
variables are in ALL_CAPS
.
Be careful with your variable names. Substitution works by simple
string replacement. Any occurrence of the variable in the URL will be
replaced. For example, if you define a custom variable named "_b" with value
"foo", /?a_b_c=_b
will become /?afoo_c=foo
.
Behaviors
Behaviors specify additional properties of the exit action.
Click Target
The clickTarget
behavior specifies where a target's click should try to open. A click defaults to opening a new tab, if it is possible in the environment. With this behavior a user can specify that the click should try open the same tab, by setting this to "_top"
. If this is not set to "_top"
, then it will fall back to opening a new tab.
exit
action
The amp-ad-exit
element exposes an exit
action that other elements reference in on="tap:..."
attributes. The action accepts a "target" string parameter that must match a named NavigationTarget
in the ExitConfig
. Custom variables beginning with an underscore can also be passed in.
Name | Value | Meaning |
---|---|---|
target |
string |
The name of a NavigationTarget in the ExitConfig . |
[a-zA-Z0-9-]+ |
string|boolean|number |
Replace the URL parameter with this name and value into the final and tracking URLs. |
Configuration spec
See the AmpAdExitConfig
typedef in config.js.
Attributes
id | An id is required so that amp-exit can be referenced by tappable elements. |
Validation
The amp-ad-exit
element is only available for AMPHTML ads).
See amp-ad-exit rules for the AMP validator specification.
You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.
Go to Stack Overflow Found a bug or missing a feature?The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.
Go to GitHub