KARMA Integration Guide

KARMA is Meredith's in-house Javascript framework for serving up ads on websites. It's essentially a wrapper around Google's Publisher Tags (GPT). KARMA gathers information about the page, the user, and the ad slots desired, then requests those ads from GAM (Google Ad Manager, Google's ad serving platform).

KARMA is different from stock GPT in that it seamlessly integrates with many of Meredith's third-party revenue partners, requesting real-time bids for programmatic and intent-based premium ad content. KARMA also gives you access to the full suite of Meredith's ad playbook products, with minimal technical integration. We also handle things like timed refresh, dynamic injection of ads, and leaderboard/right rail docking.

To integrate KARMA on your website, you need two basic pieces:

1. KARMA config/init JS snippet in the head
2. KARMA placeholder div tags in the body

PLEASE NOTE: You can only use the KARMA 3 integration OR the KARMA 2 integration. A horrible Frankenstein's-monster amalgamation of both WILL NOT WORK. Please see the KARMA 3 Migration Guide for more details.

KARMA config/init snippet

A chunk of inline Javascript in the head of your site, which tells us what kind of page and device we're on, does ad-block detection, then makes the call to initialize KARMA.

You will need to modify this code to reflect values for your site. More details on each property are below in the KARMA config properties section.

KARMA placeholder div tags

Empty div tags in the HTML that tell us where and what kind of ads should display. These divs have unique ids and data attributes that tell us the ad slot size and position.

Not sure which placeholder you need? Check out our list of placeholders here.

Instant Slots

Instant slots are any slots that load immediately upon KARMA initialization. By default KARMA placehodler divs will load instant slots.

Lazy Scroll Slots

Lazy scroll slots are included in the HTML markup, but they are not requested until the user scrolls within a specified pixel threshold (karma.config.lazyScrollThreshold). Slots are treated as lazy scroll if they have the data-lazy-scroll="true" attribute. Lazy scroll slots are requested in batches as set by karma.config.lazyScrollBatchSize. Lazy scroll slots are treated like instant slots if they are within the threshold at the time of the ad request.

Ad Slot Initialization Timing

By default, KARMA will listen for the DOMContentLoaded event to trigger the scraping of the DOM for ad slots to fill. Alternatively, for finer tuning, a call to window.karma.config.go() can be placed on the page as an inline script to inform KARMA that all ad slots are on the page and the DOM is ready to be scraped.

For pages that modify or build the DOM dynamically, the property karma.config.bypassDOMReady can be set to true. This bypasses the DOMContentLoaded listener and relies soley on the page to call karma.config.go() to initialize the ad slots.

Note: window.karma.config.go is defined in the minified KARMA initial load snippet, so your call to window.karma.config.go() must be included after that definition.

Example Pages

For a fully functioning example of a page that has nothing but KARMA ads on it, see:

• http://karma.mdpcdn.com/files/docs/examples/desktop.html
• http://karma.mdpcdn.com/files/docs/examples/mobile.html

On-Page Config Properties

Specific documentation on the on-page KARMA configuration properties follows.

KARMA also sets configuration properties on our end. See inspecting KARMA Config values for more.

karma.config.apiVersion - required

Type: number

Currently, we have some sites using a legacy (v2.x) KARMA integration with a different configuration pattern. While we're transitioning sites over to KARMA 3.x, we require the apiVersion parameter to let us know that we're on a KARMA 3.x site.

karma.config.isMobile - required

Type: boolean

We rely on you to tell us whether we're on a mobile or desktop device type. You can use any kind of device detection you like, but we recommend user agent-based detection, rather than screen size detection.

This existed in KARMA 2.x as: adService.mobileAds

karma.config.refresh.userInitiated.slotTypes

Type: Array

An array that lists all the slots which will be refreshed.

karma.config.site

Type: string

A string that tells us which site we’re on. This corresponds to the top-level ad unit, and is usually in the form of site.mdp.com/site.mdp.mob. In normal situations, you don’t need to provide this value, as KARMA will attempt to pull it from your hostname via fancy regex. If you’re on a development environment with a weird hostname (like localhost or an IP address), you’ll need to tell KARMA which site you’re on. Note that the value is different per device, so if you’re manually providing it, you’ll need to check the value of karma.config.isMobile to provide the correct string on each device type.

Note that you can also use the adTestSite URL parameter to accomplish this on localhost withou modifying your site code.

This existed in KARMA 2.x as: adService.unitValues.adDomain

karma.config.targeting - required

Type: object

All page-level targeting key-value pairs are passed in window.karma.config.targeting. You must include the required key-value pairs id, type, and channel, and you may add a number of other free-form key-value pairs, so long as both key and value are:

• an alphanumeric string (dashes and underscores are allowed), or an array of strings for certain values (like kw)
• under the character limits (20 characters for keys, 40 characters for values)

This existed in KARMA 2.x as: adService.pageTargetingValues, adService.unitValues

karma.config.targeting.id - required

Type: string

A string that uniquely identifies the page that we're on. This enables us to target ads to a particular page, in the event a sponsorship is sold for a given page. Whenever possible, please use the Content Id passed to Google Analytics. Values used for this property must be:

• unique to each page
• alphanumeric characters only
• less than (or equal to) 40 characters long

If the GA Content Id is not available we recommend using the URL pathname, with non-alphanumeric characters stripped (unless your URLs are very long, in which case you will need to trim them).

