Add SDK integration doc for inabox.

ads/inabox/inabox-host.md

@@ -14,4 +14,108 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-This is still in development. Check [here](https://github.com/ampproject/amphtml/issues/5700) for details. 
+# 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](https://amp.dev/documentation/guides-and-tutorials/learn/a4a_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.
+1. The response contains a flag indicating it is an AMPHTML ad.
+1. The ads tag creates an iframe, and set the response content 
+to the iframe using `srcdoc`.
+
+Note that this friendly iframe approach right now is in an experimental
+stage. Put the following meta tag in the head of the ad HTML to opt-in 
+the experiment:
+`<meta name="amp-experiments-opt-in" content="inabox-viewport-friendly">`.
+
+###### 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+ 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'">`
+1. 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]( https://github.com/ampproject/wg-caching/wiki/Status-Update-July-2019#amp-validator-1
+) 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-ads.
+
+##### 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.
+1. The ads tag creates an iframe with `src` set to the ad request URL.
+1. If the response is an AMPHTML ad, it will postMessage to the host 
+window. The AMP runtime version number is included in the message.
+1. The ads tag received the message then starts to load the 
+corresponding host script: 
+`https://cdn.ampproject.org/rtv/{version}/amp4ads-host-v0.js`
+1. Before host script is loaded, ads tag is still responsible for queuing 
+up all arriving AMP messages into a global array.
+1. 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](../../examples/inabox-tag-integration.js).
+
+## Mobile SDK integration
+(Working in progress, stay tuned)