Objective

For users: Provide a high-quality navigation experience for AMP creatives with fast-click protection and predictable exit behavior.

For developers: Provide features needed for display ad exits, such as pinging click tracking URLs and substituting custom URL variables. Allow exits to be configured without changing creative markup.

This initial version is only intended for ads that navigate to landing pages. This could plausibly be extended to handle other types of exits, like phone calls, but for now those are better handled by specialized components.

Background

Display ad clicks behave differently than other static web content. The ad server needs to know that the ad was clicked for proper accounting, either by redirecting through a click tracking server or by pinging the server asynchronously, and that tracking URL depends on impression-time information (e.g. an event ID) and client-side information like click location. The ad network may choose to improve click quality and the user's experience by not navigating in response to certain clicks, such as those very close to the edge of the device.

Proposal

This document proposes a new element to configure and perform exits. The element is configured with a JSON child script element and will expose an "exit" action to other elements on the page. Elements in the creative can be annotated to exit when tapped, passing a target name and extra URL parameters to insert. The exit action will perform 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 URLs using standard variable substitution rules
5. ping any click tracking URLs
6. perform the navigation by opening the target URL in a new tab

Details

Exit Configuration

When the JSON is parsed, the resulting object should conform to this ExitConfig type (this type description uses Closure Compiler type annotations):

/** @typedef {string} */
const Url;

/** @typedef {string|number|boolean} */
const VariableValue;

/** @typedef {!Object<string, (VariableValue|!Array<VariableValue>)>} */
const Variables;

/**
 * @typedef {{
 *   final_url: Url,
 *   tracking_urls: (!Array<Url>|undefined),
 *   vars: (Variables|undefined),
 *   filters: (!Array<string>|undefined>
 * }}
 */
const NavigationTarget;

/**
 * @typedef {{
 *   delay: (number|undefined)
 * }}
 */
const FastClickFilter;

/** @typedef {string} */
const UniqueElementSelector;

/**
 * @typedef {{
 *   top: (number|undefined),
 *   right: (number|undefined),
 *   bottom: (number|undefined),
 *   left: (number|undefined),
 *   relativeTo: (UniqueElementSelector|undefined)
 * }}
 */
const ClickLocationFilter;

/** @typedef {FastClickFilter|ClickLocationFilter} */
const Filter;

/**
 * @typedef {{
 *   targets: !Object<string, NavigationTarget>,
 *   filters: !Object<string, Filter>
 * }}
 */
const ExitConfig;

Filtering

There are initially two types of filters: location-based and time-based. Other filters (such as a confirmation prompt) could be added as needed.

ClickLocationFilter specifies the minimum distance a click must be from the edges of an element in the creative.

FastClickFilter specifies the time to wait before responding to clicks. This element will impose a minimum delay of 1 second on all exits.

Variable substitution

The final_url and tracking_urls will be processed for variable substitution. This includes the standard URL variables, click coordinates (CLICK_X and CLICK_Y), data from signal collection frames, and custom params.

Custom params are inspired by amp-analytics' vars option. URLs can include ${var} placeholders which will be replaced on exit. Variables can have default values which can be overridden by the element requesting the exit (see the "exit action" secton).

exit action

The component will expose an exit action that other elements will reference in on="tap:..." attributes. The action accepts a "target" string parameter that must match a named NavigationTarget in the ExitConfig. Other parameters can be passed for variable substitution by prefixing their name with an underscore.

Example

<amp-ad-exit id="exit-api">
<script type="application/json">
{
  "targets": {
    "Product_0": {
      "final_url": "https://adclickserver.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y&elem=${elem}&adurl=https://example.com/product1",
      "vars": {
        "elem": {
          "default": "headline",
        }
      }
    },
    "Product_1": {
      "final_url": "https://example.com/product2",
      "tracking_urls": [
        "https://adclickserver.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y",
        "https://tracker.adnetwork.com/?url=example.com",
      ],
      "filters": ["fast_click", "border_protection"]
    }
  },
  "filters": {
    "fast_click": {
      "delay": 1000
    },
    "border_protection": {
      "top": 10,
      "right": 5,
      "bottom": 10,
      "left": 10,
      "relativeTo": "#product1"
    }
  }
}
</script>
</amp-ad-exit>

<div id="product0" on="tap:exit-api.exit(target='Product_0', _elem='p1')">
  <p>Description of first product</p>
  <amp-img src="..." width="..." height="..."></amp-img>
</div>
<div id="product1" on="tap:exit-api.exit(target='Product_1')">
  <p>Description of second product</p>
  <amp-img src="..." width="..." height="..."></amp-img>
</div>