Skip to content

Latest commit

 

History

History
185 lines (139 loc) · 7.17 KB

API.md

File metadata and controls

185 lines (139 loc) · 7.17 KB

Modules

AdFrame

Functions

prepareIframe(iframe)

Prepare the iframe element (styles) before insertion into the DOM

establishComms(frameID, [win]) ⇒ Comms

Establish a communication channel with the remote iframe (Waits for a ping from the iframe FIRST before 2-way comms can be configured)

detectCSPBlocking([callback], [doc])

Detect any Content-Security-Policy blocking that affects blob-URLs

Typedefs

AdFrameInjection : Object
CreateAdFrameOptions : Object
Comms : Object

AdFrame

AdFrame.exports.createAdFrame(options) ⇒ HTMLIFrameElement

Create an adframe instance

Kind: static method of AdFrame
Returns: HTMLIFrameElement - The created (and inserted) iframe element

Param Type Description
options CreateAdFrameOptions Creation options

AdFrame.exports.blobURLSupported() ⇒ Boolean

Detect Blob URL support

Kind: static method of AdFrame
Returns: Boolean - True if supported

AdFrame.exports.srcDocSupported() ⇒ Boolean

Detect iframe srcdoc support

Kind: static method of AdFrame
Returns: Boolean - True if supported

prepareIframe(iframe)

Prepare the iframe element (styles) before insertion into the DOM

Kind: global function

Param Type Description
iframe HTMLIFrameElement The target iframe element

establishComms(frameID, [win]) ⇒ Comms

Establish a communication channel with the remote iframe (Waits for a ping from the iframe FIRST before 2-way comms can be configured)

Kind: global function
Returns: Comms - Comms instance

Param Type Description
frameID String The unique AdFrame ID
[win] Window Optional window reference to place the listener

detectCSPBlocking([callback], [doc])

Detect any Content-Security-Policy blocking that affects blob-URLs

Kind: global function

Param Type Description
[callback] function Callback function to fire when detection has completed
[doc] HTMLDocument Optional document reference

AdFrameInjection : Object

Kind: global typedef
Properties

Name Type Description
content String The content to inject
[prepend] Boolean Whether or not to prepend the injected content. Defaults to false (append).

CreateAdFrameOptions : Object

Kind: global typedef
Properties

Name Type Description
content String The HTML content to insert, when in HTML content mode, or the URL to load when in URL content mode
[contentType] String The type of content to use - defaults to CONTENT_HTML
[id] String Optional ID override. Defaults to dynamically generated UNIQUE ID that is used for window-communication.
[injections] Array.<AdFrameInjection> Content injections to inject into the provided content property by detecting tags.
[onBeforeInsert] function Callback fired before the iframe is inserted into the page so that final processing can be performed. This defaults to prepareIframe, which updates styles for the iframe so that it appears seamlessly in the page. Overriding this property will disable this default processing.
[onLoadCallback] function Callback method to fire once the iframe has loaded
parent HTMLElement The parent element to insert the iframe into
[position] String Insertion position. Either "first" among other children in the parent element or "last".
[restoreIframeBuiltIns] Boolean Restore built-in document/window methods if they're detected as having been overridden. Defaults to true. Can help un-break pages where some script has performed some nasty modifications to the page. Operates ONLY within created iframes.
[restorePageBuiltIns] Boolean Same as restoreIframeBuiltIns, but works on the parent, containing page (current document) instead. Defaults to false.
[sandboxFlags] Array.<String> Custom sandbox flags to set when security is set to custom mode (SECURITY_CUSTOM)
[security] String The security mode to use for securing the iframe's contents. Defaults to SECURITY_NONE.
[verifyLoad] Boolean Verify the contents as having been loaded by use of an injected helper. Defaults to false.
[win] Window Window reference
[writeMethods] Array.<String> Write methods that can be used, in order of preference. If no write modes can be selected an error will be thrown.

Comms : Object

Kind: global typedef

Comms.onMessage(cb)

Listen for messages

Kind: static method of Comms

Param Type Description
cb function Callback method to attach as a listener. Is called with message objects.

Example

onMessage(msg => {
         if (msg.type === "something") {
             sendMessage({ type: "response" });
         }
     });

Comms.sendMessage(msg)

Send a message to the remote window

Kind: static method of Comms

Param Type Description
msg Object The message to send

Example

sendMessage({ type: "information", value: 123, another: true });