{"id":15687047,"url":"https://github.com/perry-mitchell/adframe","last_synced_at":"2026-03-04T14:31:53.455Z","repository":{"id":57173371,"uuid":"207025087","full_name":"perry-mitchell/adframe","owner":"perry-mitchell","description":"Iframe control system designed for iframes that contain ads","archived":false,"fork":false,"pushed_at":"2019-09-11T12:11:03.000Z","size":1600,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-12T16:50:28.731Z","etag":null,"topics":["ads","iframe","iframe-api","iframe-embeds","iframe-hack","secure-frame"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perry-mitchell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-07T20:57:46.000Z","updated_at":"2022-11-19T00:24:45.000Z","dependencies_parsed_at":"2022-08-24T13:31:07.894Z","dependency_job_id":null,"html_url":"https://github.com/perry-mitchell/adframe","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fadframe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fadframe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fadframe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fadframe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perry-mitchell","download_url":"https://codeload.github.com/perry-mitchell/adframe/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240254181,"owners_count":19772386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ads","iframe","iframe-api","iframe-embeds","iframe-hack","secure-frame"],"created_at":"2024-10-03T17:42:42.328Z","updated_at":"2025-02-23T00:45:43.481Z","avatar_url":"https://github.com/perry-mitchell.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AdFrame\n\u003e Iframe control system designed for iframes that contain ads\n\n[![Build Status](https://travis-ci.org/perry-mitchell/adframe.svg?branch=master)](https://travis-ci.org/perry-mitchell/adframe) [![npm version](https://badge.fury.io/js/adframe.svg)](https://www.npmjs.com/package/adframe)\n\n# About\n\nCreate **well-prepared** iframes that are designed to handle dynamic advertising content held within. This library doesn't necessarily need to only be used in the advertising realm, and its array of features will most likely find it useful in a variety of situations.\n\nIframes created using this library can use a number of content insertion methods (blob URLs, `document.write`, `srcdoc` etc.), some combinations of iframe `sandbox` flags, content-loaded detection and a wealth of other tools.\n\nTo dive straight in to creating an iframe, check out the [API documentation](API.md).\n\nCreation of AdFrame iframes is performed by using a single synchronous method, which outputs the iframe (`createAdFrame`). On-load listeners can be attached via the creation options:\n\n```javascript\nimport { createAdFrame } from \"adframe\";\n\nconst container = document.querySelector(\"#container\");\n\ncreateAdFrame({\n    content: \"\u003cdiv\u003e\u003cp\u003eSome content\u003c/p\u003e\u003c/div\u003e\",\n    parent: container,\n    onLoadCallback: () =\u003e {\n        console.log(\"Loaded!\");\n    }\n});\n```\n\n_Promises are not used so as to not bloat the library with polyfills (as IE 10 is supported, for example)._\n\nIframes with URLs can also be created:\n\n```javascript\nimport { CONTENT_URL, createAdFrame } from \"adframe\";\n\ncreateAdFrame({\n    content: \"https://some-page.com\",\n    contentType: CONTENT_URL,\n    parent: container,\n    onLoadCallback: () =\u003e {\n        console.log(\"Loaded!\");\n    }\n});\n```\n\nIframes created by AdFrame are prepared, in terms of styling, before being inserted. This functionality can be overidden by changing the `onBeforeInsert` property to another function. You should, if you prefer that your iframe _looks_ good, still call the default styling function:\n\n```javascript\nimport { createAdFrame, prepareIframe } from \"adframe\";\n\ncreateAdFrame({\n    content: \"\u003cdiv\u003e\u003cp\u003eSome content\u003c/p\u003e\u003c/div\u003e\",\n    onBeforeInsert: iframe =\u003e {\n        prepareIframe(iframe);\n        iframe.setAttribute(\"id\", \"my-iframe\");\n    },\n    parent: container\n});\n```\n\n## Security\n\nSecure iframes can be generated by passing one of the available security flags, or by passing a custom configuration:\n\n * `SECURITY_SANDBOX_NONFRIENDLY`: Sandbox the iframe and remove the `allow-same-origin` flag to completely lock down the container.\n * `SECURITY_SANDBOX_SAMEORIGIN`: Sandbox the iframe but keep the `allow-same-origin` flag to allow top-page referencing from within the container.\n * `SECURITY_CUSTOM`: Sandbox the iframe with a custom list of flags, provided by the `sandboxFlags` option\n * `SECURITY_NONE`: No sandboxing (default)\n\n```javascript\nimport { SECURITY_CUSTOM, createAdFrame } from \"adframe\";\n\ncreateAdFrame({\n    content: \"\u003cdiv\u003e\u003cp\u003eSome content\u003c/p\u003e\u003c/div\u003e\",\n    parent: container,\n    security: SECURITY_CUSTOM,\n    sandboxFlags: [\n        \"allow-forms\",\n        \"allow-scripts\",\n        \"allow-same-origin\",\n        \"allow-downloads-without-user-activation\",\n        \"allow-storage-access-by-user-activation\"\n    ]\n});\n```\n\n## Messaging\n\nAdFrame establishes a 2-way communication channel between iframe windows and the context where the AdFrame instance was created. This channel can be used to send messages directly to and from the contained window without the need to do all of the `window.postMessage` preparation yourself.\n\nFrom within the iframe, use the following methods:\n\n```javascript\nwindow.AdFrame.sendMessage({ type: \"something\" });\n\nwindow.AdFrame.onmessage(msg =\u003e {\n    if (msg.type === \"response\") {\n        // ...\n    }\n});\n```\n\nFrom the context where the AdFrame was created:\n\n```javascript\nimport { createAdFrame } from \"adframe\";\n\nconst iframe = createAdFrame({\n    content: \"\u003cscript\u003e...\u003c/script\u003e\",\n    parent: container\n});\nconst { sendMessage, onMessage } = iframe;\n\nsendMessage({ type: \"hello\", customProp: true });\n\nonMessage(msg =\u003e {\n    if (msg.type === \"query\") {\n        sendMessage({ type: \"response\" });\n    }\n});\n```\n\nThe messaging interface works even if iframe sandboxing is configured.\n\n## Built-In Browser Method Restoration\n\nSome pages/scripts like to boast brand-safe ad-quality protection and the like, and can go as far as to override built-in methods like `document.write`, claiming this is so that they can control what ads are rendered. I, personally, don't trust third parties to make such a decision and risk forcing all scripts and third-parties on a page to use potentially unstable JavaScript to inject ad content. AdFrame, by default, removes overridden functions when detected. You can _disable_ this functionality by setting the `restoreIframeBuiltIns` option to `false`.\n\nThe `restoreIframeBuiltIns` operates only within the confines of new iframes created using AdFrame, but you can also trigger method restoration on the global page by setting `restorePageBuiltIns` to `true` (defaults to `false`).\n\n## Content Injection Methods\n\nAdFrame comes with a variety of ways to inject HTML content into an iframe, and this can be controlled via the `writeMethods` option. `writeMethods` takes an array of _allowed_ injection methods, listed in order of preference. They are automatically stripped of incompatible items when running, and if none are left after this process an error is thrown. The available methods are (listed in default order):\n\n * `WRITE_MODE_BLOB_URL`: Use [Blob URLs](http://qnimate.com/an-introduction-to-javascript-blobs-and-file-interface/#Blob_URLs) to inject content (preferred)\n * `WRITE_MODE_SRCDOC`: Use the iframe `srcdoc` attribute, along with base 64 encoding/decoding, to inject content\n * `WRITE_MODE_DOC_WRITE`: Use `document.write` to inject content (not available when using sandboxing)\n\nIt is recommended to leave `writeMethods` to the default value in most cases, as it will auto-detect what's best for the current environment and content.\n\n### Checking Compatibility\n\nIt is **vital** that, when running in unknown environments, that you first check for compatibility for running configurations such as `WRITE_MODE_BLOB_URL`. `WRITE_MODE_BLOB_URL` requires that a Content-Security-Policy is _not_ set up to block certain `frame-src` values. For instance - the following HTTP header would break `WRITE_MODE_BLOB_URL`:\n\n```\ncontent-security-policy: frame-src https:;\n```\n\nTo get around this, you _could_ simply disable `WRITE_MODE_BLOB_URL` by omitting it, but that could prove quite cumbersome. Instead you could use the `detectCSPBlocking` method to process this detection early-on:\n\n```javascript\nimport { createAdFrame, detectCSPBlocking } from \"adframe\";\n\nfunction buildFrame() {\n    return doSomethingElse()\n        .then(() =\u003e new Promise(resolve =\u003e\n            detectCSPBlocking(resolve)\n        ))\n        .then(() =\u003e createAdFrame({\n            // ...\n        }));\n}\n\nbuildFrame();\n```\n\nThe method only needs to be run once, and `createAdFrame` will internally strip out `WRITE_MODE_BLOB_URL` from future configurations.\n\n## Injecting Extra Content/Snippets\n\nSometimes you're given a template of data to inject along with several other snippets of HTML (styles, JavaScript etc.) to write into the same frame. This can become tedious when the primary content to insert already has a `\u003cbody\u003e`. AdFrame provides the `injections` option to allow for inserting extra snippets of content correctly within the main `content`:\n\n```javascript\nimport { createAdFrame } from \"adframe\";\n\ncreateAdFrame({\n    content: \"\u003chtml\u003e\u003cbody\u003e\u003cp\u003eTest\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e\",\n    injections: [\n        { content: \"\u003cstyle\u003ebody { background: red; }\u003c/style\u003e\", prepend: true },\n        { content: \"\u003cfooter\u003eFooter\u003c/footer\u003e\" }\n    ],\n    parent: container,\n    onLoadCallback: () =\u003e {\n        console.log(\"Loaded!\");\n    }\n});\n```\n\n## Verifying Load State\n\nAdFrame can further verify that iframe content was loaded by using `postMessage` to ping an injected internal script. Enable this functionality by using the `verifyLoad` option. Defaults to `false`.\n\n## Browser Support\n\nIE 10 and newer.\n\n_NB: This section not negotiable._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fadframe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperry-mitchell%2Fadframe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fadframe/lists"}