Client JavaScript Library

This page documents the RumDash client JavaScript library API. The library tracks Core Web Vitals and other performance metrics from your website visitors in real-time.

API Reference

RumDash.init()

Initializes RumDash analytics tracking with your API key and optional metadata. This method must be called for RumDash to collect and report Core Web Vitals and performance metrics.

init() takes effect once per page load. The first call freezes the configuration and starts collection if it resolves to enabled; any later call on the same page load is ignored and logs a warning to the console. Calling it again is therefore not a way to reconfigure, to switch reporting off, or to switch it on after a first call that resolved to disabled. RumDashGlobal.disable is what stops reporting after the fact, and a page that gates collection on consent should not call init() until consent is granted.

Parameters

  • Name
    config
    Type
    RumDashClientConfig
    Description

    Configuration object containing your API key and optional metadata

Required attributes

  • Name
    key
    Type
    string
    Description

    The API key for your website, obtained from RumDash settings. This key authenticates your website with the RumDash backend and associates analytics data with your account. You can find this in your website settings under the Installation section.

Optional attributes

  • Name
    env
    Type
    string
    Description

    Optional environment identifier. Useful for larger organizations that deploy rumdash in both prod and non-prod environments so that the data can be easily segregated.

    Default: "prod"

  • Name
    revision
    Type
    string
    Description

    Optional revision identifier for associating performance metrics with specific deployments/releases. Helpful for identifying when performance regressions/improvements were introduced. Common patterns include git commit SHAs, version number strings, or stringified deployment timestamps.

  • Name
    pageType
    Type
    string
    Description

    Optional page type identifier for categorizing different page templates. Use this to categorize pages by their type (e.g., "product", "homepage", "checkout"). This allows you to filter and compare performance across different page templates in your analytics dashboard.

    For single-page applications where the page type changes during client-side navigation, use updatePageType to update the page type dynamically.

  • Name
    enabled
    Type
    boolean
    Description

    Optional flag to disable RumDash analytics tracking. When set to false, the client registers no observers, captures nothing, and transmits nothing at all, library error reports included. The flag is honored before any other configuration is read, so a failure while the library starts up cannot produce a request from a page you excluded. Useful for conditionally keeping a page out of scope, for example a payment or checkout route excluded from a PCI review.

    This flag is read once, by the first init call, and cannot be toggled after tracking has started. A traditional multi-page site gets a fresh evaluation on every route, because every route is its own page load. A single-page application does not, so use disable to stop reporting after a client-side navigation.

    Default: true

Examples

Simplest configuration with API key:

function __rdOnLoad() {

  RumDash.init({

    key: "your-api-key-here",

  });

}

Configuration with required key and multiple optional parameters:

function __rdOnLoad() {

  RumDash.init({

    key: "your-api-key-here",

    env: "production",

    revision: "v2.1.3",

    pageType: "product-category"

  });

}

RumDash.updatePageType()

updatePageType is used to update page types in single-page applications (SPAs) where the page type may change via client-side navigations. Updating the page type allows for more meaningful analytics aggregation, as should be used with the init method's pageType.

Parameters

  • Name
    pageType
    Type
    string
    Description

    The page type identifier (e.g., "product-category", "product-detail-page", "search-results")

Examples

Updating page type after a client-side navigation in a SPA:

window.RumDash &&

  window.RumDash.updatePageType("product-detail-page");

RumDash.disable()

Stops RumDash from reporting metrics at runtime, even if reporting was previously enabled via init. Once called, the client transmits nothing further for the remainder of the page's lifetime: no metrics, and no library error reports either.

Use this when you need to turn off tracking in response to a runtime signal: a user opting out of analytics, a feature flag flipping mid-session, or a single-page application navigating onto a payment route that must stay out of PCI scope. In a single-page application this is the only way to stop reporting mid-page: every init call after the first is ignored.

disable() is one-way. It cannot be undone by a later RumDashGlobal.init, so a single-page application that disables on entering a payment route stays disabled until the next full page load, including on any route the visitor navigates to afterwards. Where that is too broad, omit the RumDash snippet from the payment-page template instead.

Examples

Opting a user out of analytics in response to a consent-management event:

consentBanner.addEventListener("rejected", () => {

  window.RumDash && window.RumDash.disable();

});