npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@smartesting/gravity-data-collector

v8.1.2

Published

Browser lib to collect your users behaviors and push the data in your Gravity project

Downloads

4,025

Readme

Node workflow

Gravity Data Collector - README

This repo contains the browser implementation of the Gravity Data Collector. Learn more about Gravity on our website

Setup

Via NPM

npm i @smartesting/gravity-data-collector

Via Yarn

yarn add @smartesting/gravity-data-collector

By updating package.json

In your package.json, add the following:

{
  "dependencies": {
    "@smartesting/gravity-data-collector": "^8.1.2"
  }
}

In your package.json, add the following:

From a script tag

Put this tag in each page that must use Gravity Data Collector.

<script
  async
  id="logger"
  type="text/javascript"
  src="https://unpkg.com/@smartesting/[email protected]/dist/gravity-logger-min.js"
></script>

Please, look to index.html to see how to use the script in HTML.

Note: The minified version of Gravity Data Collector is available only since release 2.1.5

Initialization

// initialize
import GravityCollector from '@smartesting/gravity-data-collector/dist'

GravityCollector.init(/*options*/)

Options

The GravityCollector.init() can take a CollectorOptions object with the following optional properties:

| key | type | use | default value | | ---------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | | authKey | String | The authentication key provided by Gravity to select the correct collection | | | requestInterval | Integer | Time (in ms) between two sends to Gravity server (buffering) | 1000 | | gravityServerUrl | String | Gravity server URL | https://api.gravity.smartesting.com | | debug | Boolean | Logs user action in the console instead of sending them to Gravity | false | | maxDelay | Integer | In debug mode, adds a random delay (in ms) between 0 and this value before printing an user action. | 500 | | selectorsOptions | Object (optional) | See Work with selectors. | undefined | | sessionsPercentageKept | [0..100] | Rate of sessions to be collected | 100 | | rejectSession | function () => boolean | Boolean function to ignore session tracking. For instance, to ignore sessions from some bots:rejectSession: () => /bot|googlebot|robot/i.test(navigator.userAgent) | () => false | | onPublish | function (optional) | Adds a function called after each publish to the gravity server. | undefined | | recordRequestsFor | String[] (optional) | The Gravity Data Collector does not record requests by default. You must specify here the URL origin(s) of the requests to record. For example: "https://myserver.com/" | undefined | | buildId | String (optional) | The build reference when running tests | undefined | | useHashInUrlAsPathname | Boolean (optional) | Set to true to have a correct representation of pages in Gravity if your page URLs look like this: "http://mysite.com/#/something/else" | false | | cookieStrategy | CookieStrategy ('default', 'subDomains' or 'iframeEmbedding') | Change the way the cookie is set: default works in most cases, subDomains should be used to track a single session accross multiple sub domains, iframeEmbedding should be used if your app is embedded as an iframe (eg: Jira or Azure DevOps plugin) | 'default' | | cookieWriter | (key, value, options) => string (optional) | A function used to create the cookie value (if you need to specify custom options) | null |

Features

Work with selectors

In the Gravity Data Collector, when a user action targets an HTML element, selectors are computed in order to replay the session as an automated test.

By default, the following selectors are computed:

  • xpath: a XPath selector to reach the element (eg: /html/body/div)
  • queries: on object describing various ways to reach the objet
    • id: if available, the element's id (eg: #my-object)
    • class: if available, selection of the object following CSS classes (eg: .my-container .some-class)
    • tag: selection based on the tags (eg: html body div ul li)
    • nthChild: selection based on nth-child (eg: :nth-child(2) > :nth-child(4))
    • attributes: if available, selection based on the nodes attributes (eg: [name=])
  • attributes: a hash of attributes provided by the user (default: ['data-testid'])

Tweaking selectors

xpath is always collected.

When initializing the collector, you can specify which selectors (in the queries field) and attributes you want to collect.

GravityCollector.init({ selectorsOptions: { attributes: ['data-testid', 'role'] } })

This configuration will collect all the selectors (default if queries is not specified), the data-testid and the role attributes of the HTML element with which the user interacts.

import { QueryType } from '@smartesting/gravity-data-collector/dist/types'

GravityCollector.init({ selectorsOptions: { queries: [QueryType.class, QueryType.tag] } })

This configuration will collect the CSS class(es), the tag and the data-testid (default if attributes is not specified) of the HTML element with which the user interacts.

Alternatively, you can also exclude some selectors of the queries field. For example, if you do not want id-based selectors, you can specify it this way:

import { QueryType } from '@smartesting/gravity-data-collector/dist/types'

GravityCollector.init({
  selectorsOptions: {
    excludedQueries: [QueryType.id],
  },
})

You can specify both queries and attributes fields:

import { QueryType } from '@smartesting/gravity-data-collector/dist/types'

GravityCollector.init({
  selectorsOptions: {
    queries: [QueryType.class, QueryType.tag],
    attributes: ['data-testid', 'role'],
  },
})

Identify sessions with traits

A sessions trait allows you to add context to the collected sessions, so you can easily segment them in Gravity. It is done by calling the identifySession method.

For instance, you can identify the sessions of users connected to your app:

window.GravityCollector.identifySession('connected', true)

Note: Please, keep in mind that each trait can only have a single value. It means if you set the trait connected to true and then to false, the first value will be overwritten.

Send build information to Gravity

In order to easily identify your tests sessions in Gravity, the data-collector can send build information to Gravity.

The build ID can be specified in multiple way. You can set the following properties on process.env (for example when using React)

| environment variable name | Gravity data | | -------------------------- | ------------ | | GRAVITY_BUILD_ID | buildId | | REACT_APP_GRAVITY_BUILD_ID | buildId |

You can also declare window.GRAVITY_BUILD_ID (or simply declare a global variable GRAVITY_BUILD_ID which should be assigned to the window object).

Another solution is to pass the buildIdparameter when initializing gravity data collector:

GravityCollector.init({
  authKey: '...',
  buildId: '1234',
})

Sandbox

In order to test modifications on the library, a sandbox is accessible in index.html file

First, build the lib

  npm run build

Then build the sandbox and watch for files changes:

npm run build-sandbox
npm run watch-sandbox

Finally, open index.html with a browser, display the console (F12 with most browsers) and interact with the page to see collected user actions.

Note: user actions may not show up in the console and be hidden by default. Ensure Verbose output are allowed by your developer tool.

Any Question ?

Maybe you need help to install and/or understand Gravity Data Collector

  • please visit our documentation pages
  • we start a FAQ hoping it can help you to face eventual problems with th Gravity Data Collector
  • here is a flowchart summarizing how the collector works, depending on the options and configuration of your Gravity project.