ContextQMD
Back to Amphtml

SDK integration for AMPHTML ads

ads/inabox/inabox-host.md

latest4.8 KB
Original Source

SDK integration for AMPHTML ads

One goal of AMPHTML ads is for advertisers to create ad once and use everywhere. This guide provides details about how an ad network can join us to serve and render AMPHTML ads in various environments, for example regular web & native mobile apps.

Terminologies

AMPHTML ad

Ad creatives that are written following the AMPHTML ads spec.

inabox

A term describes the situation that an AMPHTML ad is being served on a non-AMP environment, e.g a regular web page inside an iframe embed or a native mobile app inside a WebView. This is very different from how AMPHTML ad gets rendered on an AMP page, where the page and ad shares the same JS runtime.

host

The web page or native mobile app that the ad is being served on.

friendly iframe

An iframe with the same origin as the host page, so that it has full access to the host page content.

cross-domain iframe

An iframe on the host page that has different origin, so it can only communicate to the host page via postMessage API.

JS SDK (a.k.a ads tag) integration

This is the case when AMPHTML ad is being served and rendered on a regular web page (non-AMP) inside an iframe. The iframe can be either a friendly iframe, or a cross-domain iframe.

Friendly iframe

Using friendly iframe requires zero to little investment to get it work, but it can be more involved if you want to get the full benefit from AMPHTML ads, which will be discussed in the optimization session. Because AMPHTML is trustful & secure, it can be put inside a friendly iframe without worrying it hijacking the page and ruining the end user experience. Meantime, friendly iframe rendering in general requires less browser resources than cross-domain iframe rendering, which not only brings performance benefit but also revenue gain. One thing to keep in mind though is that the ad network should have their own mechanism to prevent pub modifying the ad content or faking clicks. Google Ad Manager uses this approach to integrate with AMPHTML ads.

Main workflow:

  1. The ads tag makes an ad request.
  2. The response contains a flag indicating it is an AMPHTML ad.
  3. The ads tag creates an iframe, and set the response content to the iframe using srcdoc.
Security assurance

In case that the AMPHTML ad is generated by a 3rd party, to ensure it's secure to put it in a friendly iframe, the following 2 protections should be considered:

  1. Add the following Content-Security-Policy rules to the ad response: <meta http-equiv="Content-Security-Policy" content="script-src https://cdn.ampproject.org/;object-src 'none';child-src blob:;frame-src 'none'">
  2. Validate the AMPHTML ad using an AMP validator. There is an open source JS implementation for the validator. But for performance reasons it might only be good for offline validation. For large scale serving time validation, you should consider writing your own validator following the AMP spec. A good news is that Cache WG is planning to open source a C++ implementation of the validator soon.

Ideally, both should be implemented for defense-in-depth.

Server side rendering

It is a good idea to consider server side rendering for further performance optimization. For example, rewrite all script links with version number to get the browser cache benefit. For more details about server side rendering, please reach out to the @ampproject/wg-monetization.

Cross-domain iframe

If the ad has to be put into a cross-domain iframe, the ads tag is responsible to set up the communication channel for the ad to complete various tasks such as ad expansion or viewability tracking. A so-called host script is to be loaded in that case to fulfill the requirements.

Main workflow:

  1. The ads tags sets up a postMessage listener on host window.
  2. The ads tag creates an iframe with src set to the ad request URL.
  3. If the response is an AMPHTML ad, it will postMessage to the host window. The AMP runtime version number is included in the message.
  4. The ads tag received the message then starts to load the corresponding host script: https://cdn.ampproject.org/rtv/{version}/amp4ads-host-v0.js
  5. Before host script is loaded, ads tag is still responsible for queuing up all arriving AMP messages into a global array.
  6. Once host script is fully loaded, ads tag can then hand over the job to it to process the queued messages and listen for future messages.

A sample implementation of the above process can be found here.

Mobile SDK integration

(Working in progress, stay tuned)