Skip to main content

Capacitor / Ionic

info

This guide is for Capacitor projects, including Ionic applications built with Capacitor. For Cordova projects, use the Bugfender Cordova guide.

GitHub Stack Overflow Bugfender Bugfender

Bugfender is a game-changing platform that logs every detail your users experience and feeds the data directly 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.

Specifically for Capacitor / Ionic developers, Bugfender offers powerful capabilities to remotely monitor and debug any log or error. You can easily reproduce and fix issues using our detailed log viewer and the stack trace of exceptions.

If you don't have a Bugfender account yet, go to Bugfender Signup and come back here.

info

A sample app is available in the Bugfender Capacitor repository.

Requirements​

The current @bugfender/capacitor 5.x release requires Capacitor 8. Use a matching older Bugfender major version when maintaining an application on an older Capacitor major. The plugin supports iOS, Android, web, and Electron projects.

Install the Bugfender Plugin​

In your console, type the following command:

npm install @bugfender/capacitor @bugfender/sdk @bugfender/common
npx cap sync

Configure​

Configuring the Bugfender SDK for your Ionic application is super easy! You just need to initialize the SDK and do it as early as possible in your application's lifecycle.

In the main.ts file, initialize Bugfender:

import { Bugfender } from '@bugfender/capacitor';

const bfPromise = Bugfender.init({
    appKey: '<YOUR_APP_KEY_HERE>',
    // apiURL: 'https://api.bugfender.com/', //Usually not required, should be used for on-premises or custom data centers
    // baseURL: 'https://dashboard.bugfender.com',  //Usually not required, should be used for on-premises or custom data centers
    // overrideConsoleMethods: true,
    // printToConsole: true,
    // registerErrorHandler: true,
    // logBrowserEvents: true,
    // logUIEvents: true,
    // networkLoggingEnabled: false,
    // networkLoggingCaptureBodies: false,
    // networkLoggingCaptureErrorResponseBodies: false,
    // version: '',
    // build: '',
});


bfPromise.then(async () => {
  console.log('Bugfender initialized');
});

Usage​

Send Logs​

You can use Bugfender in a similar way you would use the console object.

You can log strings, numbers or booleans:

Bugfender.log('This is a log');

The following logging levels are available:

Bugfender.log('This is a log');
Bugfender.warn('Warn log');
Bugfender.error('Error log');
Bugfender.fatal('Fatal log');
Bugfender.trace('Trace log');
Bugfender.info('Info log');

Device associated data​

Using these functions you can associate key-value pairs to a device, like a dictionary.

  • setDeviceKey(key, value): sets a key-value pair. You can set strings, numbers or booleans
  • removeDeviceKey(key): removes a key-value pair

For example:

Bugfender.setDeviceKey('device.key.string', 'fake.string.value');
Bugfender.setDeviceKey('device.key.boolean', true);
Bugfender.setDeviceKey('device.key.float', 10.1);
Bugfender.setDeviceKey('device.key.integer', 102);
Bugfender.setDeviceKey('device.key.integer2', 104);

Bugfender.removeDeviceKey('device.key.integer2');

Send Issues​

Bugfender allows you to send issues to the server. An issue is similar to an exception but they appear 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 One', 'Issue Message One').then((url: string) =>
  console.log('Issue url: %s', url)
);

Send User Feedback​

Send feedback collected with your own UI:

const feedbackUrl = await Bugfender.sendUserFeedback(
  'Feedback title',
  'Feedback details'
);

Or open Bugfender's built-in feedback form:

const result = await Bugfender.getUserFeedback({
  title: 'Feedback',
  hint: 'Please tell us what happened',
  subjectPlaceholder: 'Subject',
  feedbackPlaceholder: 'Details',
  submitLabel: 'Send',
  closeLabel: 'Cancel',
});

if (result.isSent) {
  console.log('Feedback URL:', result.feedbackURL);
}

Advanced Usage​

Network logging​