This existed in KARMA 2.x as: adService.pageTargetingValues.id

karma.config.targeting.type - required

Type: string

A string that tells us what kind of page we're on. There is a fixed list of page types. Please select the one that most closely resembles your content.

Standard KARMA page types:

1. app (for applications, with a corresponding 'app_name' value)
2. article
3. audio
4. audio_hub
5. category
6. channel
7. collection
8. freestuff
9. homepage
10. landing_page
11. longform
12. none (default)
13. page (for miscellaneous info pages)
14. photos
15. post (for blog posts)
16. print
17. product
18. profile
19. project
20. recipe
21. recipe_hub
22. reviews
23. search
24. slideshow
25. slideshow_hub
26. sponsored_collection
27. sponsored_recipe_hub
28. sponsored_print
29. sponsored_profile
30. sponsored_recipe
31. tag
32. video
33. video_article
34. video_hub
35. video_playlist
36. video_recipe

If you have a page type that doesn't fit one of these, please contact a KARMA representative by emailing adsupport@meredith.com.

This existed in KARMA 2.x as: adService.pageTargetingValues.type

karma.config.targeting.app_name

Type: string

If the ‘type’ is ‘app’, you need to also tell us the name of the application.

This existed in KARMA 2.x as: adService.pageTargetingValues.app_name

karma.config.targeting.search

Type: string

Required on pages with a type of ‘search’ only.

A string that indicates the term the user searched for. This parameter is only required on search results pages where the user has passed in a search term. It can be omitted or set to an empty string on all other pages.

This existed in KARMA 2.x as: adService.pageTargetingValues.search

karma.config.targeting.channel - required

Type: string

A string that tells us where this page falls in your site's top-level hierarchy. This existed in KARMA 2.x as: adService.unitValues.channel.

karma.config.targeting.parent

Type: string

A string that tells us where this page falls in your site's second-level hierarchy. This existed in KARMA 2.x as: adService.unitValues.parent.

karma.config.targeting.child

Type: string

A string that tells us where this page falls in your site's third-level hierarchy. This existed in KARMA 2.x as: adService.unitValues.child.

karma.config.targeting.kw

Type: array

If keywords are provided, they should be passed in as an array of strings.

This existed in KARMA 2.x as: adService.pageTargetingValues.kw

karma.config.targeting.foo

Type: string/array

You can pass any other key/value pairs in the karma.targeting object. Both the key and value must be:

• an alphanumeric string (dashes and underscores are allowed), or an array of strings
• under the character limits (20 characters for keys, 40 characters for values)

These key/value pairs will be passed along to the ad request and can be targeted in GAM line items as custom criteria.

This existed in KARMA 2.x as: adService.pageTargetingValues.foo

karma.config.callback

Type: array

If you need a piece of Javascript to run after ads have rendered, use this parameter to pass in an array of functions. These functions will execute after each ad slot is finished rendering.

Each function takes an event parameter that corresponds to GPT’s SlotRenderEnded Event.

Please always use the syntax included in the example, where you initialize the callback array and push into it. This will avoid timing issues with KARMA initialization.

Note that all callbacks will run on each ad slot every time ads are loaded in the slot, so if you have logic that’s specific to a single slot, you will need to check for the correct div id (see example above).

This existed in KARMA 2.x as: adService.callback, where it was sometimes represented as a single function instead of an array. It should always be an array today.

karma.config.bypassDOMReady

Type: boolean

WARNING: You should only set this property to true if you want complete control over when KARMA scrapes the page for ad slots, i.e. if the DOM is dynamically built in a single page application. If you use this, you will also need to manually trigger window.karma.config.go().

karma.config.suppressInterstitial

Type: boolean

Suppresses the automatic addition of div-gpt-interstitial and div-gpt-wallpaper to the page. Add this only if directed by Meredith Ad Product.

karma.config.euPrivacy.enabled

Type: boolean

Turns on non personalized ads mode in Google Ad Manager to help sites comply with the General Data Protection Regulation (GDPR).

On most Meredith-owned sites, this does NOT need to be manually set, as we have a integration with OneTrust with that will handle consent and the resulting settings automatically. If you do not have a OneTrust integration, you can check/gather consent manually and set this property accordingly.

karma.config.usPrivacy.enabled

Type: boolean

Turns on restricted data processing mode in Google Ad Manager to help sites comply with the California Consumer Privacy Act (CCPA).

On most Meredith-owned sites, this does NOT need to be manually set, as we have a integration with OneTrust with that will handle consent and the resulting settings automatically. If you do not have a OneTrust integration, you can check/gather consent manually and set this property accordingly.

Inspecting KARMA Config Values

• To see the values of KARMA config properties set by the page, inspect window.karma.config.onPageSettings
• To see the values of KARMA config properties set by the KARMA config layer, inspect window.karma.config.static

These values are merged into a final object that is the one that's in use by KARMA. To inspect that, look at window.karma.config or use the config tab of the KARMA bookmarklet

Integration FAQ

Here are some common questions and pitfalls we encounter when doing a site integration.

How do I know what placeholders to put on my page?

If you received a mapping document from the Meredith Ad Product team, it should include a list of placeholders codes. See below for how to interpret those codes. Otherwise, we have a full slot catalog here.

How do I translate a KARMA mapping placeholder code?

If you received a mapping document, you may see codes indicating which placeholders should go on the page.

If you see div-gpt-slot-type-n:tierx:

