> For the complete documentation index, see [llms.txt](https://docs.hbwrapper.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hbwrapper.com/rich-media.md). # Rich Media Formats **In plain terms:** a rich media format is a more eye-catching way of presenting an ad — for example an ad that sticks to the bottom of the screen, stays in view as the visitor scrolls, or briefly covers the page. These formats typically earn more than a plain box in the page. The wrapper ships with several ready-to-use formats (adhesion, sticky, peel, interstitial) that you can turn on per ad unit with a few settings, and it also lets developers build entirely new ones. This page has two parts: the built-in formats you can simply configure (jump to [RichMedia Formats Core Modules](#richmedia-formats-core-modules)), and the developer toolkit for creating custom formats (the sections just below). If you only want to switch on an existing format, you can skip straight to the core modules. RichMedia Formats are custom scripts that allow manipulation of how ads are displayed and interact on the page. RichMedia Formats Modules enable the creation of custom RichMedia Formats with various functionalities. RichMedia Formats Modules can be added as a Custom script file in the `src` folder of the wrapper. Here is an example of a RichMediaFormat Module: [Example](https://gitlab.com/adops/wrapper-richmediaformats/-/blob/master/example/src/custom_exampleRichMediaFormatAdapter.js). This example simply adds a label overlay over the ad to display the name of the adunit. ## Importing RichMedia Manager **Description:** This provides the modular functionality inside the wrapper and is required for modularization to work. ```javascript import richMediaManager from '../../src/_richMediaManager.js'; ``` ## Add format to RichMedia Manager **Description:** Calling the `addFormat` function adds the format to the RichMedia Manager, making it available for use in the wrapper. The function takes an object as a parameter with the following properties: **Properties:** 1. `name`: The name of the RichMediaFormat. This name is used in the module and when defining adunits as RichMediaFormats. 2. `options`: An object that holds all the default values for the options. While not strictly required to define a default for all options, it is recommended to have a default value for every option. 3. `bannerPos`: The ORTB 2.0 definition of the position of the ad on the page. * `0`: Unknown * `1`: ATF (Above The Fold) * `2`: DEPRECATED * `3`: BTF (Below The Fold) 4. `initFunc`: This function is called after the ad divs are processed on the page. It takes the DOM element of the ad div as a parameter and can alter or mutate ad divs before the ads are rendered. 5. `registerListener`: This function is called when the GAM `slotRenderEnded` event is fired. It takes the DOM element of the ad div and the GAM event parameter as arguments. This is where you can render the ad. ```javascript export const richMediaFormat = { "name" : "example", "options" : {"option1":"value1"}, "bannerPos" : 0, "initFunc" : function(el){}, "registerListener" : function(el,event){} }; richMediaManager.addFormat(richMediaFormat); ``` ## RichMedia Formats Core Modules **Description:** Some rich media formats are built-in as core modules and can be included and configured directly in the wrapper. To add a core module, add the rich media format module to the `modules.json` file. An adunit can be configured in one of two ways: 1. **In `adunits.json`**: By setting the `richMediaFormat` property. ```json { "adunit":"/22181265/Test_abcd", "device":["desktop","tablet","mobile"], "mediaTypes":{"banner":{"sizes":[[728,90]]}}, "additionalNonHBSizes":[], "targeting":{"pos":"top"}, "lazyLoaded":"false", "richMediaFormat":{"type":"adhesion","options":{"closeButton":"true"}}, "refreshTimed":"0", "refreshViewable":"0", "css":"border: 0px;", "bids" : [ {"bidder":"appnexus","params":{"placementId":"123456"}} ] } ``` 2. **In body div tag**: By setting the data attribute `data-aa-rich-media-format`. ```html
``` ### Adhesion **Type:** `adhesion` **Module:** `adhesionRichMediaFormatAdapter` **Options:** * `closeButton`: If set to `true`, it will add a close button that will close the ad. * `position`: Possible values `header` and `footer`. It will place the adhesion at the header or footer of the page. * `bottomPosition`: The distance from the bottom of the page. It takes any CSS value for the `bottom` property. * `topPosition`: The distance from the top of the page. It takes any CSS value for the `top` property. * `autoClose`: Integer value representing seconds until the format will automatically close. * `closePermanent`: If set to `true`, when a user closes the format, it will also destroy the adunit. ### Sticky **Type:** `sticky` **Module:** `stickyRichMediaFormatAdapter` **Options:** * `closeButton`: If set to `true`, it will add a close button that will close the ad. * `top`: Integer in pixels representing distance from the top. It MUST be used in conjunction with `right` or `left`. * `bottom`: Integer in pixels representing distance from the bottom. It MUST be used in conjunction with `right` or `left`. * `left`: Integer in pixels representing distance from the left. It MUST be used in conjunction with `top` or `bottom`. * `right`: Integer in pixels representing distance from the right. It MUST be used in conjunction with `top` or `bottom`. * `autoClose`: Integer value representing seconds until the format will automatically close. * `closePermanent`: If set to `true`, when a user closes the format, it will also destroy the adunit. ### Peel Ad **Type:** `peel` **Module:** `peelRichMediaFormatAdapter` **Options:** * `closeButton`: If set to `true`, it will add a close button that will close the ad. * `top`: Integer in pixels representing distance from the top. It MUST be used in conjunction with `right` or `left`. * `bottom`: Integer in pixels representing distance from the bottom. It MUST be used in conjunction with `right` or `left`. * `left`: Integer in pixels representing distance from the left. It MUST be used in conjunction with `top` or `bottom`. * `right`: Integer in pixels representing distance from the right. It MUST be used in conjunction with `top` or `bottom`. * `closePermanent`: If set to `true`, when a user closes the format, it will also destroy the adunit. ### Interstitial **Type:** `interstitial` **Module:** `interstitialRichMediaFormatAdapter` **Options:** * `timeOpen`: Integer value representing the time in seconds until the close button is available to click. * `timeOpenShow`: If `true`, it will show the timer until the close button is available. * `maxDisplayPerSession`: Integer value representing the maximum displays in a session. * `pageviewDisplayStart`: Integer value representing the first pageview count when the interstitial will display. * `pageviewDisplayEvery`: Integer value representing when to display the interstitial repeatedly based on pageview count. * `backgroundColor`: Hex value or other CSS color representing the background of the interstitial. * `opacity`: Float value representing the CSS opacity of the background. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hbwrapper.com/rich-media.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.