This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

nucleus-nodejs

Analytics, licensing and bug reports for Node.js, Electron and NW.js desktop applications.

We made it as simple as possible to report the data you need to analyze your app and improve it.

To start using this module, sign up and get an app ID on Nucleus.sh.

Electron:

This module works in both the renderer and the main process. However be sure to only call the appStarted() method once per session (in only one process) or you'll find duplicate data in the dashboard.

This module can even run in a browser outside of Node (for example in the Electron renderer process with Node Integration disabled).

Installation

Using npm:

$ npm install nucleus-nodejs --save

Usage

Sign up and get a tracking ID for your app here.

Call the appStarted method only one time per session.

You only need to call init once per process.

If you use the module in both the main and renderer process, make sure that you only call appStarted once.

const Nucleus = require("nucleus-nodejs")

Nucleus.init("<Your App Id>")

// Optional: sets an user ID
Nucleus.setUserId("richard_hendrix")

// Required: Sends the first event to the server that app started
Nucleus.appStarted()

// Report things
Nucleus.track("PLAYED_TRACK", {
  trackName: "My Awesome Song",
  duration: 120,
})

Options

You can init Nucleus with options:

const Nucleus = require("nucleus-nodejs")

Nucleus.init("<Your App Id>", {
  disableInDev: false, // disable module while in development (default: false)
  disableTracking: false, // completely disable tracking from the start (default: false)
  disableErrorReports: false, // disable errors reporting (default: false)
  autoUserId: false, // auto assign the user an id: username@hostname
  debug: true, // Show logs
})

Nucleus.appStarted()

Each property is optional. You can start using the module with just the app ID.

The module will try to autodetect a maximum of data as possible but some can fail to detect (especially if in a Browser outside of Node).

It will tell you in the logs (if you set debug: true) which one failed to detect.

You can also change the data, if you make sure to do it before the appStarted method.

Nucleus.setProps({
  version: "0.3.1",
  language: "fr",
  // ...
})

Nucleus.appStarted()

Note : when running in development, the app version will be '0.0.0'

Identify your users

You can track specific users actions on the 'User Explorer' section of your dashboard.

For that, you need to supply an userId, a string that will allow you to track your users.

It can be your own generated ID, an email, username... etc.

Nucleus.identify("someUniqueUserId"})

You can also pass custom attributes to be reported along with it.

Nucleus.identify("someUniqueUserId", {
  age: 34,
  name: "Richard Hendricks",
  jobType: "CEO",
})

If you call .identify() multiple times, the last one will be remembered as the current user data (it will overwrite).

Later on, you can update the userId only (and keep the attributes) with this method:

Nucleus.setUserId("someUniqueUserId")

Alternatively, set the autoUserId option of the module to true to automatically assign the user an ID based on his username and hostname.

Update user attributes

You can report custom user attributes along with the automatic data.

Those will be visible in your user dashboard if you previously set an user ID.

The module will remember past properties so you can use Nucleus.setProps multiple times without overwriting past props.

Properties can either numbers, strings or booleans. Nested properties or arrays aren't supported at the moment.

Nucleus.setProps({
  age: 34,
  name: "Richard Hendricks",
  jobType: "CEO",
})

Enable overwrite: set the second parameter as true to overwrite past properties.

Nucleus.setProps({
  age: 23,
}, true)

Events

After initializing Nucleus, you can send your own custom events.

Nucleus.track("PLAYED_TRACK")

They are a couple event names that are reserved by Nucleus: init, error: and nucleus:. Don't report events containing these strings.

Attach more data

You can also add extra information to tracked events, as a JSON object.

Properties can either numbers, strings or booleans. Nested properties or arrays aren't supported at the moment.

Example

Nucleus.track("PLAYED_TRACK", {
  trackName: "My Awesome Song",
  duration: 120,
})

Toggle tracking

This will completely disable any communication with Nucleus' servers.

To opt-out your users from tracking, use the following methods:

Nucleus.disableTracking()

and to opt back in:

Nucleus.enableTracking()

This change won't persist after restarts so you have to handle the saving of the settings.

You can also supply a disableTracking: true option to the module on start if you want to directly prevent tracking.

Errors

Nucleus will by default report all uncaughtException and unhandledRejection.

If you'd like to act on these errors, for example show them to your user, quit the app or reload it, you can define an onError function, which will be called on errors happening on the respective process.

Nucleus.onError = (type, err) => {
  console.error(err)
  // type will either be uncaughtException, unhandledRejection or windowError
}

windowError is an uncaughtException that happened in the renderer process. It was catched with window.onerror.

If you'd like to report another type of error, you can do so with:

Nucleus.trackError("myCustomError", err)

Contact [e-mail] for any inquiry