• This is an instant slot

  • ‘n’ is an integer that uniquely identifies the placeholder on the page
  • ‘x’ is an integer that defines the tier for this slot
• The resulting HTML markup should be: <div id="div-gpt-slot-type-n" data-tier="x" role="complementary" aria-hidden="true">

If you see div-gpt-lazy-slot-type-tierx:

• This is a lazy slot
• You should make a call in your site Javascript to createSlot (see example)

If you have a question about which tier applies to which placeholder on your site, contact a KARMA representative to help you out by emailing adsupport@meredith.com.

What is a tier?

The data-tier attribute is a way to tell us how important and/or visible an ad slot is on a given page. Tiers go from 1 to 4.

More details on tiers here

How do I load an ad slot after the initial ad request is made?

This is referred to as a lazy load ad, and you will use our createSlot method to create it with Javascript.

Things to watch out for

• Do not give any divs the prefix div-gpt except for the KARMA placeholders. When KARMA loads on a page, it looks for all divs that start with div-gpt and presumes that these are instant slot placeholders. Please don’t use that id pattern for anything else.
• Do not dynamically move ad container divs around in the DOM. This is common in masonry layouts and some docking solutions. If you dynamically move divs that contain ads around in the DOM, it effectively wipes out the contents of the iframe and causes a ‘no ad returned’ message in the KARMA bookmarklet.
• Make sure to wrap all lazy load ad invocations in window.karma.cmd.push().
• Lazy loading of ads will only work after KARMA is present on the page and initialized.
• Do not delete or modify window.karma, apart from configuration values discussed above. KARMA relies on these globally scoped variables in order to do its thing.
• To comply with accessibility requirements, all KARMA slots must include role="complementary" and aria-hidden="true" attributes on the placeholder div.

Slot Catalog

An ad slot is a spot on the page where an ad renders, denoted with an empty div tag. These divs have unique ids and data attributes that tell us what kind of ad to display.

KARMA supports three types of ad slots:

• instant ads are included in the page's HTML markup and filled as soon as they are requested.
• lazy scroll ads are a variant of instant ads that are filled when scrolled into view.
• deferred ads are a variant of instant ads that are filled after a certain amount of time passes after the initial ad request. These are configured in the KARMA config layer and require no additional site setup.
• lazy load ads are dynamically added to the page with Javascript based on user interaction (see createSlot for more details).

The placeholder divs have three major properties:

• id, e.g. id="div-gpt-leaderboard-flex-1"
• tier, e.g. data-tier="1"
• lazy-scroll, e.g. data-lazy-scroll="true"

KARMA Ad Placeholder IDs

The value of the id on the placeholder div represents the following formula: div-gpt-slottype-sizetype-iterator

• prefix: this is always div-gpt (on desktop) or div-gpt-mob (on mobile) Please do not have any other divs on the page that start with div-gpt. This will confuse KARMA.
• slot type: e.g. leaderboard, square, adhesive-banner, fluid
• size type: fixed, flex, responsive (see tables below)
• iterator: a unique number tacked on to the end of the id that makes it unique, e.g. div-gpt-square-fixed-1, div-gpt-square-fixed-2

A list of supported combinations is in the tables below.

KARMA is expecting to find div tags in the DOM with these specific ids. Changing the id values will result in no ad returned.

Desktop Ad Placeholders

Mobile Ad Placeholders

Note: there are DIFFERENT placeholders for mobile and desktop. Responsive sites should put both placeholders in the markup. KARMA will use the value of karma.config.isMobile to determine which placeholders to fill.

Ad Slot Tiers

The data-tier attribute is a way to tell us how important and/or visible an ad slot is on a given page.

Tiers go from 1 to 4. Generally, the top leaderboard and the top square-flex are tier 1 (highly visible when the page first loads), anything at the bottom of the page is tier 4 (not very visible at all), and the others fall somewhere in between.

Click the images below to get an idea of how tiers break down on a typical Meredith site.

Desktop	Mobile

Note: the iterator number on the end of the placeholder id and the tier value do not necessarily correlate. The former is a unique slot identifier; the latter is a tier identifier.

Lazy Scroll Ads

If you include data-lazy-scroll="true" as a property on your instant placeholder div, the ad will be defined on page load, but won't be requested/filled until the ad scrolls into view.

There is a threshold defined in the KARMA Config (karma.config.lazyScrollThreshold) that determines how far away from the lazy scroll ad we start filling it.

Lazy Load Ads

Any ad slot can also be lazy loaded via Javascript using the KARMA createSlot API method. When requesting an ad via the createSlot method, you will need to pass the prefix, slot type, size type, and tier, as well as the id or DOM node of the place where the ad should be injected. You do not need to pass the iterator.

More details on all the createSlot options here.

Ad Placeholder Visibility

When KARMA loads, it detects whether or not the placeholder divs are hidden by site CSS. If the div is not visible, KARMA will not request the ad. You can take advantage of this functionality to display different desktop ads on medium vs. large breakpoints.

API Methods

karma.cmd.push

Execute a function after KARMA has initialized and made the initial ad request. We recommend that you push all KARMA API calls into karma.cmd, to rule out any problems with timing (if your code loads before KARMA does, for instance).

Please always use the syntax included in the example, where you initialize the cmd array and push into it. This will avoid timing issues with KARMA initialization.

karma.createSlot

Create a lazy loaded slot and inject it into an existing DOM element on the page.

