Manually Logging Ad Metrics with JavaScript

If you’re serving ads in a custom way—outside of standard MediaOS placements—you can manually log impressions, clicks, and hovers using JavaScript. This allows you to accurately track ad engagement, even when you’re using custom rendering or interaction models.

When to Use Manual Tracking #

While MediaOS offers automated tracking through its standard ad-serving templates, there are specific conditions where manually tracking ads provides greater flexibility and control. In these key situations, manual tracking is particularly useful:

1. Dynamically Rendered Ads Outside MediaOS Templates
   • When advertisements are created or rendered outside of the standard MediaOS-managed templates—such as through custom HTML or server-side rendering—automated tracking may not be applied by default. In these cases, developers must implement manual tracking functions to ensure accurate logging of impressions, clicks, and other interactions.
2. Use of JavaScript Frameworks
   • Many modern applications rely on JavaScript frameworks such as React, Vue, or Angular to build interactive user interfaces. Ads embedded within these environments often bypass conventional DOM-based ad insertion methods. As a result, developers must explicitly call MediaOS tracking functions to ensure that ad interactions are properly recorded within the dynamic component lifecycle.
3. Capturing Hover Behavior for Interactive Creatives
   • For campaigns that utilize interactive or animated ad creatives, understanding user engagement beyond just clicks can be critical. Manual tracking allows developers to log hover events, providing insight into how long or how frequently users engage visually with the creative content without necessarily clicking. This data can be valuable for measuring attention and interaction levels.
4. Integration with Third-Party Tools
   • In complex advertising setups involving third-party platforms or analytics tools, it may be necessary to synchronize tracking events between systems. Manual tracking enables developers to trigger MediaOS logging functions in tandem with external tracking mechanisms, ensuring consistent data collection across all platforms.

JavaScript Methods #

MediaOS provides three JavaScript methods for logging ad activity:

Impressions #

MediaOS.AdServerImpression(lineItemID, adID)

This function is triggered to log an impression whenever an advertisement becomes viewable to a user on the webpage. In most cases, "viewable" means that a significant portion of the ad (typically 50% or more) is visible within the user's browser viewport for at least one second. By capturing this event, the ad server can accurately track how many times an ad has actually had the potential to be seen by users, as opposed to simply being loaded on the page.

Clicks #

MediaOS.AdServerClick(lineItemID, adID)

This function records a click event when a user actively clicks on an advertisement. It captures the interaction between the user and the ad content, which can then be used for measuring engagement, evaluating ad performance, and billing in cost-per-click (CPC) campaigns. The lineItemID and adID parameters help attribute the click to the correct ad campaign and creative.

Hovers #

MediaOS.AdServerHover(lineItemID, adID)

This function is used to log a hover event, which occurs when a user moves their mouse pointer over the ad, even if they don't click on it. Tracking hover events can provide additional insight into user interest and engagement. It helps advertisers understand if users are pausing to look at an ad (even without clicking), which may inform future creative decisions or adjustments to targeting strategies.

Method Parameters #

All three methods require the same two parameters:

These IDs can be retrieved from your MediaOS proposal or campaign setup.

Examples #

Manual tracking within MediaOS gives you the flexibility to capture ad interactions in non-standard environments. Whether you are integrating with a frontend framework, syncing with third-party analytics, or tracking additional engagement signals like hovers, these examples demonstrate how to implement manual tracking using MediaOS's core tracking functions.

Example 1: Logging an Impression #

When an ad is rendered manually—outside the default MediaOS template system—you need to explicitly track the moment the ad becomes visible to the user. This is typically done when the ad finishes rendering or enters the user’s viewport:

MediaOS.AdServerImpression(12345, 67890);

This call registers an impression for the specific ad creative and line item. However, triggering this function too early (e.g., on load) may result in logging an impression before the user can actually see the ad. Use an intersection observer or similar technique to delay this call until the ad actually appears on screen.

Warning: Avoid logging impressions too early (e.g., before the ad is visible). This can distort reporting and lower ad quality scores.

Example 2: Logging a Click #

Click tracking must be implemented manually when ads are embedded as custom HTML or are part of a dynamic frontend application. You can wrap the ad element in an anchor tag and trigger the MediaOS.AdServerClick function in an onclick event:

<a href="https://advertiser.com" onclick="MediaOS.AdServerClick(12345, 67890)">
  <img src="ad-banner.jpg" alt="Ad Banner">
</a>

This function logs the click event, helping advertisers measure direct engagement and performance metrics such as click-through rate (CTR).

Note: Be sure to track the click before the link redirects by using inline JavaScript or event delegation.

Example 3: Logging a Hover #

Hover tracking can be useful for interactive or animated creatives, where user interest may be expressed through visual engagement rather than a direct click. You can use the onmouseover attribute to detect when a user’s mouse pointer moves over the ad:

<div onmouseover="MediaOS.AdServerHover(12345, 67890)">
  <img src="ad-banner.jpg" alt="Ad Banner">
</div>

This call logs the hover interaction, which is especially valuable for rich media ads that respond to hover behavior (e.g., expanding panels, animations, tooltips).

Tip: This is useful for interactive banners or ads where hover state indicates engagement.

Best Practices #

• For single-page apps, make sure tracking is triggered on route/view changes if ads are rendered dynamically.
• Always check that the MediaOS object is available before calling the functions:

if (typeof MediaOS !== 'undefined' && MediaOS.AdServerImpression) {
  MediaOS.AdServerImpression(12345, 67890);
}

Related Articles #

• Ad Server Overview
• Selling Targeted Ads
• Including Ad Stats on Invoices