API Reference: sd-metrics

The sd-metrics script evaluates the physical hardware and exposes the results via an asynchronous JavaScript API.

Because modern Single Page Applications (SPAs) and ad scripts often load concurrently with third-party libraries, the Impulse Engine provides robust listener methods (.on, .once, .get) to guarantee you never encounter a race condition or an undefined variable.

Creating the Engine

new SdMetrics(options)

• Options:
  • endpoint (String): your private data stream endpoint URL.
  • storage (Boolean, default true): caches the metrics in localStorage so they are available faster on later page loads. The cache only holds the metrics and is never sent out of the browser by ScaleDynamics. Set it to false to disable the cache.

Example:

window.sd = new SdMetrics({
  // Replace <PRIVATE_URL> with your private data stream endpoint URL
  endpoint: '<PRIVATE_URL>',
  // Disable the local metrics cache
  storage: false,
});

Metric names

• AdTech Variables: inventory_tier, device_tier. When passed to an ad server, they are usually prefixed (e.g. GAM key sd_inventory_tier). Have a look to AdTech metrics references for more details.
• Engineering Metrics: bdp, mdc, air. Have a look to Engineering metrics references for more details.

Metric Methods

Each metric object exposes three methods to handle data retrieval based on your application's architecture.

1. .get(options?)

Returns a standard JavaScript Promise that resolves with the metric's value as soon as the hardware evaluation is complete. Ideal for async/await workflows.

• Options (optional):
  • timeout (Number, ms): maximum time to wait, counted from the .get() call.
  • default: value returned if the metric is not available before timeout. Without default, the promise rejects on timeout.

Example:

async function initializeApp() {
  try {
    const bdpScore = await window.sd.bdp.get({ timeout: 500 });
    
    if (bdpScore >= 4) {
      await loadHeavy3dModel();
    }
  } catch (error) {
    console.warn('Hardware profiling timeout, falling back to safe UI.');
  }
}

2. .once(callback)

Fires the provided callback function exactly one time when the metric is resolved. Use it when the moment the value arrives does not matter. To set ad targeting before the first ad request, prefer .get() with a timeout and a default (see AdTech Variables).

Example:

window.sd.device_tier.once((tier) => {
  // Load the heavy rich-media component only on capable devices
  if (tier <= 2) {
    loadRichMediaWidget();
  }
});

3. .on(callback)

Subscribes a listener to the metric. While hardware limits rarely change during a single page view, this method is useful for frameworks like React or Vue where you may want to bind the metric to a reactive state variable that persists across client-side navigations.

Example:

// React useEffect hook
useEffect(() => {
  if (window.sd) {
    window.sd.mdc.on((threads) => {
      setWorkerCount(threads);
    });
  }
}, []);