├── README.md
└── library.md


/README.md:
--------------------------------------------------------------------------------
 1 | # Initial-Sub-Load
 2 | 
 3 | ###Intro
 4 | 
 5 | The L.E.A.N (**L**ight, **E**ncrpyted, **A**dChoice supported, **N**on-invasive) Ad Principals, released by the IAB as a new standard for serving online advertisements, aims to give ad creators, as well as publishers, a framework in which ads can be created and served as easily and lightweight as possible.
 6 | 
 7 | Relevant Links from IAB Techlab:
 8 | * http://iabtechlab.com/blog/what-does-it-mean-to-be-lean/
 9 | * http://iabtechlab.com/blog/building-light-weight-and-load-optimized-ad-creatives/
10 | 
11 | 
12 | 
13 | To archives this a creative may have 3 distinct loading phases, each limiting the ad on how many files and request if may process in that phase, so the ad may load as fast as possible and be visible as soon as possible to the website visitor.
14 | 
15 | * "initial" phase: The creative may load a limited number of resources (like images and scripts), to provide a first but functional presentation of the ad. Furthermore it may load trackings to measure simple technical KPI's like impression and viewability. Most publisher's limit the maximum total file weight (example 100 KB) and  the amount of file request during this phase.  Make sure you are aware of the exact limitations for each publisher. <br><br>OVK members will all support the specification at http://www.werbeformen.de/ovk/ovk-de/werbeformen/spezifikationen/initialsubload.html
16 | 
17 | 
18 | * "subload" phase: Only when the publisher website is fully loaded, may the ad load more and heavier resources. These include animations, light video files or other interactive experiences. All of these resources still need to adhere to a maximum file weight for the whole creative (example +200KB), but without a limit to file requests.
19 | 
20 | * "user initiated" phase: Only when the user interacts with the ad (swipe, click), the ad may load further resources without any limits. This can be full-length video spots or other heavy media files.
21 | 
22 | 
23 | For ad creators the "inital" phase is easy to program and accommodate. The loading process of the ad starts, so the ad can do a limited amount of steps before it has to stop and needs to wait for the "subload" phase.
24 | 
25 | To correctly anticipate the "subload" phase however, might prove more difficult.  Most ads are "locked" inside a SafeFrame (an iframe with no way to access the site), or nested deep inside of iframe-chains with different solutions and scenarios on each website.
26 | 
27 | To provide an easy solution for ad creators and publisher alike the OVK developed a lightweight and fast solution, which can be inserted into any creative and correctly determines when to start the subload, no matter on which website the creative is served.
28 | 
29 | Based on JavaScript, the solution can be pasted into the JavaScript code of the creative and exposes a new "Event" called "iabSubLoadStart". Any steps the creative should take during "subload", can be added via an EventListener on the "window" object of the creative.<br><br>
30 |  
31 | 


