Install the pixel in any stack

1. Configuration attributes

<script
  async
  src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
  data-fxmd-meter-mode="exposure"
  data-fxmd-attribution-mode="inject"></script>

The shorter forms data-meter-mode and data-attribution-mode are also accepted, for platforms whose tag editors strip vendor prefixes.

What it sends

A page_view on load and on each route change, a module_view when a tagged component becomes visible, one heartbeat 15 seconds in, and an attribution_click if someone clicks your credit link. Each carries an anonymous visitor id, the path, the viewport, timezone and language, and whether the attribution element was visible. Transport is navigator.sendBeacon with a fetch fallback, so it never blocks rendering and never fails loudly. No personal data, no cross-site identifier, and nothing about the individual beyond a random id your browser stores.

2. Which domains to register

• Apex and www are one entry. Registering https://example.com also accepts https://www.example.com, and the reverse.
• Every other subdomain is its own entry. app.example.com, portal.example.com, and dashboard.example.com each need registering. Adding a domain never adds a licence fee.
• The scheme and port matter. Register the origin you actually serve. A non-standard port is part of the origin.
• Register staging too if you want to test there, or accept that staging events are rejected. Rejected events are not billed, so an unregistered staging site is harmless, just invisible.
• Localhost is not registerable. Verify on a deployed origin.

The site identity in your reporting is the hostname the page was served from, so a single licence covering five subdomains still shows you five rows and one combined billable total.

3. Page mode vs exposure mode

There is a safety net: if an exposure-mode site records no tagged component views at all in a period, billing falls back to counting its human page views, so an untagged site is never silently metered at zero. It is a backstop, not a plan. Once you tag correctly the fallback stops applying and your marketing-page visitors go back to being uncounted, which is the whole point of choosing exposure mode.

4. Tagging the data components

Put both attributes on the outermost element of each FXMacroData-powered component. The pixel watches it with an IntersectionObserver and reports the first time at least 10% of it enters the viewport, once per route.

<section data-fxmd-metered data-fxmd-module="release-calendar">
  <!-- your rendering of the FXMacroData calendar -->
</section>

<div data-fxmd-metered data-fxmd-module="usd-cpi-chart">...</div>
<aside data-fxmd-metered data-fxmd-module="rate-differentials">...</aside>

• Both attributes are required. data-fxmd-module alone names a component in the page payload but does not meter it; data-fxmd-metered is what arms the observer.
• Module names are lowercase, up to 64 characters, from a-z 0-9 _ . : -. Anything else is dropped silently, which looks exactly like nothing happening. Keep them stable: they are how you read your own usage later.
• Content added later is picked up. A MutationObserver rescans on DOM changes and on class, style, hidden, and aria-hidden changes, so tabs, accordions, modals, and lazy-loaded panels all work without extra code.
• Up to 16 module names are collected per event. Tag components, not every row in a table.

5. The JavaScript API

When a component is drawn to a canvas, rendered inside a web component, or only exists after a user action, tag it in code instead.

// Report a module view explicitly.
window.FXMacroDataPixel.trackModule("release-calendar");

// Options: dedupe defaults to true (once per module per route).
window.FXMacroDataPixel.trackModule("usd-cpi-chart", {
  dedupe: false,
  source: "chart-render",
  element_label: "USD CPI, 12m",
});

// Read the current anonymous context, e.g. for your own debugging.
window.FXMacroDataPixel.getContext();
// { anonymous_visitor_id, anonymous_session_id, site_id, meter_mode, meter_version }

The script is loaded async, so it may not have booted when your code runs. Use the queue and nothing is lost:

window.FXMacroDataPixel = window.FXMacroDataPixel || { q: [] };
window.FXMacroDataPixel.q.push(["trackModule", "release-calendar"]);

Queued commands run as soon as the pixel initialises, and the same q.push form keeps working afterwards.

6. The attribution link

The licence requires visible FXMacroData credit wherever the data appears. Mark your own element and the pixel confirms it is present, on screen, and not hidden by CSS.

<a href="https://fxmacrodata.com/?utm_source=example.com&utm_medium=partner"
   data-fxmd-attribution>Data powered by FXMacroData</a>

