Tracking Beacons

Abstract

Describes the tracking beacons used by the Yahoo Ad Tech Recommends client.

Overview

Tracking beacons are used by the Recommends client through a series of example requests, as described below.

Example Request 1 - Client Loaded From a Script Tag

To begin, the Recommends client is loaded from a script tag embedded in the publisher page as shown below.

<script type="text/javascript">
(window.readmo = window.readmo || []).push({
  section: '12345',
  container: '#readmo-12345'
});

!(function(d){
  var script = d.createElement("script");
  script.async = true;
  script.src = 'https://s.yimg.com/dy/ads/readmo.js';
  d.body.appendChild(script);
})(document);
</script>

The Recommends client now renders the module into an element on the publisher page referred to by the container property of the script tag.

<div id="readmo-12345"></div>

Example Request 2 - Client Contacts the Gateway

Once the Recommends client script loads, it contacts the Recommends gateway with the parameters specified in the script tag.

This request is shown in the screenshot below, using Chrome developer tools. The gateway request to readmo.yahoo.com is highlighted in the network tab.

gateway request tab

Example Request 3 - Client Starts Rapid Instrumentation

After parsing the response from the Recommends gateway, the client starts a second JavaScript component known as rapid, which is used for tracking user behavior. The rapid client is active throughout the entire time the page is loaded.

Rapid works by buffering the instrumentation it collects about the user behavior on the page and periodically sending that back to the Yahoo Ad Tech cloud.

A request from the rapid instrumentation component to 3p-udc.yahoo.com is depicted in the screenshot below, as shown using Chrome developer tools.

start javascript

Important

We provide information about rapid, so that you’re aware of the instrumentation and the association of rapid with Yahoo Ad Tech Recommends. We don’t, however, provide documentation about the format.

The relationship between Recommends event beacons and pages or modules is described in

See Appendix: Events and Page-Module Relationships for the supported types of event beacons and a diagram of the relationship between Recommends event beacons and pages or modules.

The readmo_page_view Beacon

In this example, the beacon fires when the recommendations within the modules are loaded.

https://3p-geo.yahoo.com/p?s=1197809846&t=1HwcVloQVrNVFfLK,0.9348572346597235&_I=&_AO=0&_NOL=0&_R=&_P=3.53.19%05_pl%031%04A_v%033.53.19%04A_cn%03EVERGREEN-PROD%04_bt%03rapid%04A_pr%03file%04A_tzoff%03-7%04A_sid%032zwh1poSWmDmDHE2%04_w%03file%3A%2F%2F%2FUsers%2Fmmorais%2Ftmp%2Fpage-24acd6b52057400a944962c055cf5916.html%04site%03foxnews.com%04reqid%03e37488fa-44b3-4709-9a1b-234159514128%04pubid%031912324%04test%03%04test_id%03%04ver%03standard%04readmo%03true%04pageid%0324acd6b52057400a944962c055cf5916%04pageviewid%03083d9316-a858-4e0a-94e6-7a920357a6d3%04_E%03simple%04outcm%03readmo_page_view%04_ts%031593627342%04_ms%03722%04A_sr%031920x1080%04A_vr%031920x1057%04A_do%031%04A_ib%03955x230%04A_ob%03955x1043%04A_srr%031

The readmo_mod_load Beacon

In this example, the beacon fires when the recommendations within the modules are loaded.

https://3p-geo.yahoo.com/p?s=1197809846&t=0ooP80qRd1ADJUaC,0.9018686174728532&_I=&_AO=0&_NOL=0&_R=&_P=3.53.19%05_pl%031%04A_v%033.53.19%04A_cn%03EVERGREEN-PROD%04_bt%03rapid%04A_pr%03file%04A_tzoff%03-7%04A_sid%032zwh1poSWmDmDHE2%04_w%03file%3A%2F%2F%2FUsers%2Fmmorais%2Ftmp%2Fpage-24acd6b52057400a944962c055cf5916.html%04site%03foxnews.com%04reqid%03e37488fa-44b3-4709-9a1b-234159514128%04pubid%031912324%04test%03%04test_id%03%04ver%03standard%04readmo%03true%04nsite%030%04nsponsored%032%04pageid%0324acd6b52057400a944962c055cf5916%04subsec%03ea788f8c9f26409aa7f7c759f54189b1%04_E%03simple%04outcm%03readmo_mod_load%04_ts%031593627342%04_ms%03725%04A_sr%031920x1080%04A_vr%031920x1057%04A_do%031%04A_ib%03955x230%04A_ob%03955x1043%04A_srr%031

The readmo_mod_view Beacon

The beacon fires when 1% of the module comes into view.

