Introduction

The AMP environment is very different to traditional web pages. In order to keep pages fast and efficient, restrictions are imposed on JavaScript execution and as a result typical data collection and targeting methods don't work. To provide the best of Permutive in the AMP environment, we've built an AMP integration on top of AMP components.

Our integration ensures that Permutive's core functionality is supported in the AMP environment - including data collection, real-time segmentation and ad targeting. This enables you to take advantage of Permutive's real-time capabilities on AMP pages.

Prerequisites

In order to implement AMP, you'll first need a Permutive project set up and the following information to hand:

  • Project ID - available in your Permutive dashboard
  • Public API Key - available in your Permutive dashboard
  • Namespace - Please contact techsupport@permutive.com and our team will assign you an AMP namespace

Where you see <NAMESPACE> , <PROJECT_ID>  and <API_KEY>  in this document, these should be replaced by the corresponding values.

Data Collection

To enable data collection, we've built a custom plugin for the amp-analytics  component. Analytics is an extension to AMP, and must be enabled for your AMP pages. Instructions for enabling amp-analytics  can be found here.

This will involve importing the amp-analytics  script into your page, for example:

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

Once enabled on your page, the next step is to include Permutive's AMP analytics configuration in the body of your page. 

<amp-analytics config="https://amp.permutive.com/amp-analytics-v2.json">
  <script type="application/json">
    {
      "vars": {
        "namespace": <NAMESPACE>,
        "key": "<API_KEY>"
      },
      "extraUrlParams": {
         ...
      }
    }
  </script>
</amp-analytics>

Be sure to replace <API_KEY> and <NAMESPACE> with your public API key and AMP namespace. The extraUrlParams object is optional and can be used to pass in arbitrary properties about the page content. These properties are included in the events sent into Permutive, so you should ensure that the properties you send in match up with your Permutive event schemas. If you want to send in a list property, you must suffix your property name with !list  and pass in a comma-separated string as the property value. Every property name should be prefixed by properties.. Here's an example of what extraUrlParams  might look like:

"extraUrlParams": {
  "properties.article.title": "Elon Musk Builds Space Colony on Mars",
  "properties.article.author": "Hari Seldon",
  "properties.article.categories!list": "travel,finance"
}

Once your amp-analytics configuration is live on a test page, you should contact us, and we can ensure that data is being collected correctly. You should see Pageview and PageviewEngagement events being collected on your AMP pages.

Targeting

Permutive segmentation and targeting in AMP is very different to standard web pages, due to the strict limitations around executing third-party JavaScript, and the way amp-ad  elements render in isolated iframes. 

To enable Permutive segmentation and targeting in AMP, you'll need to first place an amp-iframe component on your page and then update your amp-ad components to include Permutive's AMP RTC configuration.

amp-iframe

You must first ensure the amp-iframe script is included on your page (see here). This will involve importing the amp-iframe script into your page, for example:

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

Next, you must include Permutive's amp-iframe  component on your page. This is an invisible iframe that will execute Permutive JavaScript.

<amp-iframe width="1" height="1"
      layout="responsive"
      sandbox="allow-scripts allow-same-origin"
      src="https://<NAMESPACE>.amp.permutive.com/amp-iframe.html?project=<PROJECT_ID>&key=<API_KEY>">
    </amp-iframe>

Note that <NAMESPACE> , <PROJECT_ID>  and <API_KEY>  should be replaced appropriately during installation.

amp-ad

Finally, you'll need to include Permutive's AMP RTC configuration in each of your amp-ad  components, where you want Permutive targeting data to be available.

<amp-ad width="123"
      height="456"
      type="doubleclick"
      data-slot="/network/ad-unit"
      rtc-config='{
        "urls": [
          "https://<NAMESPACE>.amp.permutive.com/rtc?type=doubleclick"
        ]
      }'>
    </amp-ad>

Note that the type  parameter in the RTC URL must match the type  parameter of the amp-ad  element (doubleclick in the above example). 

This RTC configuration will enable Permutive to augment your ad requests with real-time targeting data.

Limitations

Permutive capabilities are more limited in AMP compared to the standard web environment.

Current limitations include:

  • As we are unable to execute JavaScript on the page, we are unable to interact with custom elements and detect interactions (e.g. the user hovering their mouse over a dialog on the page). However, amp-analytics  is fairly powerful, and we are able to collect data on anything supported by amp-analytics triggers. The default setup will collect Pageview  and PageviewEngagement events only.
  • Currently only the doubleclick  ad type is supported, for real-time targeting. However support for additional ad types may be made available upon request.
  • AMP does not let us manipulate the page in any way - for example our Permutive overlay reactions will not work in the AMP environment.
  • Some of our integrations will not be enabled on AMP pages, simply because they don't make sense or are unable to operate in the AMP environment. 

Did this answer your question?