The pixel reports the element position, size, text, and whether it was visible in the viewport at the time of the event. It never moves or restyles your element. Set data-fxmd-attribution-mode="inject" only if you would rather we add a small fixed badge for you; a real credit inside your own layout is better for both sides.

7. Single-page frameworks

Route changes are handled for you. The pixel wraps history.pushState and history.replaceState and listens for popstate and hashchange, so every client-side navigation produces a fresh page view and rescans for tagged components. You do not need a router hook. Load the script once in the shell, choose exposure mode, and tag.

<!-- before </body>, on pages that display FXMacroData content -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>

<!-- index.html -->
<script
  async
  src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
  data-fxmd-meter-mode="exposure"></script>

// ReleaseCalendar.tsx
export function ReleaseCalendar({ events }) {
  return (
    <section data-fxmd-metered data-fxmd-module="release-calendar">
      {events.map((e) => <EventRow key={e.id} event={e} />)}
    </section>
  );
}

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
          strategy="afterInteractive"
          data-fxmd-meter-mode="exposure"
        />
      </body>
    </html>
  );
}

// pages/_document.tsx
<Head>
  <script
    async
    src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
    data-fxmd-meter-mode="exposure"
  />
</Head>

<!-- index.html -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

<!-- ReleaseCalendar.vue -->
<template>
  <section data-fxmd-metered data-fxmd-module="release-calendar">
    <EventRow v-for="e in events" :key="e.id" :event="e" />
  </section>
</template>

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [{
        src: "https://fxmacrodata.com/static/js/fxmacrodata-pixel.js",
        async: true,
        "data-fxmd-meter-mode": "exposure",
      }],
    },
  },
});

<!-- src/index.html, before </body> -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

<!-- release-calendar.component.html -->
<section data-fxmd-metered data-fxmd-module="release-calendar">
  <app-event-row *ngFor="let e of events" [event]="e"></app-event-row>
</section>

<!-- src/app.html, inside %sveltekit.body% wrapper -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

---
// src/layouts/Base.astro
---
<slot />
<script is:inline async
        src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

// app/root.tsx
<body>
  <Outlet />
  <script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
          data-fxmd-meter-mode="exposure" />
  <Scripts />
</body>

// gatsby-ssr.js
export const onRenderBody = ({ setPostBodyComponents }) => {
  setPostBodyComponents([
    <script key="fxmd" async
      src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
      data-fxmd-meter-mode="exposure" />,
  ]);
};

<!-- Same tag in the shell HTML. Anything that navigates through the
     History API or replaces DOM in place is already handled. -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

8. Server-rendered frameworks

With classic server rendering you have a real choice: put the tag in a partial included only by the templates that show FXMacroData content and stay in page mode, or put it in the base layout and switch to exposure mode. The first is simpler and usually more accurate.

