babel-plugin-autoinstrument v2.1.3

Babel Plugin Auto-Instrument

This plugin will automatically generate data-gs and data-gs-c attributes for JSX elements based off of their path and position in the JSX tree.

For example, the path /app/components/file.js and JSX <Content><Main/></Content> would generate the following data-gs attribute for <Main>:

<Main data-gs="app__components__file__Content__Main />

The data-gs-c attribute (short for "data-gainsight-content") is derived from an elements children, content or various attribute (e.g. title or name.) An example:

<Content>
    <Header>
      A Title
    </Header>
</Content>

in the file /app/pages/News.js would generate the following attributes for <Header>:

<Header data-gs="app__pages__News__Content__Header" data-gs-c="a-title">

Motivation

We want to use the analytics solution Gainsight to track usage of our application. In Gainsight, features such as "Create new Query" are mapped to elements in the DOM, like the "Create Query" button.

These elements need to be uniquely identifiable. To minimize maintenance effort, the unique attributes are generated at build time, instead of manually adding id attributes (or other unique characteristics.) This also allows mapping new features without requiring changes from the front-end team and a new release.

Gainsight uses CSS selectors to identify elements in the DOM, for example

[data-gs*="News"][data-gs-c*="title"]

would match the <Header data-gs="app_pages_News" data-gs-c="a-title">. The selectors use substring matching and are chosen to be as robust as possible, e.g. adding a wrapping <div> around the <Header> would not break the selector, even though the data-gs attribute would now contain app__pages__News__Content__div__Header.

Should the selector break with a new release (e.g. renaming News.js to Blog.js), Gainsights backfill feature can be used to fill in the gap after the release. Gainsight tracks all interactions with the app, and stores the target elements attributes and the parent elements from the DOM. A new selector (e.g. [data-gs*=Blog"][data-gs-c*="title"]) can retroactively be matched against this history of interactions and mapped to a certain feature.

The data-gs-c attribute is necessary for e.g. <label> elements and other that contain short but usually identifying content, as it's not possible to match against content with CSS selectors (unlike with e.g. XPath.)

Caveats

In some cases, data-gs needs to be explicitly forwarded to JSXElements that render DOM nodes. For example, if a shared component doesn't forward data-gs, then only the attributes generate for the shared component will end up in the DOM, not the attributes where it was used:

Shared component /app/components/Button.jsx:

export function Button({ title, style, children, onClick }) {
  return (
    <a onClick={onClick} title={title} className={style === 'important' ? 'red' : 'green'}>
        <span className='expand-padding'>
            <span className={style === 'important' ? 'big' : 'small'}>
                {children}
            </span>
        </span>
    </a>
  )
}

Usage /app/pages/DatabaseEditor.jsx:

<Form>
    <Button style='important'>
        Delete Database
    </Button>
</Form>

In DatabaseEditor.jsx, would get the following data-gs props:

data-gs={gs('app', 'pages', 'DatabaseEditor', 'Form', 'Button')}
data-gs-c={gsC('delete-database')}

This would help identify this particular button via the delete-database string. However, as the shared component does not forward data-gs or data-gs-c that's passed to it, the actual DOM node will end up like this:

<a class='red' data-gs='app__components__Button'>
    <span class='expand-padding' data-gs='app__components__Button__span'>
        <span class="big' data-gs='app__components__Button__span__span' data-gs-c="delete-database">
            Delete Database
        </span>
    </span>
</a>

The padding on <a>s child will expand the clickable area in <a>, however the useful data-gs-c attribute ends up on the second <span>. Gainsight would now only count clicks on "Delete Database" if they actually hit the letters, and not if they hit the margin/padding.

Depending on the design, the margin/padding can be a significant part of the button, and Gainsight would miss clicks on that area, which will skew our statistics.

Therefore, the shared component needs to be modified to forward data-gs and data-gs-c to the <a> tag:

export function Button({ title, style, children, onClick, 'data-gs': dataGs, 'data-gs-c': dataGsC }) {
  return (
    <a
        onClick={onClick}
        title={title}
        className={style === 'important' ? 'red' : 'green'}
        data-gs={dataGs}
        data-gs-c={dataGsC}
    >
        <span className='expand-padding'>
            <span className={style === 'important' ? 'big' : 'small'}>
                {children}
            </span>
        </span>
    </a>
  )
}

The output will now be

<a class='red' data-gs='app__pages__DatabaseEditor__Form__Button' data-gs-c="delete-database">
    <span class='expand-padding' data-gs='app__components__Button__span'>
        <span class="big' data-gs='app__components__Button__span__span' data-gs-c="delete-database">
            Delete Database
        </span>
    </span>
</a>

and the following CSS selector would track all clicks on the Button, even those that hit margin/padding:

[data-gs*=DatabaseEditor][data-gs-c*="delete-database"]