karma.createSlot(slotName, container, autofill, callback, options)

This existed in KARMA 2.x as: adService.renderAds.createLazyLoadSlot(), adService.renderAds.createInfiniteScrollSlot()

karma.destroySlot

Remove a slot from the page.

karma.destroySlot(slotId)

This existed in KARMA 2.x as: adService.renderAds.destroySlot()

karma.fillSlots

Fills all unfilled slots with a single ad request. This is recommended performance practice if you're adding more than one lazy loaded slot at a time, to save on HTTP requests.

This existed in KARMA 2.x as: adService.renderAds.fillLazyLoadSlots()

karma.getSlotById

Returns a KARMA slot object.

karma.getSlotById(slotId)

If no valid ID is provided, undefined will be returned.

karma.getSlotCount

Returns an integer. Get the total number of slots registered for this page.

This existed in KARMA 2.x as: adService.renderAds.getSlotCount()

karma.isInView

Is the given slot in view? Returns a boolean.

karma.isInView(slotId, bypassFocusRules)

This existed in KARMA 2.x as: adService.renderAds.isInView()

karma.report

Pass reporting info to segment.

karma.report(name, value)

karma.report('CollapseCode', 1234567890) // Example of Collapse Code reporting the creative id that called it.

karma.updateTargeting

Update page or slot-level targeting values.

karma.updateTargeting(newTargetingObj, slotId)

This existed in KARMA 2.x as: adService.renderAds.updatePageTargeting(), adService.renderAds.updateSlotTargeting()

karma.disableTimedRefreshOnSlot

Disable timed refresh on a given slot.

karma.disableTimedRefreshOnSlot(slotId, permanent)

See here for more examples

This existed in KARMA 2.x as: adService.renderAds.disableTimedRefreshOnSlot()

karma.reEnableTimedRefreshOnSlot

Re-enabled timed refresh on a given slot.

karma.reEnableTimedRefreshOnSlot(slotId)

karma.releaseDocking

Undock any KARMA-docked leaderboards. (We plan to update this to include rail docking as well in the near future.)

This existed in KARMA 2.x as: adService.renderAds.forceReleaseBanner()

karma.rebuildRails

Re-inititalizes rail docking (after a new piece of content is injected onto the page, for instance). For more details, see our rail docking documentation

karma.refresh

Triggers a user-initiated refresh (for example, when a user clicks to the next slide in a slideshow). The slot types that are eligible for user-initiated refresh can be inspected at window.karma.config.refresh.userInitiated.slotTypes.

This existed in KARMA 2.x as: window.refreshAdFrame()

karma.setBypassViewabilityRequirement

Setting bypassViewabilityRequirement to true on a slot will allow it to timed refresh even if the slot is not in the viewport, or if it is covered by another DOM element. This setting does not bypass window focus rules. No slot will timed refresh if the browser window containing that slot is not focused.

karma.setBypassViewabilityRequirement(slotId, true)

karma.config.callback.push

Add a function to the list of functions that run after each slot is rendered.

Each function takes an event parameter that corresponds to GPT’s SlotRenderEnded Event.

karma.config.callback.push(fn)

Please always use the syntax included in the example, where you initialize the callback array and push into it. This will avoid timing issues with KARMA initialization.

Note that all callbacks will run on each ad slot every time ads are loaded in the slot, so if you have logic that’s specific to a single slot, you will need to check for the correct div id (see example above). It is good practice to write your callbacks in such a manner that they only execute once.

Each callback that we add that does minimal operations (such as reading and/or variables) consistently adds about .8 ms per slot in the request to the slotOnLoad time. This number increases to ~2ms when DOM lookups are included in the callback (via document.querySelector()).

This existed in KARMA 2.x as: adService.renderAds.addToCallbackList

karma.config.go

Manually trigger the KARMA init process. Using this method is optional unless karma.config.bypassDOMReady is set to true.

When using KARMA 3, by default the page is scraped for instant slots when the DOMContentLoaded event fires. If DOMContentLoaded has already fired by the time KARMA is ready to scrape the page (i.e. doc.readyState !=='loading') then the page is scraped at that point.

In order to jump start the scraping of the page, karma.config.go() can be called to start slot scraping prior to the DOMContentLoaded event firing. No additional configuration is required to use karma.config.go(). If it is fired after DOMContentLoaded it is ignored, and if it is before, then DOMContentLoaded is ignored (see oneTimeCallbackTrigger() inside dom.js).

The one exception is if karma.config.bypassDOMReady is set to true. In this case, karma.config.go() must be called as KARMA ignores the state of the DOM.

Note: window.karma.config.go is defined in the minified KARMA initial load snippet, so your call to window.karma.config.go() must be included after that definition.

karma.resetVideoTargeting

Clear header bidding targeting and reset the video targeting object (window.karma.vars.videoTargeting). This method should be called after a video ad request has been sent to GAM containing header bidding targeting. Header bidding targeting is valid for one impression and must be cleared after it is used.

Video targeting is stored on window.karma.vars.videoTargeting where it can be picked up by the video player at the time of the ad request.

karma.resetVideoTargeting()

karma.updateVideoTargeting

Request new video ad bids. This function does not accept a callback, so it is reccomended that it be called 5 seconds before an upcoming video ad request is made. This is intended to be used for subsequent videos in a video playlist.

Video targeting is stored on window.karma.vars.videoTargeting where it can be picked up by the video player at the time of the ad request.

