Skip to main content

Bugfender iOS SDK - Objective-C

info

An iOS Sample app is available at Github Bugfender iOS

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 iOS 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.

Supported iOS versions:

  • BugfenderSDK 2.0 works for iOS 12.0 and newer.
  • For iOS 11.0 support you can use BugfenderSDK 1.12.
  • For iOS 10 support you can use BugfenderSDK 1.10.6.
  • For iOS 8 support you can use BugfenderSDK 1.8.

Install​

tip

Learn How To Install Bugfender iOS SDK in 10'​

Watch this simple tutorial and learn how to receive the NSLog logs and crashes form your iOS users.

In order to get started using the Bugfender JavaScript SDK, you will need to load the Bugfender script to the top of your application, before all other scripts. Alternatively, you can also install the SDK via a package manager.

Please note you will need Xcode 12 or better.

  1. In Xcode go to the target's General tab and press on the icon to add a new library

  2. In the popover choose Add Other and then Add Package Dependency...

  3. Paste the GitHub url from the Bugfender iOS repository https://github.com/bugfender/BugfenderSDK-iOS in the textfield and press Next

  4. Leave the first option checked and press Next

  5. Xcode will download the Bugfender files and you will be prompted with the following menu. Ensure BugfenderSDK is selected and press Finish

  6. Import SystemConfiguration.framework, Security.framework, CoreServices.framework, CoreGraphics.framework and libc++.tbd as well.

Configure​

Configuring the Bugfender SDK for your iOS application is super easy! Make Bugfender available project-wide by adding the following line to the .pch file:

#import <BugfenderSDK/BugfenderSDK.h>

Get an API key from the Bugfender console. In your AppDelegate call activateLogger when the application starts, in application:didFinishLaunchingWithOptions: add the following:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    //Next two lines are usually not required
    //But in case you have on-premises or custom data centers, you might need to put your URLs
    //[Bugfender setApiURL:[NSURL URLWithString:@"https://api.bugfender.com/"]] 
    //[Bugfender setBaseURL:[NSURL URLWithString:@"https://dashboard.bugfender.com"]]

    // Activate the remote logger with an App Key.
    [Bugfender activateLogger:@"YOUR_APP_KEY"];
    [Bugfender enableNSLogLogging]; // optional, capture logs printed to console automatically
    [Bugfender enableUIEventLogging]; // optional, log user interactions automatically
    [Bugfender enableCrashReporting]; // optional, log crashes automatically
    ...
}
note

Remember to change YOUR_APP_KEY with the app key of your app. You can get an app key by signing up to Bugfender.

Usage​

Send logs​

BFLog(@"Hello world!"); // use BFLog as you would use NSLog

You may use BFLog as you would normally use NSLog.

You may also want to specify a logging level by using the following macros:

  • BFLogFatal(...): Fatal log.
  • BFLogErr(...): Error log.
  • BFLogWarn(...): Warning log.
  • BFLogInfo(...): Info log.
  • BFLog(...): Default (debug) log.
  • BFLogTrace(...): Trace log.

Pro tip: Use search and replace to change all NSLog to BFLog using Find > Find and Replace in Workspace...

We also have support for several logging libraries:

Device associated data​

Once your application is running on several devices, it will be useful to know which device belongs to whom. You can associate information to a device as if it were a dictionary:

[Bugfender setDeviceString:@"[email protected]" forKey:@"user email"];

This will later on let you search this device by “key” in the Bugfender Dashboard and you can use any of the associated data to filter our your device list.

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 sendIssueWithTitle:@"App Error" text:@"We have found an Error, we need to check it"];

Collect user feedback​

Getting feedback from the final users is one of the most important things for an app developer. Good user feedback allows you detect errors in your app and helps you to understand better your product.

Bugfender provides a feature to easily collect app feedback from final users. It takes only two minutes and a few lines of code to integrate. You can think about the User Feedback as a special kind of Issue, every time your users submit their feedback you will get a new issue in Bugfender.

The easiest way to implement Bugfender User Feedback is using the customizable User Feedback View Controller. It provides a convenient view controller with two text fields, one short for the subject and another bigger for the feedback. Both text fields grow automatically.

Using the default UI​

Using the convenient UI provided by Bugfender requires only creating a new View Controller and presenting it modally. All you need is to call the following method and complete the required parameters with the title and placeholders for your UI.

// Instantiate new User Feedback
BFUserFeedbackNavigationController *nvc = [Bugfender userFeedbackViewControllerWithTitle:@"Navigation bar title"
                                                  hint:@"Give some instructions to your users"
                                    subjectPlaceholder:@"Placeholder for subject textfield"
                                    messagePlaceholder:@"Placeholder for message textfield"
                                       sendButtonTitle:@"Send"
                                     cancelButtonTitle:@"Cancel"
                                            completion:^(BOOL feedbackSent, *NSURL issueURL) {
                                                if (feedbackSent) {
                                                    // Say thanks!
                                                } else {
                                                    // User decided to not send feedback
                                                }
                                            }];

