Description Provides configurable behavior for ad exits for A4A (AMP for Ads).
Availability Stable
Required Script <script async custom-element="amp-ad-exit" src="https://cdn.ampproject.org/v0/amp-ad-exit-0.1.js"></script>
Supported Layouts All. This element is hidden.

Overview

The amp-ad-exit element is configured with a JSON child script element and exposes an "exit" action to other elements in the A4A (AMP for Ads) creative. 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"]
    },
    "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 two types of filters: location-based and time-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: 0
right number Distance in px from the right edge. Default: 0
bottom number Distance in px from the bottom edge. Default: 0
left number Distance in px from the left edge. Default: 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.

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

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. The default value can be overridden in the exit action invocation:

<amp-ad-exit id="exit-api"><script type="application/json">
{
  "targets": {
    "product": {
      "finalUrl": "http://example.com/?page=_productCategory",
      "vars": {
        "_productCategory": {
          "defaultValue": "none"
        }
      }
    }
  }
}
</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.

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.

Parameter name Parameter value type 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 A4A (AMP for Ads) documents. See amp-ad-exit rules for the AMP validator specification.