@bugfender/sdk NPM

Bugfender Web SDK

Bugfender is a game-changing platform that logs every detail your users experience and feeds the data straight to an easy-to-use web console. Bugfender SDK is multi-platform and available for mobile and web apps, so you can use the same tool for all your apps.

This Bugfender SDK is for frontend projects written in JavaScript or TypeScript.

Sample Apps
Installation
- NPM
- Browser
Usage
Advanced Usage
Content Security Policy
Changelog
- 2.x Breaking Changes
Other SDKs

Sample Apps

We have created two sample apps you can use as reference:

If you plan to use Bugfender SDK on an vanilla JavaScript app, visit https://github.com/bugfender/BugfenderSDK-JS-Sample
If you plan to use Bugfender SDK on an Angular app, visit https://github.com/bugfender/BugfenderSDK-Angular-Sample
If you plan to use Bugfender SDK on an React app, visit https://github.com/bugfender/BugfenderSDK-React-Sample
If you plan to use Bugfender SDK on an Vue.js app, visit https://github.com/bugfender/BugfenderSDK-Vue-Sample

Installation

Bugfender is designed to work both in the browser and in Node.js development environments (only for frontend).

NPM

Here are the main points to get Bugfender working on your apps:

Get an app key at bugfender.com
Install SDK NPM package:

npm install @bugfender/sdk

Then you can init and use the SDK:

// Import Bugfender
import { Bugfender } from '@bugfender/sdk';

// Initialize. `appKey` is the only required option.
Bugfender.init({
    appKey: '<YOUR_APP_KEY_HERE>',
    // apiURL: 'https://api.bugfender.com',
    // baseURL: 'https://dashboard.bugfender.com',
    // overrideConsoleMethods: true,
    // printToConsole: true,
    // registerErrorHandler: true,
    // logBrowserEvents: true,
    // logUIEvents: true,
    // version: '',
    // build: '',
});

// Bugfender now can be used
Bugfender.log('Hello world!');

Remember to change <YOUR_APP_KEY_HERE> with the app key of your app. For all the available options see our reference.

TypeScript

If you are writting an app using TypeScript, Bugfender includes a TypeScript definition file.

Browser

If you plan to use the SDK directly on your HTML/JS web page, you can import the SDK following these steps:

Get an app key at bugfender.com
Import Bugfender SDK JavaScript file
Init and use on your script

<script defer src="https://js.bugfender.com/bugfender-v2.js"></script>
<script defer src="your-script.js"></script>

Note that to respect the loading order the script tags must have the defer attribute and not async. If async is used, the order is not guaranteed so there might be logs & errors from your app that Bugfender won't catch.

// your-script.js
// Bugfender will be registered in `window`
// Initialize. `appKey` is the only required option.
Bugfender.init({
    appKey: '<YOUR_APP_KEY_HERE>',
});

// Bugfender now can be used
Bugfender.log('Hello world!');

Remember to change <YOUR_APP_KEY_HERE> with the app key of your app. For all the available options see our reference.

Usage

Only after you have initialized the SDK you can start using it. For a complete API Reference visit the following URL: https://js.bugfender.com.

Send logs

The SDK provides the following methods to send logs to the server:

Bugfender.trace()
Bugfender.info()
Bugfender.log()
Bugfender.warn()
Bugfender.error()
Bugfender.fatal()

The signature of these methods is the same as the window.console equivalents.

Capturing `console` logs

Probably you might want to get all you app logs in your log viewer, to do this, when you init Bugfender you can enable the console override. For this there's the overrideConsoleMethods option you can enable/enable. By default the SDK will capture window.console calls.

Disable UI events logging

Bugfender logs some UI events by default. This includes: clicks, field focus/blur, field keypresses with the resulting value (except for password fields) and form submissions. To disable this behaviour set logUIEvents option to false on Bugfender initialization.

Ignore keypress value for sensitive fields

Bugfender already ignores password fields from keypress logging, but if you need to ignore a sensitive field you can use the data-bf-ignore-keypress attribute. Note that this can be applied to a single field or a group of fields. If you want to disable this behavior for the whole page add the attribute to the html or body element.

<!-- Ignore a single field -->
<input placeholder="Sensitive field…" data-bf-ignore-keypress>