karma.updateVideoTargeting()

Events

Events emitted by KARMA in the lifecycle of your page.

karmaTargetingReady - when page targeting is ready

Fires when KARMA has finished processing page-level targeting. If you are sniffing for KARMA page types in your code, this would be a good thing to listen for.

Note: this event fires before the ad request has been made.

leaderboard_docked

Fires when the leaderboard is docked to the top of the page.

document.body.addEventListener("leaderboard_docked", function() {
    console.log("The leaderboard is now docked.");
});

leaderboard_undocking

Fires when the leaderboard is in the process of undocking from the top of the page.

document.body.addEventListener("leaderboard_undocking", function() {
    console.log("The leaderboard is now undocked.");
});

leaderboard_undocked

Fires when the leaderboard docking is released.

document.body.addEventListener("leaderboard_undocked", function() {
    console.log("The leaderboard is now undocked.");
});

karmaRequest

Fires on window immediately before any KARMA request is made to GAM. Event.detail will return a stringified JSON containing a map of the slots being requested (slotContainer), and how they were requested (refreshType);

Note: This event only returns info for the slots that are acutally being sent to GAM. For example, any slots that are hidden at the time of request, thus not sent to GAM will not be returned in the event.

karmaStopRefresh

KARMA listens for this event to disable timed refresh on a particular slot. This is used instead of (karma.disableTimedRefreshOnSlot)[karmadisabletimedrefreshonslot] in Google Ad Manager when the creative is served inside a cross-domain iframe (aka safeframe).

karma.cmd.push

Fires when the initial ad request has been made.

This is a method, not an event, but if you want to delay any of your code until after KARMA has been initialized and the initial ad request has been made, you will want to wrap your code in karma.cmd.push

karma.config.callback

Fires when ad creative is returned for each slot.

Like karma.cmd.push above, this is a method, not a event. But if you want to run code after ad creative is returned for each slot, you will want to push it into karma.config.callback.

Functions pushed into karma.config.callback will be executed as a GPT slotRenderEnded event. An argument will be passed into the function that gives you access to the GPT Slot Object via the .slot property (see example).

Reporting

KARMA has the ability to report on specific events.

Segment Reporting

KARMA has 2 functions to report on creative wrapper behavior.

Reports to segment when collapse code has been called. This function is called from the collapse code creative wrapper, and passed the creativeId for tracking in BigQuery

Reports to segment when refresh kill code has been called. This function is called from the creative when refresh has been killed, and it passes the creativeId for tracking in BigQuery

KARMA 3 Migration Guide

PLEASE NOTE: You can only use the KARMA 3 integration OR the KARMA 2 integration. A horrible Frankenstein's-monster amalgamation of both WILL NOT WORK.

KARMA recently underwent a major API overhaul, known interally as KARMA 3. As of right now, it is basically functionally identical to previous versions of KARMA, and it's fully backwards compatible. Everyone should upgrade their integration to KARMA 3 to take advantage of future functionality releases.

K3 Benefits

• 1 KARMA file instead of 2!
• Built-in adblock detection!
• Cleaner API!

TL;DR

• Instead of calling karma.header.js/karma.footer.js, you now make one call to karma.js in the head.
• window.adService config property names have all changed
• Placeholder divs have NOT changed, unless you never upgraded to tiers.
• adService.renderAds and all other API methods have changed. (You can start using the new API Methods immediately, even if your config snippet has not been updated.)

New Config Properties in KARMA 3

Get details on all the config properties here.

Changes to Existing Config Properties

Get details on all the config properties here.

API Method Changes in KARMA 3

You can start using the new API methods immediately, even if your config snippet has not been updated.

Get details on all the API methods here.

Slot placeholder ID Changes in KARMA 3

Technically, these have all been gone for years. But some of you are still using them. Stop it, please.

Get the full list of slot placeholders here.

Note: -n and :tierx are not literal strings. See how do I translate a KARMA mapping code?

KARMA Docking

The docking banner functionality for both leaderboards and rails can now be handled by Karma. When docking is turned on, the class 'docked' will be added to the specified container. The site team can then handle the CSS as they need to dock the container.

Docking can be turned on for specific page types, or site wide.

To request leaderboard docking be turned on for a site, please contact the AdDev team and supply the following information, then add the standard docking classes to your page as defined below:

• KARMA page types to dock the leaderboard on (or all pages)
• Sample URLs
• Should the banner roll back up after a specified time? ** How long? (10 sec default)
• Should the leaderboard dock on screens less that 1025px in width?

To request rail docking be turned on for a site, please contact the AdDev team and supply the following information, then add the standard docking classes to your page as defined below:

• KARMA page types to dock the leaderboard on (or all pages)
• Sample URLs
• Margin in pixels that the docked container should be from the top of the page.

Standard Docking Element Classes

KARMA is expecting these classes to be on the appropriate divs on the page that correspond to our docking needs. These are the network default classes; it can be overridden at the site and page type level. You can see what selectors are configured for the page you're on by looking at karma.config.docking, either in the console, or on the config tab of the KARMA bookmarklet

Leaderboard

• dockingElementSelector: '.karma-leaderboard-docking-element'
• belowBannerSelector: '.karma-below-banner'
• siteContainerSelector: '.karma-site-container'

Rail

• dockingElementSelector: '.karma-rail-docking-element'
• contentContainerSelector: '.karma-content-container'
• mainColumnSelector: '.karma-main-column'
• railSelector: '.karma-sticky-rail'

