@bugfender/sdk
v2.3.0
Published
Bugfender SDK for web, a remote logger tailor-made for apps
Downloads
12,214
Readme
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.
Table Of Contents
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 thedefer
attribute and notasync
. Ifasync
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
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. UsesendIssue
instead.sendIssue
&sendCrash
: won't wraptext
inside Markdown code block backticks anymore.
Other SDKs
Bugfender is also available in other platforms:
- iOS: https://github.com/bugfender/BugfenderSDK-iOS
- Android: https://github.com/bugfender/BugfenderSDK-android-sample
Learn more at Bugfender.