<!-- Ignore a group of fields. Note that all children of `form` are ignored. -->
<form data-bf-ignore-keypress>
    <input placeholder="Superhero name">
    <input placeholder="Superhero HQ address">
</form>

<!-- Ignore on all the fields -->
<body data-bf-ignore-keypress>
    ...
</body>

Note that what's being ignored is the value of the field. The keypress event will still be registered.

Advanced Usage

Send issues

Bugfender allows you to send issues to the server. An issue is similar to a session but they are showed in the issues section and you can send issues any time from the app, even if the device is not enabled in the system. Issues are useful to keep track of important errors that you can detect in your code.

For sending an issue you can use the following function:

Bugfender.sendIssue('Issue title', 'Description of the issue');

Send logs with tags

Bugfender has a more advanced logging system that console.log() and allows you to add tags to the logs, adding a tag will allow you find and filter logs easily in the Bugfender log viewer.

Bugfender.sendLog({ tag: 'tag1', text: 'this is my log' });

Using `LogLevel` enum

The way you access the LogLevel enum depends on how you're consuming the Bugfender SDK.

NPM package, ES6 import:

import { LogLevel } from '@bugfender/sdk';

NPM package, CommonJS require:

const LogLevel = require('@bugfender/sdk').LogLevel;

Browser <script> tag:

Bugfender.LogLevel

Device associated data

You can associate information to a device as if it were a dictionary:

Bugfender.setDeviceKey('key', 'value');
Bugfender.removeDeviceKey('key');

You can find more information in our blog post Associated device information.

Collect User Feedback

Bugfender can collect User Feedback. User Feedback is similar to a session but they will show in the "User Feedback" section. You can send them any time from the app, even if the device is not enabled.

Bugfender.sendUserFeedback('Love the App!', 'You are doing a great job with it.')

User Feedback modal

npm.io

You can call getUserFeedback() to open a feedback modal. This method accepts an options object which allows to customise the modal strings. We also provide CSS variables to customise the styling (see below).

Bugfender.getUserFeedback().then((result) => {
    if (result.isSent) {
        // User sent the feedback
        // `result.feedbackURL` contains the Bugfender feedback URL
    } else {
        // User closed the modal without sending the feedback
    }
});

CSS variables:

--bf-backdrop-bg: rgba(0, 0, 0, .5);
--bf-border-radius: 4px;
--bf-color: #222;
--bf-font-heading: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
--bf-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
--bf-input-border: 1px solid #ccc;
--bf-modal-shadow: 0px 4px 12px 0px rgba(0, 0, 0, 0.25);
--bf-placeholder-color: #757575;
--bf-submit-bg: #ff5060;
--bf-submit-color: #fff;
--bf-submit-shadow: 0 2px 0 0 #a93e48;
--bf-z-index: 9999;

Send a Crash manually

You can also manually send crash information. Usually you do not want to use this, enable automated crash reporting instead using the registerErrorHandler option. This will force all logs in the current session to be sent, even if log sending is disabled.

Bugfender.sendCrash('Crash Title', `Ops, the app crashed, better check what's wrong.`);

API Reference

For a complete API Reference you can visit: https://js.bugfender.com.

Content Security Policy

If you have CSP enabled you'll need to grant access to the following resources:

api.bugfender.com: for the Bugfender API.
js.bugfender.com: for the browser <script>.

If you opted for the NPM installation you'll only need to grant access to the API:

Content-Security-Policy: default-src api.bugfender.com;

Otherwise, if you've installed Bugfender via the browser <script> tag, you'll need to grant access to both the API & the JS library:

Content-Security-Policy: default-src api.bugfender.com js.bugfender.com;

For more information on how to configure CSP please refer to the MDN documentation.

Changelog

The changelog of the Bugfender Web SDK can be found in ReleaseNotes under the js tag. For all the Bugfender product changes please visit the general release notes.

2.x Breaking Changes

The Web SDK API has changed slightly to be compatible with the Bugfender React Native SDK. Be aware of the following breaking changes before upgrading to 2.x:

The following methods now are asyncronous and return a Promise:
- getDeviceURL
- getSessionURL
- sendIssue
- sendCrash
- sendUserFeedback
Markdown has been deprecated:
- sendIssueMarkdown: method removed. Use sendIssue instead.
- sendIssue & sendCrash: won't wrap text inside Markdown code block backticks anymore.