Docking Events

We have three docking-related events available:

• leaderboard_docked
• leaderboard_undocking
• leaderboard_undocked

Release Leaderboard Docking

To release the docked leaderboard, use the releaseDocking API method.

Rebuild Rail Docking

On pages where rail markup is added to the DOM after page load, once the new content and rail is added, simply call karma.rebuildRails(). This will re-init all pre-existing rails and add any new rails that match the specified class selectors.

Use the rebuildRails API method.

There is an example page with multiple rails and lazy rails here: http://karma.mdpcdn.com/files/docs/examples/desktop-multi-rail.html

Docking Use Cases

Mobile Adhesive Banner Styling

If you include a div-gpt-mob-adhesive-banner-fixed on the page, you also need to include a container div and some CSS for positioning.

Refresh

KARMA has two mechanisms for refreshing the ads on page: user-initiated refresh and timed refresh.

User-initiated refresh

Triggered by site code when the user takes an action, such as navigating through a slideshow. Uses the karma.refresh method.

Timed refresh

Every page has a set of slot types that are configured in the KARMA Config layer to automatically refresh after they've been in view for a certain amount of time.

The refresh timers on each slot pause when the ad scrolls out of view and resume when the ad re-enters the viewport.

A configured slot must meet the following criteria to for timed refresh to trigger:

• 100% of pixels are in the active window (clicking into the developer console will make the window inactive)
• Each of the 4 corners of the ad creative are not covered by any visible HTML elements (e.g. overlays, floating menus)
• The slot must be in view for at least the length of time specified in karma.config.refresh.timed.intervals.refresh (the timer will pause when the ad is out of view, and resume when the ad is back in view)

• The slot must meet one of the following criteria

  • The slot's tier is set as unrestricted (karma.config.refresh.timed.unrestrictedTiers)
  • The slot's advertiser is not on the blacklist (karma.config.refresh.timed.advertiserBlacklist)
  • The returned creative is AdX

You can inspect the timed refresh configuration on any given page by looking at the config tab of the KARMA bookmarklet or by inspecting window.karma.config.refresh.timed in your browser console.

Slot swap

A neat feature of timed refresh is the ability to automatically swap the current slot to a different tier or slot type after the ad has been in view for a certain amount of time.

This is basically a prepackaged combination of the destroySlot and createSlot.

The swap interval is separate from the timed refresh interval. You can inspect the swap interval by looking at window.karma.config.refresh.timed.intervals.swap.

For instance: on most Meredith sites, the tier 1 mobile adhesive banner is configured to swap to a tier 3 mobile adhesive banner after 15 seconds in view.

Refresh Use Cases

Example KARMA Pages

These are standalone pages that have nothing but KARMA on them.

Production Environment

• http://karma.mdpcdn.com/files/docs/examples/desktop.html?adTestSite=bhg.mdp.com
• http://karma.mdpcdn.com/files/docs/examples/mobile.html?adTestSite=bhg.mdp.com

Troubleshooting

What to do when you suspect an ad is misbehaving:

• Use the KARMA bookmarklet to see what ads have been requested/returned to the page. Take a screenshot of your screen with the bookmarklet active. Send an email to adsupport@meredith.com with the screenshot and the URL of the page you saw the problem on.

  • If your problem is an issue with bad ad creative, the Ad Product team will contact the campaign manager and/or ad agency to correct the problem.
  • If we determine that your problem has to do with a bug in KARMA itself, the Ad Product team will create a support ticket with the KARMA developers to address the issue.

How to Debug Krux SuperTags

Krux SuperTags is a tag management platform that is included by karma.js. It determines what tags to deliver to your page by looking at your domain name to determine what site you’re on. (If you have a non-standard domain for local/staging purposes, you may not be able to use SuperTags in those environments.)

To verify if SuperTags is being loaded/inspect SuperTags code being delivered, run this in your browser console: document.querySelector('.kxhead')

If it returns null, SuperTags is not being loaded. Otherwise, it should return an object that contains all the JS tags being delivered by SuperTags to your page. You can open each tag individually to inspect the code.

If you see a problem with SuperTags code delivery, contact the KARMA dev team at adsupport@meredith.com.

KARMA Bookmarklet

The handy-dandy KARMA bookmarklet:

• Lets you inspect site and page-level KARMA configuration properties.
• Tells you what ad slots have been requested, as well as which ads have been returned. This is helpful in identifying and reporting. problematic ad creative.
• Lets you report problematic ads via email with one click.
• Tells you what page and slot targeting values we have requested from GAM. This is helpful when identifying issues with on-page code.
• Tells you what page and slot-level configurations are set up for timed refresh, docking, etc.
• Gives you a handy interface for appending URL params onto your URL for testing/debugging purposes.

Installing the KARMA Bookmarklet

The KARMA bookmarklet is accessible here: http://karma.mdpcdn.com/files/tools/bookmarklets

Simply drag it to your bookmarks bar and click it on any Meredith page with ads. The bookmarklet is compatible with Chrome (desktop and mobile), Firefox, Safari (desktop and mobile), Edge, and Internet Explorer.

Slots Tab

This tab lists out all the ad slots on the page, as well as identifying information for any ads returned, and any slot-level configuration properties. The slots will also be highlighted and outlined in red on the page itself.

The most important feature on this tab is a Create an email report button that lets you easily send an email to adsupport@meredith.com with any problems you might see. We also recommend that you include a screenshot with your email.