{# templates/partials/fxmd_pixel.html #}
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>

{# templates/markets/calendar.html #}
{% include "partials/fxmd_pixel.html" %}

{# templates/base.html #}
{% block fxmd_pixel %}{% endblock %}

{# templates/calendar.html #}
{% block fxmd_pixel %}
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>
{% endblock %}

<%# app/views/layouts/application.html.erb %>
<%= yield :fxmd_pixel %>

<%# app/views/markets/calendar.html.erb %>
<% content_for :fxmd_pixel do %>
  <script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>
<% end %>

{{-- resources/views/layouts/app.blade.php --}}
@stack('fxmd')

{{-- resources/views/markets/calendar.blade.php --}}
@push('fxmd')
  <script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>
@endpush

@* Views/Shared/_Layout.cshtml *@
@await RenderSectionAsync("FxmdPixel", required: false)

@* Views/Markets/Calendar.cshtml *@
@section FxmdPixel {
  <script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>
}

<!-- templates/fragments/fxmd.html -->
<script th:fragment="pixel" async
        src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>

<!-- templates/calendar.html -->
<div th:replace="fragments/fxmd :: pixel"></div>

<%- include('partials/fxmd-pixel') %>      <!-- EJS -->
{{> fxmd-pixel}}                            <!-- Handlebars -->
script(async, src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js")  //- Pug

<?php if ($page_shows_fxmd_data): ?>
  <script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>
<?php endif; ?>

9. CMS and no-code platforms

Most hosted platforms give you a custom-code box for the site head or footer. Paste the tag there, then decide the mode: site-wide box plus exposure mode plus tagging, or a page-level box on just the data pages plus page mode.

// functions.php in a child theme
add_action('wp_footer', function () {
    if (!is_page(['market-calendar', 'rates'])) return;   // data pages only
    echo '<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>';
});

<!-- Any header/footer scripts plugin, or theme options -> custom code -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

<!-- then wrap the shortcode/block output -->
<div data-fxmd-metered data-fxmd-module="release-calendar">[fxmd_calendar]</div>

<!-- layout/theme.liquid, before </body> -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

Project Settings -> Custom Code -> Footer Code
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

Then on the wrapper element: Settings -> Custom attributes
  data-fxmd-metered  =  (leave blank)
  data-fxmd-module   =  release-calendar

Settings -> Advanced -> Code Injection -> Footer
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

Per page: Page Settings -> Advanced -> Page Header Code Injection

Settings -> Custom Code -> Add Custom Code
  Place in: Body - end
  Load on: All pages, or Choose specific pages
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>

Settings -> Code injection -> Site footer
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"
        data-fxmd-meter-mode="exposure"></script>

// mytheme.theme
function mytheme_page_attachments_alter(array &$attachments) {
  $attachments['#attached']['html_head'][] = [[
    '#tag' => 'script',
    '#attributes' => [
      'src' => 'https://fxmacrodata.com/static/js/fxmacrodata-pixel.js',
      'async' => TRUE,
      'data-fxmd-meter-mode' => 'exposure',
    ],
  ], 'fxmd_pixel'];
}

Site settings -> custom head or footer code -> paste the tag.
Add the two data attributes to the container element in whichever
element-settings panel the platform provides.

10. Static site generators

<!-- layouts/partials/fxmd-pixel.html -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>

<!-- layouts/_default/baseof.html -->
{{ if .Params.fxmd }}{{ partial "fxmd-pixel.html" . }}{{ end }}

<!-- _includes/fxmd-pixel.html -->
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>

<!-- _layouts/default.html -->
{% if page.fxmd %}{% include fxmd-pixel.html %}{% endif %}

<!-- _includes/layouts/base.njk -->
{% if fxmd %}
<script async src="https://fxmacrodata.com/static/js/fxmacrodata-pixel.js"></script>
{% endif %}

// docusaurus.config.js
scripts: [{
  src: "https://fxmacrodata.com/static/js/fxmacrodata-pixel.js",
  async: true,
  "data-fxmd-meter-mode": "exposure",
}]

11. Tag managers

Tag type: Custom HTML
<script>
  var s = document.createElement("script");
  s.async = true;
  s.src = "https://fxmacrodata.com/static/js/fxmacrodata-pixel.js";
  s.setAttribute("data-fxmd-meter-mode", "exposure");
  document.body.appendChild(s);
</script>

Trigger: All Pages (exposure mode), or a Page View trigger
         limited to your data pages (page mode).

// Any "custom JavaScript" destination, loaded once per page:
!function(){
  var s = document.createElement("script");
  s.async = true;
  s.src = "https://fxmacrodata.com/static/js/fxmacrodata-pixel.js";
  s.setAttribute("data-fxmd-meter-mode", "exposure");
  document.body.appendChild(s);
}();

A tag manager adds a layer that can be misconfigured, blocked by consent tooling, or deployed late. If you control the site template, put the tag in the template.

12. CSP, consent, and privacy

Content Security Policy

script-src  'self' https://fxmacrodata.com;
connect-src 'self' https://fxmacrodata.com;

connect-src is the one people forget. Without it the script loads, runs, and every beacon is blocked, so the pixel looks installed and measures nothing. If you use nonces, put the nonce on the script tag; the pixel adds no inline script of its own.

Pinning the script

There is no version-pinned URL and no published integrity hash for the copy on fxmacrodata.com. The file is served with a short cache and is replaced in place whenever the meter is updated, so an integrity attribute pinned against that URL would stop the pixel loading on the next release. If your policy requires a pinned hash, host the file on your own domain unmodified and pin your own: see self-hosting and relaying. Whichever copy runs, it reports its own build on every event as meter_version, so your reporting always shows which version produced a figure.

What it stores on the visitor device

All three are first-party to your domain and meaningless anywhere else. Nothing is read from or written to any other site, there is no cross-site identifier, and no advertising use. If storage is unavailable the pixel falls back to an in-memory id for that page view, which over-counts rather than under-counts.

Consent

This is a licence-compliance meter, not analytics or advertising, and most operators treat it the way they treat any first-party measurement they are contractually obliged to run. Where your counsel decides it needs consent, gate the tag the same way you gate the rest, and understand the trade: an unconsented visitor is not metered, is not billed, and is not visible in your reporting.

Disclose it in your privacy policy the way you disclose other first-party measurement: the cookie name, the retention, and that it counts unique readers for a data licence and nothing else.

Ad blockers and network filtering

Some visitors block third-party scripts by hostname. That under-counts you, which is not a problem for us. If it is a problem for your own reporting, host the file on your own domain and relay the collector through your own server. Both are supported, and both have rules worth reading before you wire them in: see self-hosting and relaying. Do not modify the script itself: a changed meter is not a meter.

13. What the collector validates

Worth reading before you put anything between the browser and the collector, and before you conclude that an event which never appeared was lost in transit.

How an event finds your account

By origin, and only by origin. The collector reads the Origin request header, falls back to the origin field inside the event body when there is no header, and matches the result against the domains registered in API Management. No match means origin is not an approved redistribution domain, and nothing is stored or billed.

Because the address is never checked, events are accepted from wherever you send them, including your own servers. What must always be right is the origin, and it must be one you registered.

How automated traffic is filtered

A public web page is crawled, prefetched, previewed, and scraped by clients you never chose to serve, so every event is classified before anything billable is written. Traffic classed as automated is kept in your reporting and left out of the billable count.

14. Self-hosting and relaying

Two independent changes, both supported. Host the script on your own domain to survive hostname-based blocking and to pin your own integrity hash. Relay the collector through your own server so the browser only ever talks to you. Do one, the other, or both.

Hosting the script yourself

Serve fxmacrodata-pixel.js from your own origin, byte for byte as published. You then own the URL and the hash, so you can version it and pin it however your policy requires, and you decide when to take an update. Do not modify the file: a changed meter is not a meter.

<script
  async
  src="https://example.com/assets/fxmacrodata-pixel.<version>.js"
  integrity="sha384-<your hash of the file you host>"
  crossorigin="anonymous"></script>

A self-hosted copy still sends to https://fxmacrodata.com unless you also relay, so keep connect-src https://fxmacrodata.com in your policy. Check for a newer build when you next review the page; the version each event carries as meter_version tells you what you are running.

Relaying the collector

Point the pixel at your own endpoint and forward each request to the collector from your server.

<script
  async
  src="https://example.com/assets/fxmacrodata-pixel.js"
  data-fxmd-endpoint="https://example.com/fxmd-collect"></script>

POST https://example.com/fxmd-collect
  -> POST https://fxmacrodata.com/fxmacrodata-pixel/v1/events

Relayed events reach us from your infrastructure rather than the visitor's browser. That is fine, and the address they arrive from is never held against you. What matters is that the signals the collector reads from the request survive the hop.

What you may change on the way through

The path field, and we would rather you did. If your URLs carry record ids, account numbers, or anything else belonging to your customers, replace them before forwarding. path feeds the per-page breakdown in your reporting and nothing else: it never identifies a person, and it never affects what you are billed. A normalised path such as /reports/:id gives you a cleaner breakdown than one row per document, and keeps your identifiers on your side.

Leave the rest as the pixel produced it. The visitor and session ids, the origin, the module names, and the meter mode are all metering inputs, and editing them changes what you are billed.

One side effect to expect: the country on each event is derived from the address the request arrives from, so a relayed event is attributed to your hosting region. The geography column in your reporting will reflect that. It has no effect on measured users or on billing.

15. Verify and troubleshoot

Open a data page in a normal browser, then check the Network tab for a POST to /fxmacrodata-pixel/v1/events returning 200. Then open the redistribution panel in API Management: it shows registered surfaces, combined users, pixel status, and the estimated next invoice. Pixel status turns active after the first accepted event.