Network logging is opt-in and disabled by default. Captured requests appear in Bugfender as logs tagged bf_network.

Bugfender.setNetworkLoggingEnabled(true);

// Optional capture settings
Bugfender.setNetworkLoggingCaptureBodies(false);
Bugfender.setNetworkLoggingCaptureErrorResponseBodies(true);
Bugfender.setNetworkLoggingURLFilter(
  ['https://api.example.com/*'],
  ['*/secrets/*']
);
Bugfender.setNetworkLoggingMaxRequestsPerMinute(60);

Use obfuscation handlers to redact application-specific secrets:

Bugfender.setNetworkLoggingRequestObfuscationHandler((url, headers, body) => ({
  url,
  headers: { ...headers, authorization: '[REDACTED]' },
  body,
}));

Bugfender.setNetworkLoggingResponseObfuscationHandler((headers, body) => ({
  headers,
  body: body?.replace(/"token":"[^"]*"/g, '"token":"[REDACTED]"') ?? null,
}));

Platform behavior:

  • iOS captures URLSession traffic. Network logging requires Bugfender iOS SDK 3.0.1 or newer.
  • Android captures OkHttp traffic through the Bugfender adapter and requires Bugfender Android SDK 4.x.
  • Web and Electron capture fetch and XMLHttpRequest through @bugfender/sdk 4.x.

Send Logs with Tags​

Bugfender has a more advanced logging system than sending regular logs, you can use the following method to add a tag will allow you find and filter logs easily in the Bugfender log viewer.

Bugfender.sendLog({
  line: 1001,
  level: LogLevel.Debug,
  tag: 'tag',
  method: 'method',
  file: 'file',
  text: 'Sending low level debug log.',
});

Send logs programmatically​

You can override the Bugfender website settings with the following functions.

  • forceSendOnce: Synchronizes all logs with the server once, regardless if this device is enabled or not. This method is useful when an error condition is detected and the logs should be sent to the server for analysis, regardless if the device is enabled in the Bugfender Console. Logs are synchronized only once. After that, the logs are again sent according to the enabled flag in the Bugfender Console. This command can be called anytime, and will take effect the next time the device is online.
  • setForceEnabled(enabled): Synchronizes all logs with the server all the time, regardless if this device is enabled or not. This method is useful when the logs should be sent to the server regardless if the device is enabled in the Bugfender Console. Logs are synchronized continuously while setForceEnabled is true. This command can be called anytime, and will take effect the next time the device is online.
Bugfender.forceSendOnce();

Bugfender.setForceEnabled(true);

Manually sending crashes​

If you have your own crash reporting system and need to send crashes, you can do so by calling directly sendCrash

Bugfender.sendCrash('Crash title', 'Crash text').then((url: string) =>
  console.log('Crash url: %s', url)
);

Sometimes you want to integrate Bugfender with a third party tool. For this purpose, the SDK provides a method that returns the URL for the session. You can send it to the third party tool to easily go to the logs of the current session from the other tool.

let session = await Bugfender.getSessionURL();

Sometimes you want to integrate Bugfender with a third party tool. For this purpose, the SDK provides a method that returns the URL for the current device. You can send it to the third party tool and easily navigate back to the logs of the device from the other tool.

let device = await Bugfender.getDeviceURL();

Disk usage​

Bugfender caches logs in the mobile device internal memory temporarily if there is no Internet connection to send logs. There is the possibility to limit the amount of disk space that this cache can take. If the cache becomes full, the oldest logs will be discarded.

Set maximumLocalStorageSize during initialization to limit the local log cache. The value is in bytes, must be between 1 MB and 50 MB, and defaults to 5 MB on iOS and Android.

await Bugfender.init({
  appKey: '<YOUR_APP_KEY_HERE>',
  maximumLocalStorageSize: 10 * 1024 * 1024,
});

API Reference​

The complete typed API reference, including initialization options and return types, is available at js.bugfender.com.