Config Tab

This tab lists page-level KARMA configurations, including leaderboard docking, right rail docking, and timed refresh information. It will also tell you if KARMA is not integrated or not ready.

Targeting Tab

This tab lists out all page and slot-level targeting information, pulled directly from GAM.

Note: You can use this tab on any site with GAM, not just KARMA sites.

Debug Tab

This tab includes a handy form for appending KARMA URL parameters to your URL for debugging purposes. Simply select the params you want and click the Reload Page with Params. Note that this will trigger a full page refresh, so you may lose reference to any problematic ad creatives.

Debug API Methods

karma.debug

Turn on verbose console logging, expose the window.karmads variable to the global scope, and dump the KARMA log to the console. This functionality can also be turned on via the karmaDebug=true URL parameter.

Note: this should NOT be included in regular site code. It's intended for developer debugging in the console only. If you have the KARMA bookmarklet or the KARMA testing bookmarklet up, this method has already been called (though there's no harm in calling it multiple times).

This existed in KARMA 2.x as: adService.performance.showLog(), adService.performance.exposeKarma()

URL Params

KARMA offers many URL params to help with testing and debugging.

You can also use the debug tab on the KARMA Bookmarklet to add these params if you hate typing.

MDP Debug Creative

Replaces normal ad creative with debug creative. Use this to rule out or identify ad creative as the source of a problem

karmaDebug

Enable verbose KARMA debugging in the console (KARMA logs will show up in green) and automatically load the KARMA Bookmarklet. If you forgot to put the karmaDebug URL parameter at the end of your URL, and you still need to see the KARMA logs, you can run this in your browser console instead: window.karma.debug()

adTestEnv

If you are inside the Meredith network and/or have access to our dev and test environments, you can preview upcoming KARMA changes on our staging environment using the adTestEnv URL parameter. (Accepted values are local, dev, test, and www.) This will pull in the version of KARMA service on the specified environment, as well as the version of the KARMA config deployed to that environment. Useful if you’re working on changes that correspond to a KARMA release that is not yet in production.

adTestSite

Override the karma.config.site value. This can be useful if you are testing on a page that doesn't match the main site's url.

ref_hub

Adds a page targeting key/value pair of ref_hub that overrides anything set in the KARMA config.

psrc/ordersrc/esrc

If any of these are present in the URL query string, a page-level targeting key-value pair of 'urlSrc' is set that matches either psrc, ordersrc, or esrc.

Product Demos (advertest)

