Installation

The recommended way to install Bugsee is using Swift Package Manager, CocoaPods or Carthage, but you can also add it to your project manually by following the instructions below.

Cocoapods

If you're installing Bugsee 1.27.0 or newer, please make sure you're using CocoaPods 1.10.0 or newer, as previous versions have a bug where improper slice from XCFramework was selected. Learn more.

Add the following line to your project's Podfile.

pod 'Bugsee'

Run the following commands to install the Pod.

pod install
pod update Bugsee # This is important, install command does not guarantee you will get latest version

If you are using CocoaPods you can skip now directly to initialization

Swift Package Manager

Navigate to the SPM section in your project, add a new package, point it to

https://github.com/bugsee/spm

and select the latest version.

Add to Swift Package Manager

Carthage

Add the following line to your project's Cartfile.

binary "https://download.bugsee.com/sdk/ios/dynamic/Bugsee.json"

To use Bugsee as Fat framework:

Run the following commands to update the library.

carthage update

Drag Bugsee.framework from Carthage/Build/iOS to your project's Frameworks, Libraries, and Embedded Content section in XCode

Add to Embedded field

On your application targets’ Build Phases settings tab, click the + icon and choose New Run Script Phase. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:

/usr/local/bin/carthage copy-frameworks

Add the paths to the frameworks you want to use under “Input Files”, e.g.:

$(SRCROOT)/Carthage/Build/iOS/Bugsee.framework

Add the paths to the copied frameworks to the “Output Files”, e.g.:

$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Bugsee.framework

The result must look similar to the one shown below. If you have additional frameworks managed by Carthage your list of input and output files may vary.

Copy frameworks script

To use Bugsee as XCFramework (starting 1.28.4):

Run the following commands to update the library.

carthage update --use-xcframeworks

Drag Bugsee.xcframework from Carthage/Build to your project's Frameworks, Libraries, and Embedded Content section in XCode.

For more information refer to Carthage Documentation

Manual

Download the latest version from here and extract it. Copy Bugsee.xcframework to your project by drag and dropping it into the right location:

Copy frameworks

Initialization

Make sure you launch your app with Bugsee on a real device. Bugsee iOS SDK does not work in simulator as it heavily depends on the hardware.

Locate your app delegate and initialize the framework in your application:didFinishLaunchingWithOptions method:

!Objective-C

@import Bugsee;

//...

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...other initialization code

    [Bugsee launchWithToken:@"<your_app_token>"];

    return YES;
}

!Swift

import Bugsee

//...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // ...other initialization code

    Bugsee.launch(token:"<your_app_token>")

    return true
}

Debug builds

If you want to build and enable Bugsee only in debug builds, there are few things you need to do.

The proper file in your Podfile to only enable it in debug builds is

Add the following line to your project's Podfile

pod 'Bugsee', :configurations => ['Debug']

Then you have to wrap every reference to Bugsee in your code with #ifdef DEBUG as the following example shows:

#ifdef DEBUG
#import <Bugsee/Bugsee.h>
#endif

...

#ifdef DEBUG
[Bugsee launchWithToken:@"<your_app_token>"];
#endif

TestFlight builds

It makes sense in some cases to enable Bugsee on builds distributed through Testflight but keep it disabled on the ones distributed through App Store. There is an easy way to detect a TestFlight build at runtime. You might come up with more complex use case where Bugsee is enabled both for TestFlight and for Release but with different configuration options, the example below shows a simple case of completely disabling it in the production build.

Application crashes can be intercepted by system instead of Bugsee for builds installed via TestFlight. You can disable "Share With App Developers" system option on test devices in Settings > Privacy > Analytics & Improvements.

!Objective-C

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...other initialization code

    if ([[[[NSBundle mainBundle] appStoreReceiptURL] lastPathComponent] isEqualToString:@"sandboxReceipt"]) {
        // We are in TestFlight, enable Bugsee!
        [Bugsee launchWithToken:@"<your_app_token>"];
    }

    return YES;
}

!Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // ...other initialization code

    let isRunningTestFlightBeta = Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt"
    if isRunningTestFlightBeta {
        Bugsee.launch(token:"<your_app_token>")
    }

    return true
}

Publishing to App Store

Starting with Bugsee iOS SDK 2.1.0 it is not required to clean the extra data before the App Store submission.

If you plan to publish your application to App Store, one additional step is required. It will trigger the stripping of extra data during build to prevent submission rejection. Follow the steps below to do that:

  • Add an extra "Run Script" build phase to your project

Build phase

  • Paste the following script into it

!Non-SPM installation

SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'BugseeClean' | head -1)
if [ ! "${SCRIPT_SRC}" ]; then
echo "Error: BugseeClean script not found."
exit 1
fi
/usr/bin/python "${SCRIPT_SRC}"

!SPM

This step is not necessary with Bugsee Swift Package.