Intent to Implement: Replacement API for window.context in cross-domain iframes

Background

Parts borrowed from: https://github.com/ampproject/amphtml/issues/3019

Currently AMP provides a context API to scripts within 3rd party iframes (including amp-ad). This API provides certain metadata (URL, referrer), as well as IntersectionObserver emulation and ability to request resizing of their containing AMP elements.

However, the issue is that this API is only accessible within that specific window created via the 3P flow, e.g. a nested x-domain iframe, created via the A4A or Glade flow, has no way to use it. At the same time, certain features of that API would be very useful for rich content which might make use of the viewability information or ability to resize (e.g creatives).

A postMessage based API has already been implemented to enable communication across nested iframes to provide some of the same context to creatives within. However, a replacement for window.context that looks the same and follows the same patterns of use as the original would be easier to use and transition to, and could be implemented as a simple wrapper around the postMesssage API.

Overview

A new class has been implemented, AmpContext, that provides access to multiple API calls and context information. This will now be part of the AMP runtime and available to any AMP elements, and all non-AMP creatives will continue to use window.context, however that will now simply be an instance of AmpContext.

Important Changes for Non-AMP Ads

The following changes will only need to be implemented by creatives that want to use window.context. Creatives that do not care to use it do not need to include the script or implement these changes.

A creative can not guarantee that it will be created within the same origin as the 3p frame such that window.context is available to use, in fact the new A4A flow will always wrap creatives in a cross domain iframe such that window.content is not accessible. Thus, advertisers must include the following code snippet and only use window.context once it is guaranteed to be ready to use as it is loaded asynchronously.

if (!window.context){
 /* must add listener for the creation of window.context prior to attaching the script */
 window.addEventListener('amp-windowContextCreated', function(){
    /* window.context now ready to use */
    ...
 });

 // load ampcontext-lib.js which will create window.context
 try{
   var version = JSON.parse(decodeURI(window.name)).ampcontextVersion;
   var ampContextScript = document.createElement('script');
   ampContextScript.src = "https://cdn.ampproject.org/" + version +  
      "/ampcontext-v0.js";
   document.head.appendChild(ampContextScript);
  } catch (err){ /* window.context could not be built */ }
} else {
	/* window.context available and ready to use*/
}

Important Changes for Ad Networks

All ad networks that want their served creatives to be able to use window.context must utilize window.context.addContextToIframe(iframe), a helper function, to assign the name attribute of their creative’s iframe properly. The helper function returns the iframe with the name attribute properly set so as to allow window.context to work in child iframes.

Backwards Compatibility

For ease of transition, the methods and properties on the new window.context object will look and behave the same as on the old window.context object. However, some methods and properties will not be implemented as they are not relevant for a creative to use, as they were added to window.context for ad networks to use (marked as N/A below). There are also some properties that are not yet implemented, with the goal that should be added soon (marker as no).

Method / Property on window.context	Original window.context supports	AmpContext supports
referrer	yes	yes
location	yes	yes
canonicalUrl	yes	yes
clientId	yes	no
pageViewId	yes	yes
startTime	yes	yes
container	yes	yes
renderStart()	yes	N/A
noContentAvailable()	yes	N/A
reportRenderedEntityIdentifier()	yes	N/A
observeIntersection()	yes	yes
initialIntersection	yes	no
hidden	yes	no
requestResize()	yes	yes
onResizeSuccess()	yes	yes
onResizeDenied()	yes	yes
master	yes	N/A
isMaster	yes	N/A
computeInMasterFrame	yes	N/A

References

window.context available info

[jasti]

@bradfrizzell @lannka Can you confirm that window.context (via AMP Context) is not available in delayed rendering mode? We need to get this done ASAP especially if we are deprecating useSameDomainRenderingUntilDeprecated by end of March.

[bradfrizzell]

Closing as this is done / old. Please create new issues for any future bugs / requests related to this I2I