While any key-value pair can be passed through adTestKeyValues, we often use it to force certain ad creative. Here are a list of known advertest values (these change often, so check with Ad Product if one doesn't work).

Force specific products where possible.

Vendor Tests (advertest)

While any key-value pair can be passed through adTestKeyValues, we often use it to force certain ad creative. Here are a list of known advertest values (these change often, so check with Ad Product if one doesn't work).

Force specific vendors to win a bid auction where possible.

Glossary

Ad Service

Also known as KARMA (see below).

ATG

A legacy Java-based e-commerce platform, owned by Oracle, that powers a few legacy Interwoven-driven sites. ATG also houses CRT and subscription/registration pages.

Celtra

A vendor/platform for building rich media ads for mobile (sort of like Flash is used for desktop).

Click-through rate

The percentage of ads that get clicked on.

CM

Campaign Manager.

CSM

Client Services Manager

CPC

Cost per click.

CPM

Cost per million impressions.

CRT

Consumer Revenue Transformation. Our internal term for the team/pages that process our online magazine subscriptions/renewals.

DART

The old ad framework provided by Google that we used to use to serve desktop ads.

GAM

Doubleclick for Publishers. The software that our ad operations team uses to manage the ads that get served into the GPT ad tags.

GAM Terminology

• Ad Slot
  Defined in Operative as platform+locator+size. Each size that can deliver to a set of Ad Units has to be individually set up

• Ad Unit
  The name and code (within GAM) that is defined by KARMA (example: bhg.mdp.com/tier1/article/gardening)

• Drop ID
  Sales system numerical unique identifier (currently FT)

• Line Items
  Individual products that are listed in GAM with the flight dates and associated size, key value, or geo targeting

• Locator (Loc)
  The Ad Unit or GAM placement defined in Operative. Loc1 = ad unit, Loc2 = placement

• Order
  A grouping of line items that comprise a purchased campaign

• Package
  A grouping of products. Products in packages can be "Visible to the CSM; not pushed to GAM", "Visible to the CSM; pushed to GAM" or "Not visible to the CSM; pushed to GAM"

• Placement
  CSM usage: The product that is put on the plan. Corresponds (usually) to a Site + Size
  CM/Ad Tec usage: A grouping of ad units in GAM

• Product
  The item that CSMs would book on an order, can be made up of multiple Ad Slots

• Push (aka Traffic)
  The action of taking a line item and approving it, setting it so that it shows up in the production ad server.

Docking banners or rails

Ads that stay fixed to a certain spot on the user's screen as they scroll. Helps viewability.

Double Verify (DV)

Blocking and viewability technology. Some agencies wrap their ad creative with it.

Drupal

A PHP/MySQL-based CMS that powers many of our sites.

First Look

Google's Header Bidding product

FlashTalking (FT)

Blocking and viewability technology. Some agencies wrap their ad creative with it.

Gateway Direct (GWD)

A third-party ad vendor that serves ads on both desktop and mobile. This is one of the third parties that can take over an ad slot, preventing GAM ads from showing.

GPT

Google Publisher Tags. The ad framework provided by Google that we use currently to serve desktop and mobile ads.

Hover/Adhesive Banner

A mobile ad unit that sticks to the bottom of the user's screen as they scroll.

Instant ad slots

Slots that are included in the HTML markup and requested instantly as the page loads.

Interstitial Ad

An ad that serves into an overlay that covers the site. Usually we use the term "interstitial" to refer to mobile overlays and "interrupter" or "roadblock" to refer to desktop overlays.

Interwoven

An XML-based CMS that's used on many of our legacy sites. Integrates with Java well, hence why we used it with ATG-driven sites.

KARMA

The Meredith-developed and maintained wrapper for GPT.

Kargo

Third-party vendor that sells and serves ads for mobile. We currently serve Kargo tags through GPT.

Krux

Third-party integration that keeps track of user information and passes that information to GPT to serve ads targeted to that user's demographic. Krux also provides us with a tag manager called Krux Supertag, which we use to load many of our third-party integrations.

Lazy Load ad slots (also called Infinite Scroll ad slots)

Slots that are dynamically created/injected into the page based on a user interaction (scrolling down the page, for instance). This is in contrast to slots that are in the markup when the page loads initially.

Lazy Scroll slots (also called Scroll Load)

Slots that are included in the HTML markup (like instant slots) but are not requested until the user scrolls to where the slot is a certain distance from the viewport. See Lazy Scroll Slots for implementation details.

Media.net/MediaNet

A third-party provider that serves ad content on desktop and mobile as well as recommended content on the page. This is one of the third parties that can take over an ad slot, preventing GAM ads from showing.

MOAT

A third-party vendor that provides us with viewability statistics on our ads. It tracks this via tracking pixels that are inserted onto the page as the user interacts with the page.

Monetate

A third-party provider that serves in-house ads (targeters) as well as registration interrupters/roadblocks.

Native Advertising

Advertising that takes the form of sponsored content on our websites. Native advertising usually does not look like an ad. Instead, it mimics the look and feel of content. Selectable Media is one of our providers for this.

NTENT (formerly VSW)

A third-party ad vendor that serves into the ancillary slot, often with the header 'More Smart Savings'.

Operative

Our future new order management system. It replaces part of Salesforce, all of FatTail, and part or all of RevStream.

Outbrain

A third-party vendor that provides recommended content on the page, often with the header 'You Might Also Like'.

Pre-roll advertising

Video ads that runs before video content.ha

Pubmatic (PMP/UOE)

A third-party ad vendor that serves ads on both desktop and mobile. This is one of the third parties that can take over an ad slot, preventing GAM ads from showing.

Reg overlay

Usually refers to a login/reg screen in an iframe that's centered inside of an overlay that cover's the user's screen. Not to be confused with a roadblock or interstitial ad.

Remnant

Usually refers to below-the-fold ads that are run-of-network, low-yield. Usually served through AdEx.

Run-of-network

Ads that run across the entire network of sites.

Roadblock (aka Interrupter)

An overlay that covers the user's browser window and serves an invitation to register. When logged in, the roadblock does not appear. Not to be confused with a reg overlay or an interstital ad.

Rubicon

A third-party ad vendor; potential replacement for Pubmatic.

Selectable Media

A Meredith-owned vendor that serves native advertising as well as registration interrupters (called 'content unlock'). Selectable unlocks usually give the user a choice of creating an account or watching a video to continue to the content underneath the overlay.

Site Skin

A mobile-specific ad product (originally from Kargo, now served directly through GAM) that takes over the header of a mobile site, often changing the color of the logo and any navigation buttons in the header.

SolveMedia

A third-party ad-based captcha that asks users to watch a video, then type a word into the box. Gradually being phased out in favor of Selectable Media interrupters.

Sonobi

A third-party ad vendor that serves ads on both desktop and mobile. This is one of the third parties that can take over an ad slot, preventing GAM ads from showing.

Spoutable

An 'exit ad' that appears when the user attempts to leave one of our sites.

SuperTags

A tag manager provided by Krux, which we use to load many of our third-party integrations.

Targeters

Also referred to as teasers (on CQ). Essentially, these are house ads, targeted to users based on their registration status. Many (if not all) of these are served through Monetate.

TripleLift

Native Ad exchange. We serve their creative through Selectable Media's platform as backfill.

Viewability

Usually refers to the percentage of our ads that are visible to the user for at least 1 second. Moat is the tool we currently use to track this.

Wallpaper ads

Desktop ads that cover the background of a site, filling up the blank space that surrounds the site content well. These are served via a GAM template.

Welcome Ad

Full-screen overlay ad that displays a 'tip of the day' and an ad, as well as a 'Continue to Site' link.

Yieldbot

A third-party ad vendor that serves ads on both desktop and mobile. This is one of the third parties that can take over an ad slot, preventing GAM ads from showing. Yieldbot also serves the bar that loads at the bottom of some websites, with links to trending content on those sites. This is referred to internally as "Yieldbar". More Info: Yieldbot

YieldMo

A third-party vendor that serves in-stream ads on mobile and tablet. No related to Yieldbot.

Yieldstack

A Meredith-specific term to refer to a series of ad products sorted by how much revenue they yield. No relation to Yieldbot (except that Yieldbot can be included in the Yieldstack).