// Present modally
[self presentViewController:nvc animated:YES completion:nil];

Additionally, if you require more customization you can configure the view controller prior to presenting it.

Please note BFUserFeedbackNavigationController is a subclass of navigation controller. You need to access the view controller using the public property feedbackViewController. For a complete list of customizable attributes you can inspect "BFUserFeedbackViewController.h".

Using a custom UI​

If you need further customization than provided by BFUserFeedbackViewController you can implement your own UI. All you have to do is collect your user feedback as you wish and send it to Bugfender using sendUserFeedback:

NSURL * feedbackUrl = [Bugfender sendUserFeedbackReturningUrlWithSubject:@"Title of the feedback" 
                                                                 message:@"message of the feedback"];

The returned URL is a direct link to the Bugfender's dashboard. Use it to create automations or to keep a reference in your servers.

Advanced Usage​

Collecting system logs​

Automatic os_log collection​

Bugfender can collect os_log and NSLog messages from your customers' iOS devices. To enable the automatic collection, call:

[Bugfender enableNSLogLogging];

Customizing os_log collection​

Bugfender also provides the enableNSLogLogging(withInterceptor:) function which to enable the log system collection but allows you tu use an interceptor to do an advanced filtering of the messages you want to send to our systems.

Implemente a custom BFLogInterceptor:

#import <Foundation/Foundation.h>
#import <BugfenderSDK/BugfenderSDK.h>

@interface CustomLogInterceptor : NSObject <BFLogInterceptor>
@end

@implementation CustomLogInterceptor

- (BFInterceptedLog *)intercept:(BFInterceptedLog *)interceptedLog {
    // Implement your filtering logic here
    // For example, only log messages that contain a specific keyword
    if ([interceptedLog.text containsString:@"ImportantKeyword"]) {
        return interceptedLog;
    } else {
        return nil; // Returning nil will block the log entry
    }
}

@end

When you initialize Bugfender, you need to use your custom interceptor:

##import "AppDelegate.h"
#import "CustomLogInterceptor.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Activate Bugfender with your app key
    [Bugfender activateLogger:@"YOUR_APP_KEY"];
    //... other Bugfender options ...

    // Create an instance of your custom interceptor
    CustomLogInterceptor *interceptor = [[CustomLogInterceptor alloc] init];

    // Enable NSLog interception with your custom interceptor
    [Bugfender enableNSLogLoggingWithInterceptor:interceptor];

    // ... other setup code ...

    return YES;
}

@end

Check the signature of BFInteceptedLog to see all the properties you can use.

Having your app decide when to send logs​

In some special circumstances you may want to send logs, regardless of the enabled state of the device in the Bugfender console, for example in a custom exception handler. Use forceSendOnce to force sending the logs once, and use setForceEnabled: to force it for some period of time.

Manually sending crashes in iOS​

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

[Bugfender sendCrashWithTitle:@"My Crash" text:@"The app crashed on my code"];

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.

[Bugfender sessionIdentifierUrl];

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.

[Bugfender deviceIdentifierUrl];

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.

[Bugfender sessionIdentifierUrl];

Log buffer size​

Bugfender keeps up to 5 MB worth of log data in the device. This way Bugfender can work offline, and you can get some log data from the past when enabling a device. You can change that limit with setMaximumLocalStorageSize.

// Setting maximum cache size to 1 Mb
[Bugfender setMaximumLocalStorageSize:(1024*1024)];

Updating from BugfenderSDK prior to 1.8 and ObjC only projects​

BugfenderSDK is now a dynamic framework and you will need to check the "embed framework" option when adding it to your project manually or using Carthage.

Additionally, the Bugfender.swift helper class is not needed anymore and can be safely deleted, however, Swift must be available in your project. If you are installing Bugfender manually or using Carthage ensure that Build Settings -> Always Embed Swift Standard Libraries is set to YES.

Automate Symbols Uploading​

You can use the Bugfender XCode Script to automatically upload dSYM bundle for symbolicating crashes.

Note: At the moment, Bitcode enabled apps are not supported by the script.

To add the script to XCode:

  1. Copy the script to your project directory.
  2. Go to your App settings.
  3. Select Target from the left.
  4. Select the Build Settings tab, find Build Options > User Script Sandboxing and set it to No.
  5. Go to Build Phases.
  6. Open menu under the + sign and select New Run Script Phase.
  7. Under the shell portion of Run Script add a script call: BUGFENDER_SYMBOLICATION_URL=https://dashboard.bugfender.com/ <path_to_the_script>/upload-symbols.sh YOUR_SIMBOLICATION_TOKEN
    • It is also possible to drag & drop it from Finder and XCode will fill in the path.
note

Remember to change YOUR_SIMBOLICATION_TOKEN with the symbolication token for your app. You can get an app key by signing up to Bugfender.

Xcode Symbols Script

API Reference​

For a complete API Reference you can visit: https://bugfender.github.io/BugfenderSDK-iOS/Classes/Bugfender.html