https://3p-geo.yahoo.com/p?s=1197809846&t=sEXuJ4KxjEaKN5dp,0.05361777446253413&_I=&_AO=0&_NOL=0&_R=&_P=3.53.19%05_pl%031%04A_v%033.53.19%04A_cn%03EVERGREEN-PROD%04_bt%03rapid%04A_pr%03file%04A_tzoff%03-7%04A_sid%03U5ilBS00cD0zMNnR%04_w%03file%3A%2F%2F%2FUsers%2Fmmorais%2Ftmp%2Fpage-24acd6b52057400a944962c055cf5916.html%04site%03foxnews.com%04reqid%0352abbaf2-e8f0-484b-9e95-6001e831c041%04pubid%031912324%04test%03%04test_id%03%04ver%03standard%04readmo%03true%04nsite%036%04nsponsored%030%04pageid%0324acd6b52057400a944962c055cf5916%04subsec%03bb38c1bff07b4db0a02c0ae22732d16f%04_E%03simple%04outcm%03readmo_mod_

In addition to rapid events, under some circumstances a cookie sync beacon https://geo.yahoo.com/b?… will fire from the Recommends module. Note that the cookie sync endpoint still goes to geo.yahoo.com and not 3p-geo.yahoo.com).

Example Request 4 - Client Fires View Beacon

Each sponsored recommendation in the returned rads array has associated beacons. The beacons will fire based on rules that are included with the ad.

The format of the rule depends on the type of ad and is described in Appendix: Events and Page-Module Relationships in the section that discusses video tracking.

An example rule for an image ad is shown below in the fragment from the gateway response.

$ jq '.rads[0].rules' readmo-67837bdbc5574142b2de717017aca950-response.json
{
  "viewabilityDefStatic": {
    "c": 1,
    "d": 1,
    "p": 50
  },
  "viewabilityDefStatic3P": [
    {
      "c": 1,
      "d": 1,
      "p": 100,
      "t": 3
    }
  ]
}

The view beacon url is also included in the gateway response. An example is shown below in the fragment from the gateway response.

See Appendix: List of Beacon Url Mnemonics to understand the meaning of the mnemonics associated with each url.

$ jq '.rads[0].actionUrls' readmo-67837bdbc5574142b2de717017aca950-response.json
{
  "STATIC_VIEW_3P": [
    "https://beap.gemini.yahoo.com/action?bv=1.0.0&es=C5Xbue0GIS.gGjQ6VO25XVVIfZo_tW.1c2QghYb5RBFOum84CvPGigFoy0ZJ1Ja4QauMmBi_9fTrEsYLZ9EMd.foJc1xQCBDkZRiifqYYPHb8iwSFzwX2ghMn2WrPE0XZIMxs.fqmraEeiIbGHd6yywZwP2Z_ZxrprWAimJJI4UvfBxgdRf1lU9ze9RfPoHoOUpUrss5z05TAVFtRIfHqgDhx0yKkW8IXDsuZdSU5rV42sgJB8esjt288cwYabCHocyaax1yEtFtAWu7g7RnMMKOcyEtuSjlaq5o0JhIqtkfmMhf7ONZt01FtzIBN9i6vh.3zDSlsG4.W3256zBK8ILZIK72M2toYawXUKH5wkllJnVvRzs8B0k.j.KNZA--&vt=$(S_VIEW_TYPE)"
  ]
}

Example Request 5 - Client Fires a Click Beacon

The click beacon url is included in the gateway response. An example is shown below in the fragment from the gateway response

$ jq '.rads[0].tag.clickUrl' readmo-67837bdbc5574142b2de717017aca950-response.json
"https://beap.gemini.yahoo.com/mbclk?bv=1.0.0&es=bDTE.rAGIS_oUPmaBpV7eag8dtXv63q8GWJHh0HvZbWF5B4CNWsPPMrSvB6IghifAqoxUB0E2nW3HiAP1q4x9PbmlzthB1I_t8m14l6ELxnsup8zwv4cYjGnTpSqGGhFhDaP8.6Ca4hTx47kNpHYnXqtsuyBtyQ3n1GwWnhfgS7OecMJs.HYlflqJ9vLOdbexKWy5EZjlxbBm3nZuEQZbml4bSlHfgQbJfixB65O.b55obhzkOIJ37po6_VmLsPAfhQvlfyfGDtOxq6SduvNmCR8UCJfkhekWBDv9loBalt4w0sWiUCdo.ZYrTwN315enzp7yT0sLdf.Y6MQGLlrGkumyyn57fHhx3KJ7aOdxfQnR6L5hW8MeZiXCD2kRomLIG5wCSe.gt1YWxv7Pd_0LEDN2JWDBP.FWwWBTYFtaTiYCf_lrojwSw8ivjjN9EeLyImYaI_n2IZT2a22GiCmYberPRl2MDjhY_EFSCvmmc.sa.SD_cDOZSNAaMF6OEZKCzBO5Mr_SP0Q.4qXahbQ0Q_50Q5bpVRPs0cu83ovzl_R6db4MK0xqWP5vVNvDIO_Td4rPj4Q_s9DVi8oTeTu3Vu_l64uL9JzDhxcMBf8YcPGmWxZTiDQ4a1UHLAoUfIh7zY0mE6j8D3ZU.CsACgmxVwdNMD8e6uxR7SdrDiyWFRGlOvi0QRGa74Dv3C_uQJRomM74YqVGsn88_JUJCENF60JERl3dLlqsCC7QHW03WjglanhuoUlB2wZZE7liVjk.jMhlF1SaKheJojj5wObxd6VGDenx91GGw