API

---

• Initialization Options
• Automatically Capture Errors
• Manually Capture Errors
• Manually Capture Messages
• Context
• Close Handler

Initialization Options

The init method sets the options when you first initialise the library.

Understand.init({
  env: 'production',
  token: 'b6eeab13-72f6-4c35-8452-5e96d3d24f1a',
  disableSourceMaps: false,
  beforeSend: (event) => {},
  context: {}
});

env

Required, a string that defines your application environment.

token

Required, the input token from your Understand.io channel.

disableSourceMaps

Disables source maps. Check the source maps section for more information.

beforeSend

• fn: (event: Object) => event

A callback function that allows you to add custom logic to an event before sending it.

Understand.init({
  ...
  beforeSend: (event) => {
    // add custom tag based on event message
    if (event.message && event.message.match(/login failed/i)) {
      event.tags = [...event.tags, 'authentication'];
    }

    return event;
  }
});

You can also optionally discard the event by returning null.

Understand.init({
  ...
  beforeSend: (event) => {
    // discard events coming from localhost
    if (event.client_ip === '127.0.0.1') {
      return null;
    }

    return event;
  }
});

context

The context object lets you add context information along with your events.

Context can be injected using the initialization options:

Understand.init({
    ...
    context: {
      request_id: '<request id>',
      session_id: '<session id>',
      user_id: '<user id>',
      client_ip: '<client ip>',
      tags: []
    }
});

or using setters, as explained in the Context section.

• request_id: this value is used by Understand to group multiple errors into the same issue. This id is unique per page visit.

• session_id: this value is used by Understand to group errors into the same session. You can optionally set this value to your HTTP server session identifier.

• user_id: integer or null, the identifier of the logged user.

• client_ip: the IP address of the user.

• tags: array of tags that can help you categorize events.

Note: the handler will take care of providing default values for request_id and session_id, but you could always use your own values if you want to have more control on how events are grouped. For example, if you're using Laravel you can easily set the context using framework specific methods:

Understand.init({
  session_id: '@{{ sha1(request()->session()->getId()) }}',
  user_id: @{{ auth()->id() }},
  client_ip: '@{{ request()->getClientIp() }}'
});

Note that here we are using sha1 to hash the session id in order to avoid security concernes.

Automatically Capture Errors

To automatically attach global handlers to capture uncaught exceptions and unhandled rejections you will need to call catchErrors after initialization process.

Understand.catchErrors();

To optionally enable/disable global handlers you can pass an object to catchErrors with the proper boolean values, for example:

Understand.catchErrors({
  enableWindowError: true,
  enableUnhandledRejection: false
});

• enableWindowError (true by default) automatically setups window.onerror handler to catch JavaScript runtime errors.
• enableUnhandledRejection (true by default) automatically setups window.onunhandledrejection handler, for catching events raised by unhandled Promise rejections. Note: the browser support for this feature is limited.

Manually Capture Errors

You can pass an Error object to logError() to get it captured as an event.

try {
  throw new Error('Oh snap!');
} catch (e) {
  Understand.logError(e);
}

You can throw a string (or other primitives) as an error, but it would then be treated as a message. See A string is not an Error for more information.

Manually Capture Messages

If you need to send a basic message to Understand you can do so by using the logMessage() method:

Understand.logMessage('my message', 'info');

You can set the severity of a message to one of five values: fatal, error, warning, info, and debug. When capturing messages info is the default level.

Note: only messages with fatal and error severity level will show up in the Errors section of Understand's dashboard.

Context

As already introduced in the Initialization Options section, Understand supports 3 types of structured data for context, which allows you to add more useful information in order to identify issues. Those values can be set at any time using setters:

Session

Understand.withContext(function (context) {
  context.setRequestId('<request identifier>');
  context.setSessionId('<session identifier>');
});

User

Understand.withContext(function (context) {
  context.setUserId(<user identifier>);
  context.setClientIp('<ip address>');
});

Tags

Understand.withContext(function (context) {
  context.setTags(['backlog']);

  // or push individual tag
  context.setTag('demo');
});

You can clear the context using the clear() method:

Understand.withContext(function (context) {
  context.clear();
});

Close handler

If at any time you decide that you don't want to report errors anymore you can close the handler.

Understand.close();