--------------------------------------------------------------------------------
/library.md:
--------------------------------------------------------------------------------
  1 | ###What you need to do
  2 | To correctly integrate the solution, follow these simple steps:
  3 | 
  4 | 1.) Paste the following code into the JavaScript portion of your creative. This code is minimized to be as lightweight as possible. You will find a readable form at the end of this document.
  5 | ```
  6 | !function(){var e={y:window.top!==window?window.top:window,t:4,p:function(){try{return window.top.document}catch(t){return!1}}(),w:function(t){"string"==typeof t.data&&"IAB_HOST_LOADED"===t.data&&(window.clearTimeout(e.k),e.x())},k:"",q:"function"==typeof CustomEvent?new CustomEvent("iabSubLoadStart"):document.createEvent("Event").initEvent("iabSubLoadStart",!0,!0),x:function(){return self.dispatchEvent(e.q)}};e.p?"complete"!==e.y.document.readyState?(console.log("SETTING READYSTATE LISTENER"),e.y.document.addEventListener("readystatechange",function(){"complete"===e.y.document.readyState&&e.x()})):this.x():(window.addEventListener("message",e.w.bind(e)),e.k=setTimeout(function(){window.removeEventListener("message",e.w),e.x()},1e3*e.t))}();
  7 | ``` 
  8 | 
  9 | 
 10 | 2.) Create a new JavaScript function, which will handle the "subload" phase of your creative (loading further resources, starting animations, and so on). For example, name it "startCreativeSubload".
 11 | 
 12 | 3.) Add a new EventListener for "iabSubLoadStart" to the window object, reference your new "subload" function as second argument of "addEventListener".
 13 | 
 14 |  
 15 |  ```
 16 |  <script>
 17 |  window.addEventListener('iabSubLoadStart', startCreativeSubLoad)
 18 |  </script>
 19 |  ``` 
 20 | 
 21 | 4.) Your done! The creative will now start "subload" as soon as it is able to. It is recommended to test your creative thoroughly. 
 22 | 
 23 | Important: It must be ensured that the subload is only started once per creative, since the corresponding signals may be passed multiple times.
 24 | 
 25 | 
 26 | ### How it works
 27 | The solution will check for 2 possible states/points in time to start "subload":
 28 | * The website can be reached, and it's load status can be read by the creative
 29 | * The website can not be reached, it's load status is unknown or can only be determined, if the website supports inter-iframe communications.
 30 | 
 31 | 
 32 | For the first state, the creative will try to contact the website and monitor its load status. If it is already loaded, the "subload" phase will start at once. Otherwise the creative will wait until the website finishes loading.
 33 | 
 34 | For the second state, the creative will wait a minimum of 4 seconds for the site to contact the creative and communicate its load status. If the site does not support inter-iframe communication, "subload" will start after 4 seconds. If the website contacts the creative before the 4 seconds, the "subload" phase will start as soon as the connection is established.
 35 | 
 36 | 
 37 | ``` 
 38 | /**
 39 | 		 * Trigger Script  (unminified)
 40 | 		 *
 41 | 		 * Tries to determine how the publisher delivers the creative to the website.
 42 | 		 * There are 4 possibilities:
 43 | 		 *  - Directly on the website via a Javascript. We can read the "host" site and wait for a complete load
 44 | 		 *  - Via an iframe, separating the creative from the website, but in a friendly Iframe. We still can read when the "host" is completely loaded.
 45 | 		 *  - Via an unfriendly iframe, completely blocking access to the website. In this case we just assume the "host" is completely loaded after X seconds.
 46 | 		 *  - Via an unfriendly iframe, but the websites sends the message "IAB_HOST_LOADED" when it has finished loading.
 47 | 		 * As soon as we think the website is loaded, the creative can initiate the subload by listening for the event "iabSubLoadStart".
 48 | 		 **/
 49 | 
 50 | 
 51 | 
 52 | (function () {
 53 |     var iabSubLoadLib = {
 54 |         mainWindow: (window.top !== window) ? window.top : window,
 55 |         waitTimer: 4,
 56 |         friendlyFrame: (function () {
 57 |             try {
 58 |                 return (window.top.document);
 59 |             } catch (e) {
 60 |                 return false;
 61 |             }
 62 |         })(),
 63 |         postMessageHandler: function (event) {
 64 |             if (typeof event.data === 'string' && event.data === 'IAB_HOST_LOADED') {
 65 |                 window.clearTimeout(iabSubLoadLib.loadTimer);
 66 |                 iabSubLoadLib.startSubLoad();
 67 |             }
 68 |         },
 69 |         loadTimer: '',
 70 |         subLoadEvent: (typeof CustomEvent === 'function') ? new CustomEvent('iabSubLoadStart') : (document.createEvent('Event')).initEvent('iabSubLoadStart', true, true),
 71 |         startSubLoad: function () {
 72 |             return self.dispatchEvent(iabSubLoadLib.subLoadEvent);
 73 |         }
 74 |     };
 75 |     if (iabSubLoadLib.friendlyFrame) {
 76 |         //we know we are in a friendly iframe or directly on the site, check readystate
 77 |         if (iabSubLoadLib.mainWindow.document.readyState !== 'complete') {
 78 |             //site is still loading, use event
 79 |             iabSubLoadLib.mainWindow.document.addEventListener('readystatechange', function () {
 80 |                 if (iabSubLoadLib.mainWindow.document.readyState === 'complete') {
 81 |                     iabSubLoadLib.startSubLoad();
 82 |                 }
 83 |             });
 84 |         } else {
 85 |             //site is already loaded, start subload
 86 |             this.startSubLoad();
 87 |         }
 88 |     } else {
 89 |         //we are in an unfriendly iframe, wait a bit before subload starts or the site sends a message that it is loaded
 90 |         window.addEventListener('message', iabSubLoadLib.postMessageHandler.bind(iabSubLoadLib));
 91 |         iabSubLoadLib.loadTimer = setTimeout(function () {
 92 |             window.removeEventListener('message', iabSubLoadLib.postMessageHandler);
 93 |             iabSubLoadLib.startSubLoad();
 94 |         }, iabSubLoadLib.waitTimer * 1000);
 95 |     }
 96 | }());
 97 | 
 98 | 		
 99 | ``` 
100 | 


--------------------------------------------------------------------------------