amp-ad-exit

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:

1. Parse the JSON config (if it hasn't yet been parsed).
2. Find the requested exit target.
3. Determine whether the exit should be allowed by processing the click event through declared filters.
4. Rewrite URL variables (see Variable Substitution)
5. Ping any click tracking URLs.
6. 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:

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:

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:

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:

1. navigator.sendBeacon, if available
2. 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

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.

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.

Actions

setVariable action

amp-ad-exit also supports variable targets. The variable targets do not define exit URLs by themselves, but instead point to one of the named NavigationTargets in the ExitConfig. Not to be confused with the URL custom variables, these are state variables maintained by the amp-ad-exit element that can be updated at runtime which enable stateful exit behavior. See the example below.

setVariable action is used to set up the mapping from a state variable to a named NavigationTarget in the ExitConfig.

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, or a "variable" string parameter which is a state variable that points to a NavigationTarget. Custom variables beginning with an underscore can also be passed in.

Example: Using variable targets

<amp-ad-exit id="exit-api" layout="nodisplay">
  <script type="application/json">
    {
      "targets": {
        "product1": {
          "finalUrl": "https://example.com/product1"
        },
        "product2": {
          "finalUrl": "https://example.com/product2"
        }
      }
    }
  </script>
</amp-ad-exit>
<amp-selector
  id="exit-selector"
  layout="nodisplay"
  on="select:exit-api.setVariable(name='currentProduct', target=event.targetOption)"
>
  <option option="product1" selected></option>
  <option option="product2"></option>
</amp-selector>
<amp-carousel
  type="slides"
  autoplay
  on="slideChange:exit-selector.toggle(index=event.index, value=true),
        tap:exit-api.exit(variable='currentProduct', default='product1')"
>
  <div>product 1</div>
  <div>product 2</div>
</amp-carousel>

Configuration spec

See the AmpAdExitConfig typedef in config.js.

Attributes

Validation

The amp-ad-exit element is only available for AMPHTML ads). See amp-ad-exit rules for the AMP validator specification.