Table of contents

Usage
- Required element structure
- JSON configuration
Validation

amp-link-rewriter

Description

Allows publishers to rewrite URL based on configurable pattern

Required Scripts

<script async custom-element="amp-link-rewriter" src="https://cdn.ampproject.org/v0/amp-link-rewriter-0.1.js"></script>

Supported Layouts

nodisplay

Usage

amp-link-rewriter allows publishers to rewrite URLs based on configurable patterns.

Required element structure

Add the required `script`

Inside the <head>...</head> section of your AMP page, insert the following code before the line <script async src="https://cdn.ampproject.org/v0.js"></script>.

<script
  async
  custom-element="amp-link-rewriter"
  src="https://cdn.ampproject.org/v0/amp-link-rewriter-0.1.js"
></script>

Add the `amp-link-rewriter` component

Inside the <body>...</body> section of your AMP page, insert code as shown below the example (it has to be customized for every vendor use case):

<amp-link-rewriter layout="nodisplay">
  <script type="application/json">
    {
      "output": "https://visit.foo.net?pid=110&url=${href}&cid=${customerId}",
      "section": ["#product-listing-1", "#product-listing-2"],
      "attribute": {
        "href": "((?!(https:\/\/skip\.com)).)*",
        "id": "comments",
        "class": "sidebar",
        "rel": "(?!(skip))*"
      },
      "vars": {
        "customerId": "12345"
      }
    }
  </script>
</amp-link-rewriter>

Full example

The final code should look like:

<!DOCTYPE html>
<html ⚡ lang="en">
  <head>
    ...
    <script
      async
      custom-element="amp-link-rewriter"
      src="https://cdn.ampproject.org/v0/amp-link-rewriter-0.1.js"
    ></script>
    ...
    <script async src="https://cdn.ampproject.org/v0.js"></script>
  </head>
  <body>
    ...
    <amp-link-rewriter layout="nodisplay">
      <script type="application/json">
        {
          "output": "https://visit.foo.net?pid=110&url=${href}&cid=${customerId}",
          "section": ["#product-listing-1", "#product-listing-2"],
          "attribute": {
            "href": "`((?!(https:\/\/skip\.com)).)*`",
            "id": "comments",
            "class": "sidebar",
            "rel": "(?!(skip))*"
          },
          "vars": {
            "customerId": "12345"
          }
        }
      </script>
    </amp-link-rewriter>
    ....
  </body>
</html>

JSON configuration

`output` (required)

The output property has to be a string value with the redirection url plus a query string of placeholders that will be shifted with values defined in the config JSON vars property, or in the anchor itself as a data attribute.

<amp-link-rewriter layout="nodisplay">
  <script type="application/json">
    {
      "output": "https://visit.foo.net?pid=110&cid=${customerId}`",
      "vars": {
        "customerId": "12345"
      }
    }
  </script>
</amp-link-rewriter>

We can also define data values in the anchor data attribute as the following example:

<a
  href="https://www.amazon.de/s?i=computers&rh=n%3A340843031&ref=sn_gfs_co_computervs_AM_5"
  data-vars-event-id="231"
></a>

The config could be something like:

{
  "output": "https://visit.foo.net?eid=${eventId}&cid=${customerId}"
}

The resulting, rewritten URL would be:

`https://visit.foo.net?eid=231&cid=12345`

Apart from vars defined in the vars property of the JSON configuration, or as a data attribute, there are other predefined vars which are AMP URL MACROs plus anchor attributes id and href that could be used for replacing values in the output pattern. The AMP URL MACROs available are AMP_GEO, DOCUMENT_REFERRER, and SOURCE_URL. The following table shows the relationship between defined data and placeholders.

value	source	example	placeholder
country	geo	`us`	`AMP_GEO(ISOCountry)`
data-vars-*	anchor	`<a href="..." data-vars-merchant-id="123" />`	`${merchantId}`
href	anchor	`<a href="https://retailer.com" />`	`${href}`
id	anchor	`<a href="..." id="link" />`	`${id}`
location	page	`https://www.partnerweb.com/`	`SOURCE_URL`
random	page	`Math.random().toString(32).substr(2)`	`${random}`
referrer	page	`https://google.de/`	`DOCUMENT_REFERRER`
rel	anchor	`<a href="..." rel="pass" />`	`${rel}`
rev	anchor	`<a href="..." rev="author" />`	`${rev}`
vars.*	config	`{ "vars": { "publisherId": "123" } }`	`${publisherId}`

section (optional)

The section property defines an array of css selector expressions that filter areas where the url rewriting should operate.

{
  "output": "https://visit.foo.net?pid=110&url=${href}&cid=${customerId}",
  "section": ["#product-listing-1", "#product-listing-2"]
}

In the previous example, the html sections defined with attribute ID equal to product-listing-1 and product-listing-2 will be considered for url rewriting.

attribute (optional)

The attribute property defines a list of rules to match the anchor elements retrieved from the filtered sections. These rules are built from regular expressions associated with html element attributes as id, href, class or rel.

{
  "section": ["#product-listing-1"],
  "attribute": {
    "href": "((?!(https://skip.com)).)*",
    "class": "comments"
  }
}

The anchors within the html area with id product-listing-1 will have to match the regex expression defined for the attribute href and class. The regex expression will be wrapped with ^ and \$ for a full match.

In this example, it means that all the anchors with youtube.com and mobile.vodafone.de will be excluded. Also, the included anchors need to have a class attribute with the value comments.

scopeDocument (optional)

By default, all anchors will be rewritten if the page doesn't have any links which respect the attribute and section scope specified in the config.

To change this behavior, you need to set scopeDocument to false.

Validation

See amp-link-rewriter rules in the AMP validator specification.

Need more help?

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