AMP Ads - Technical Best Practices

Enhancing incoming ad configuration

Enhancing only ad iframes with Custom JavaScript

Running custom JavaScript only in the master iframe

Demand Management Platform Implementation (DMP) on AMP

This document shows some code samples you can leverage to address common use-cases in AMP Ads.

Enhancing incoming ad configuration

The AMP Ads framework has the ability to enrich ad requests before making the final request to the ad server. Publishers may prefer to do this because they need to run custom JavaScript that the main AMP document doesn’t allow. The common use-cases for running custom JavaScript are :

There are 3 steps required in order to enhance the incoming ad configuration.

Step 1: Create a remote.html file

The remote.html needs to be placed on a subdomain of the domain where the main AMP document is hosted. e.g. if the publisher hosts a webpage on https://nytimes.com, then the remote file should be hosted on something similar to https://sub-domain.nytimes.com for the custom JavaScript to have the abiity to read or write cookies for nytimes.com.

Step 2: Include the location of the remote.html file in the main AMP document

Your main AMP document needs to include the reference to the remote.html like below :

<meta name="amp-3p-iframe-src" content="https://assets.your-domain.com/path/to/remote.html">

For example, the head section of the base amp document looks like below :

 <head>
   
<meta charset="utf-8">
   
<title>Ads in AMP</title>
   
<link rel="canonical" href="."/>
   
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
    <meta name="amp-3p-iframe-src" content="https://x20web.corp.google.com/~jastiv/remote.html">
   <
style>body {opacity: 0}</style><noscript><style>body {opacity: 1}</style></noscript>
   <
script async src="https://cdn.ampproject.org/v0.js"></script>
 
</head>

Step 3: Update the draw3p() function with custom JavaScript

The remote.html file consists of a draw3p() function which allows you to plugin any custom JavaScript as you wish. For example, say you wanted to enhance the ad call with an additional custom criteria called “test3p” with a value of “true”, the final remote.html looks like below with draw3p function highlighted. Consider the rest of the document to be boilerplate.

<!doctype html>
<head>
   
<meta charset="utf-8">
   
<meta name="robots" content="noindex">
   <
script>
       (
function() {
           
var v = location.search.substr(1);
           
if (!(/^\d+(-canary)?$/.test(v))) return;
           
var u = 'https://3p.ampproject.net/' + encodeURIComponent(v) + '/f.js';
           
document.write('<script' + ' src="' + encodeURI(u) + '"><' + '/script>');
       })();
   </
script>
</head>

<body style="margin:0">
   
<div id="c" style="position:absolute;top:0;left:0;bottom:0;right:0;">
       <
script>
       
    draw3p(function(config, done) {
               config.targeting
= {
                   
"test3p": ["true"]
               };
               done(config);
           });
        </script>
   
</div>
   <
script>
       
if (window.docEndCallback) window.docEndCallback()
   </
script>
</body>
</html>

See a live example of this example here.

Enhancing only ad iframes with Custom JavaScript

With the remote.html setup described above, the remote.html file will load each time an iframe loads. If you would like to run some custom JavaScript only when the request originates for a doubleclick server, you should set a condition on the config.targeting object in the draw3p function like below :

 <script>
           draw3p(function(config, done) {
             
 if (config && config.targeting && config.type==’doubleclick’) {
                    // Check that the config object is valid and the type is DoubleClick
                   done(config);
               }
else {
                   done
();
               }
           });

Running custom JavaScript only in the master iframe

Every AMP document only has a single master iframe and you can run JavaScript that is common to all ads, just once by checking if the incoming ad request is originating from the master iframe by performing the following check.

<script>
           draw3p(function(config, done) {
           
   if (window.context && window.context.isMaster) {
                    //load page level dmp tag
               }
               done
();
           });
       
</script>

Demand Management Platform Implementation (DMP) on AMP

For publishers that want to interact with their data management platform, we recommend that you make use of the functionality to enhance the incoming ad configuration using the draw3p function in the remote.html file.

The pseudo-code for appending audience segments to your ad call can look like this :

 draw3p(function (config, done) {

// check that the config is valid, the incoming ad call is from doubleclick and ensure that the work is only being done in the master Iframe (This is work that needs to be done once one in a page)

{

Step 1: Expose metadata to the DMP from the ad call.

Step 2: Construct DMP javascript, load the meta-data that you constructed from your ad call  and send to the DMP

}

// check again if the config is valid (this is work that needs to be done for every amp ad iframe)

{

Step 3 : Get the DMP segments from the localstorage javascript variable that is updated in Step 2.

Step 4: Append the audience segments as part of the ad call.

Step 5: Invoke callback

}