Skip to main content

Migrating from 6.x to 7.x

note

This guide targets the 7.x release line, currently in beta. If you are setting up a brand-new project, start from the 7.x installation guide instead. For 6.x installs, see the 6.x installation guide.

This guide walks through every public-API change between Bugsee iOS SDK 6.x and 7.x.

TL;DR

7.x keeps the shape of the 6.x API, but much of it moved. Many 6.x methods still exist under a new name, the option keys changed, feedback left the core framework for its own package, and the minimum deployment target is now iOS 15. You will need code changes; a drop-in version bump is not possible.

1. Requirements and dependency​

1.1 Deployment target​

The minimum deployment target moves from iOS 12 to iOS 15. Raise it in your target's build settings before upgrading.

7.x also ships tvOS and visionOS slices:

Platform6.x7.x
iOS12.015.0
tvOS(not shipped)15.0
visionOS(not shipped)1.0

Simulator slices are built without the native crash reporter, exactly as in 6.x — run on a real device to exercise crash capture.

1.2 Dependency​

7.x is distributed through Swift Package Manager. The repository is unchanged — https://github.com/bugsee/spm — so an existing integration only needs its dependency rule changed to Exact Version with the 7.x beta tag. See the 7.x installation guide for details.

2. Option keys​

Check this before anything else

Option names are no longer the same text behind the scenes. If you typed them out as plain strings — @"VideoEnabled", @"ShakeToReport" — your app still builds and still runs, but Bugsee no longer recognizes them and uses its defaults instead.

2.1 Detection​

6.x7.x
BugseeCrashReportKeyBugseeOptionDetectAndReportCrash
BugseeAppLaunchCrashDetectionKeyBugseeOptionDetectAndReportEarlyCrash
BugseeDetectAppExitKeyBugseeOptionDetectAndReportExit
BugseeKillDetectionKey(removed)
(not available)BugseeOptionDetectAndReportAnomaly
(not available)BugseeOptionDetectAndReportHang
(not available)BugseeOptionDetectAndReportHangFairLevel
(not available)BugseeOptionDetectAndReportHangMediumLevel
(not available)BugseeOptionDetectAndReportHangSevereLevel
(not available)BugseeOptionDetectAndReportHttpErrors
(not available)BugseeOptionDetectAndReportMainThreadMisuse
(not available)BugseeOptionDetectCrashFillEmptyExceptionStacks
(not available)BugseeOptionDetectCrashSwiftAsyncStackTraces
(not available)BugseeOptionDetectFrustration

BugseeKillDetectionKey and the BugseeOptions.killDetection property are removed, and so is BugseeOptionDetectAndReportKill from the earlier 7.x betas. Out-of-memory kills are reported through BugseeOptionDetectAndReportExit, which is on by default (see §3).

2.2 Capture​

6.x7.x
BugseeCaptureAVPlayerKeyBugseeOptionCaptureAVPlayer
BugseeMonitorBluetoothStatusKeyBugseeOptionCaptureBluetoothStatus
BugseeEnableMachExceptionsKeyBugseeOptionCaptureCrashHandlerType (see below)
BugseeMonitorDiskSpaceKeyBugseeOptionCaptureDiskSpace
BugseeCaptureLogsKeyBugseeOptionCaptureLogs
BugseeMonitorNetworkKeyBugseeOptionCaptureNetwork
BugseeMaxNetworkBodySizeKeyBugseeOptionCaptureNetworkBodySizeLimit
BugseeSanitizeNetworkDataKeyBugseeOptionCaptureNetworkUseDefaultSanitizer
BugseeCaptureOSLogsKeyBugseeOptionCaptureOSLogs
BugseeEnableOnDeviceSymbolicationKeyBugseeOptionCaptureOnDeviceSymbolication
BugseeScreenshotEnabledKeyBugseeOptionCaptureScreenshot
BugseeStatusBarInfoKeyBugseeOptionCaptureStatusBarInfo
BugseeVideoEnabledKeyBugseeOptionCaptureVideo
BugseeCaptureVideoAdaptiveKeyBugseeOptionCaptureVideoAdaptive
BugseeFrameRateKeyBugseeOptionCaptureVideoFrameRate
BugseeMaxFrameRateKeyBugseeOptionCaptureVideoMaxFramerate
BugseeMinFrameRateKeyBugseeOptionCaptureVideoMinFramerate
BugseeVideoScaleKeyBugseeOptionCaptureVideoScale
BugseeViewHierarchyEnabledKeyBugseeOptionCaptureViewHierarchy
BugseeMonitorWebSocketKeyBugseeOptionCaptureWebSocket
(not available)BugseeOptionCaptureBreadcrumbs
(not available)BugseeOptionCaptureBreadcrumbsExtras
(not available)BugseeOptionCaptureCameraPreview
(not available)BugseeOptionCaptureCrashSignals (see below)
(not available)BugseeOptionCaptureDeviceAndNetworkNames
(not available)BugseeOptionCaptureLogsLevel
(not available)BugseeOptionCaptureNetworkBodyWithoutType
(not available)BugseeOptionCaptureNetworkOnLaunch
(not available)BugseeOptionCaptureSampleBufferDisplayLayer
(not available)BugseeOptionCaptureScreenshotScale
(not available)BugseeOptionCaptureVideoPrivacyBlur
(not available)BugseeOptionCaptureVideoQuality
(not available)BugseeOptionCaptureWebViewAdvanced
(not available)BugseeOptionCaptureWebViewReportTrigger

BugseeEnableMachExceptionsKey and the BugseeOptions.enableMachExceptions property are removed. The crash handler is chosen with BugseeOptionCaptureCrashHandlerType (BugseeOptions.crashHandlerType), which takes a BugseeCrashHandlerType:

6.x7.xWhat Bugsee installs
BugseeEnableMachExceptionsKey: NO (6.x default)BugseeCrashHandlerTypeBSD (.bsd)BSD signal handlers
BugseeEnableMachExceptionsKey: YESBugseeCrashHandlerTypeMach (.mach)A Mach exception handler, plus a BSD signal handler for SIGABRT. Other signals raised by software (raise(), kill()) are not reported
(not available)BugseeCrashHandlerTypeMachAndBSD (.machAndBSD, 7.x default)Both, so hardware faults and signals raised by software are reported

tvOS always uses BSD signal handlers, whatever the value.

The removed key is ignored if it is still passed, including as a plain string (@"BugseeEnableMachExceptions", @"enableMachExceptions", @"com.bugsee.option.capture.mach-exceptions"). Bugsee logs a warning to the console the first time it sees one.

BugseeOptionCaptureCrashSignals (BugseeOptions.crashSignals) is new. It chooses which fatal signals Bugsee intercepts on iOS, tvOS and visionOS. Combine BugseeCrashSignals values:

7.xSwiftSignal
BugseeCrashSignalABRT.abrtSIGABRT: abort(), failed assertions, uncaught exceptions
BugseeCrashSignalSEGV.segvSIGSEGV: invalid memory access
BugseeCrashSignalBUS.busSIGBUS: misaligned or otherwise invalid memory access
BugseeCrashSignalILL.illSIGILL: illegal instruction
BugseeCrashSignalFPE.fpeSIGFPE: arithmetic exception
BugseeCrashSignalTRAP.trapSIGTRAP: breakpoint or trap instruction, including Swift runtime traps
BugseeCrashSignalsAll.allEvery signal above
BugseeCrashSignalsDefault.defaultBugsee chooses (default)

With the default, Bugsee intercepts every signal, except that the Xamarin and .NET SDKs leave out SIGSEGV and SIGBUS: the .NET runtime turns them into NullReferenceException. Any other value is used as given, so list every signal you want. BugseeCrashSignalsDefault works only on its own, not combined with other values.

BugseeOptions *options = [BugseeOptions defaultOptions];
options.crashSignals = BugseeCrashSignalABRT | BugseeCrashSignalILL | BugseeCrashSignalTRAP;

[Bugsee launchWithToken:@"<your_app_token>" options:options];
  • A bad memory access arrives as either SIGSEGV or SIGBUS, depending on the fault. With BugseeCrashHandlerTypeMach or BugseeCrashHandlerTypeMachAndBSD, it is intercepted if either of the two is selected. With BugseeCrashHandlerTypeBSD, and always on tvOS, only the selected signal is intercepted, so select both to catch every bad memory access. Leave both out to ignore bad memory accesses.
  • Leaving out SIGABRT also stops uncaught Objective-C exceptions from being reported, because they end in abort().
  • With BugseeCrashHandlerTypeMach, SIGABRT is the only signal raised by software that Bugsee reports. The other selected signals are reported only as hardware faults.
  • With no signals selected (BugseeCrashSignalsNone), Bugsee reports no crashes and no uncaught exceptions, and logs a warning to the console.

2.3 Reporting​

6.x7.x
BugseeDefaultBugPriorityKeyBugseeOptionReportingDefaultBugPriority
BugseeDefaultCrashPriorityKeyBugseeOptionReportingDefaultCrashPriority
BugseeDefaultErrorPriorityKeyBugseeOptionReportingDefaultErrorPriority
BugseeScreenshotToReportKeyBugseeOptionReportingTriggerByScreenshot
BugseeShakeToReportKeyBugseeOptionReportingTriggerByShake
BugseeReportDescriptionRequiredKeyBugseeOptionReportingUIDescriptionRequired
BugseeReportEmailRequiredKeyBugseeOptionReportingUIEmailRequired
BugseeReportLabelsEnabledKeyBugseeOptionReportingUILabelsEnabled
BugseeReportLabelsRequiredKeyBugseeOptionReportingUILabelsRequired
BugseeReportPrioritySelectorKeyBugseeOptionReportingUIPrioritySelectorEnabled
BugseeStyleKeyBugseeOptionReportingUIStyle
BugseeReportSummaryRequiredKeyBugseeOptionReportingUISummaryRequired

2.4 Configuration​

6.x7.x
BugseeBuildTargetKeyBugseeOptionConfigBuildTarget
BugseeBuildTypeKeyBugseeOptionConfigBuildType
BugseeMaxRecordingTimeKeyBugseeOptionConfigDuration
BugseeMaxDataSizeKeyBugseeOptionConfigMaxDataSize
BugseeWifiOnlyUploadKeyBugseeOptionConfigWifiOnlyUpload
(not available)BugseeOptionConfigNotifyFlushDelay

2.5 Performance​

6.x7.x
BugseePerformanceAdaptiveSamplingKeyBugseeOptionPerformanceAdaptiveSampling
BugseePerformanceMonitoringKeyBugseeOptionPerformanceMonitoring
BugseePerformanceSampleRateKeyBugseeOptionPerformanceSampleRate

2.6 Options that have no BugseeOptions property​

Most of the settings 7.x adds exist only as keys. Reach them through the dictionary launch overload, or fold them into a BugseeOptions object with updateLaunchOptions::

BugseeOptions *options = [BugseeOptions defaultOptions];
options.videoEnabled = YES;

[options updateLaunchOptions:@{
    BugseeOptionDetectAndReportHang : @YES,
    BugseeOptionCaptureBreadcrumbs  : @YES,
}];

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

3. Defaults that changed​

Nine registered defaults changed. Eight were realigned with the Android SDK, so the same option means the same thing on both platforms. The ninth, the crash handler type, is iOS's own. Six of them are values a 6.x app is running today.

Option6.x7.x
BugseeOptionReportingTriggerByShakeNOYES
BugseeOptionReportingTriggerByScreenshotYESNO
BugseeOptionDetectAndReportExitNOYES
BugseeOptionDetectAndReportEarlyCrashNOYES
BugseeOptionCaptureVideoAdaptiveNOYES
BugseeOptionCaptureCrashHandlerTypeBSDMachAndBSD (iOS and visionOS)
Nothing tells you this happened

These are behavioral changes, not compile-time ones. Nothing fails to build and nothing warns at runtime. An app that never set these options gets the new behavior the moment it upgrades.

The consequence to plan for: taking a screenshot no longer opens the report dialog, and shaking the device now does. If your users were taught the screenshot gesture, set both keys explicitly.

With BugseeCrashHandlerTypeMachAndBSD, Bugsee installs a Mach exception handler and BSD signal handlers, so it also reports signals raised by software (raise(), kill()). tvOS always uses BSD signal handlers. See §2.2 for the three handler types.

To keep 6.x behavior, pin all six:

NSDictionary *options = @{
    BugseeOptionReportingTriggerByShake:      @NO,
    BugseeOptionReportingTriggerByScreenshot: @YES,
    BugseeOptionDetectAndReportExit:          @NO,
    BugseeOptionDetectAndReportEarlyCrash:    @NO,
    BugseeOptionCaptureVideoAdaptive:         @NO,
    BugseeOptionCaptureCrashHandlerType:      @(BugseeCrashHandlerTypeBSD),
};

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

BugseeOptionCaptureVideoAdaptive is a deliberate difference from Android, not an oversight: iOS ships adaptive capture as opt-out because it was validated on device here, while Android keeps it opt-in.

Three more defaults changed but have no 6.x counterpart to contradict: BugseeOptionConfigNotifyFlushDelay (1000 → 0), BugseeOptionCaptureBreadcrumbsExtras (YES → NO), and BugseeOptionCaptureNetworkBodySizeLimit, whose Debug-only 120 KB override is gone — release builds always used 20480, which is the documented value.

4. Launching and lifecycle​

4.1 Dictionary launch has a new Swift label​

In 6.x both launch overloads carried the Swift name launch(token:options:) and Swift picked one by argument type. In 7.x the dictionary overload is spelled out:

6.x (Swift)7.x (Swift)
Bugsee.launch(token:options:) (dictionary)Bugsee.launch(token:dictionaryOptions:)
Bugsee.launch(token:options:) (BugseeOptions)Bugsee.launch(token:options:)
Bugsee.relaunch(options:) (dictionary)Bugsee.relaunch(dictionaryOptions:)
Bugsee.relaunch(options:) (BugseeOptions)Bugsee.relaunch(options:)

Objective-C selectors are unchanged: launchWithToken:andOptions: and launchWithToken:options:.

4.2 pause and resume are gone​

+[Bugsee pause] and +[Bugsee resume] are removed.

Blackout is not a drop-in replacement

6.x pause suspended video and the loggers. 7.x blackout suppresses only what describes the screen — logs, network events and traces keep being captured. If you relied on pause to stop all capture, use +[Bugsee stop:] and launch again afterwards.

4.3 New: observing SDK status​

Bugsee finishes starting up in the background, so launchWithToken: returns a moment before recording is actually live. 7.x lets you see when that moment passes.

// BugseeStatusStopped / Launching / Launched / Stopping
if ([Bugsee sharedInstance].status == BugseeStatusLaunched) { /* ... */ }

// Or observe every transition, on the main thread:
- (void)bugseeDidChangeStatus:(BugseeStatus)status {
    NSLog(@"Bugsee status: %ld", (long)status);
}

The existing launched property still works, but it is NO during the short Launching window. Prefer status, or the started: completion block, for launch sequencing.

4.4 New: relaunch with no arguments​

+[Bugsee relaunch] restarts with the current app token and default options.

4.5 Deleting collected data​

The 6.x call keeps its Objective-C selector. In Swift it is renamed from deleteCollectedData(completion:) to deleteCollectedDataOnDevice(completion:). It deletes everything Bugsee has collected on the device: the recording, reports not uploaded yet (their uploads are cancelled), crashes not reported yet and the performance baselines learned by anomaly detection.

7.x adds a second form that deletes less. deleteCollectedDataOnDevice:completion: always deletes the recording and keeps the reports waiting for upload. Pass YES to also delete the data already set aside for reports that are not assembled yet.

// 6.x and 7.x — deletes everything
[Bugsee deleteCollectedDataOnDevice:^(BOOL success) { /* ... */ }];

// 7.x only — keeps the reports waiting for upload
[Bugsee deleteCollectedDataOnDevice:YES completion:^(BOOL success) { /* ... */ }];

For both forms:

  • Stop recording with +[Bugsee stop:] first, as in 6.x. Otherwise nothing is deleted and the completion receives NO.
  • The completion is called on the main thread once the deletion has finished, with YES if the data was deleted.
  • A launch called before the deletion has finished starts after it, unless you call stop before it starts.

4.6 BugseeDelegate methods have new Swift names​

Every BugseeDelegate method now declares its Swift name. The Objective-C selectors are unchanged; the Swift names Xcode derived from them in 6.x are not.

An old name is not an error

The delegate methods are optional, so a Swift implementation that still uses the 6.x name compiles and is simply never called: the filter stops filtering, the attachments stop being attached. Rename every implementation.

6.x (Swift)7.x (Swift)
bugseeFilterNetworkEvent(_:completionHandler:)bugsee(filterNetworkEvent:completionHandler:)
bugseeFilterLog(_:completionHandler:)bugsee(filterLog:completionHandler:)
bugseeAttachments(for:)bugsee(attachmentsFor:)
bugseeAttachments(for:completionHandler:)bugsee(attachmentsFor:completionHandler:)
bugseeLifecycleEvent(_:)bugsee(lifecycleEvent:)
bugseeAddFieldsBeforeReportCreated()bugseePrepareReportFields()
bugseeAddFieldsBeforeReportCreated(_:)bugseePrepareReportFields(completion:)
bugseeCheckFields(afterReportCreated:)bugsee(finalizeReportFields:)
bugseeCheckFields(afterReportCreated:completionHandler:)bugsee(finalizeReportFields:completionHandler:)
(not available)bugsee(didChangeStatus:)

5. Feedback moved to its own package​

Feedback is no longer part of the core framework. Every 6.x feedback symbol is removed, and the feature ships as a separate Swift package, BugseeFeedback, layered on top of the core SDK.

Package coordinates

Add https://github.com/bugsee/feedback-spm with the Exact Version rule, at the same version as the core SDK. Each BugseeFeedback release requires that core version exactly.

5.1 API mapping​

6.x7.x
+[Bugsee showFeedbackController][BugseeFeedback.shared showFeedbackUI]
+[Bugsee setDefaultFeedbackGreeting:][BugseeFeedback.shared setGreeting:]
-[BugseeDelegate bugsee:didReceiveNewFeedback:]-[BugseeFeedbackListener onNewMessagesReceived:]
(not available)-[BugseeFeedbackListener onNewMessageSent:]
(not available)[BugseeFeedback.shared setListener:]

5.2 Register the extension​

The package registers itself with the SDK on load. You can also register it explicitly:

@import BugseeFeedback;

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

5.3 Rewrite the call sites​

Call the feature through BugseeFeedback.shared.

// 6.x
[Bugsee showFeedbackController];
[Bugsee setDefaultFeedbackGreeting:@"How can we help?"];

// 7.x
[BugseeFeedback.shared showFeedbackUI];
[BugseeFeedback.shared setGreeting:@"How can we help?"];

5.4 New-message callbacks​

The bugsee:didReceiveNewFeedback: delegate method is replaced by a dedicated listener on the extension.

// 7.x — your type conforms to BugseeFeedbackListener
[BugseeFeedback.shared setListener:self];

5.5 The extension registry is public​

registerExt(_:) and ext(_:) are the general mechanism for optional 7.x modules, not a feedback-specific hook. Feedback is the first module to use it.

6. Event filters​

6.1 removeNetworkEventFilter is gone​

All three filter setters now accept nil to remove the filter.

// 6.x
[Bugsee removeNetworkEventFilter];

// 7.x
[Bugsee setNetworkEventFilter:nil];

6.2 New: a block-based log filter​

6.x could only filter console logs through the bugseeFilterLog:completionHandler: delegate method. 7.x adds setLogEventFilter:, which runs alongside it.

[Bugsee setLogEventFilter:^(BugseeLogEvent *event, BugseeLogFilterDecisionBlock decision) {
    if ([event.text containsString:@"password"]) {
        decision(nil);   // drop it
        return;
    }
    decision(event);
}];

6.3 New: a breadcrumb filter​

Breadcrumbs are new in 7.x, and setBreadcrumbFilter: is the only filter they pass through. See §9.3.

7. Manual reports​

7.1 showReportController is now showReportDialog​

6.x7.x
showReportControllershowReportDialog
showReportControllerWithSummary:description:severity:showReportDialogWithSummary:description:severity:
showReportControllerWithSummary:description:severity:labels:showReportDialogWithSummary:description:severity:labels:
(not available)showReportDialogWithSummary:description:

7.2 includeVideo: overloads and logError:labels: are gone​

uploadWithSummary:…:includeVideo: loses its last parameter. Drop the argument; the shorter overload already exists in 6.x. logError:labels:includeVideo: and logError:labels: are gone too: call logError:, and add labels in bugseeAttachmentsForReport: (see §7.5 for how far such a label reaches).

// 6.x
[Bugsee uploadWithSummary:@"s" description:@"d" severity:BugseeSeverityHigh
                   labels:nil includeVideo:YES];

// 7.x
[Bugsee uploadWithSummary:@"s" description:@"d" severity:BugseeSeverityHigh labels:nil];

// 6.x
[Bugsee logError:error labels:@[@"checkout"]];

// 7.x: labels in bugseeAttachmentsForReport:, see §7.5
[Bugsee logError:error];

7.x also adds a two-argument uploadWithSummary:description:.

7.3 uploadReport: is upload(_:) in Swift​

The Objective-C selector uploadReport: is unchanged; only its Swift name moves from Bugsee.uploadReport(_:) to Bugsee.upload(_:). A completion: overload is new.

7.4 The report the delegate receives is live​

In 6.x, the BugseeReport passed to bugseeAttachmentsForReport: carried three properties: type, severity and labels. In 7.x it is a handle on the report about to be uploaded, and whatever you change on it is what gets uploaded.

  • type is read-only. The trigger decides it: BugseeReportTypeBug, BugseeReportTypeCrash or BugseeReportTypeError.
  • labels is no longer nullable. Assign an empty array to clear them, or call clearLabels.
  • There is no public initializer. Bugsee creates the object; do not keep it past the delegate call.
  • severity accepts only BugseeSeverityLow…BugseeSeverityBlocker (1–5). Any other value is ignored and logged, and the current severity is kept. The same rule applies to the severity in the BugseeReportFields your delegate returns, and to the BugseeOptionReportingDefault*Priority options: an out-of-range default leaves the report's severity unset.

New on the report: reportId, summary, reportDescription, email, its attributes (getAttribute:, setAttribute:withValue:, removeAttribute:, clearAllAttributes), addLabel: / addLabels: / clearLabels, and addAttachment: / clearAttachments. Attachments added on the report share the delegate's budget of three attachments of at most 3 MB each.

- (NSArray<BugseeAttachment *> *)bugseeAttachmentsForReport:(BugseeReport *)report {
    [report addLabel:@"beta"];
    [report setAttribute:@"plan" withValue:@"pro"];
    return @[];
}

7.5 BugseeExceptionLoggingOptions is gone​

logException takes the exception domain and the number of frames to skip as parameters, as on Android 7.x. BugseeExceptionLoggingOptions, BugseeMergingRulesSkipFramesKey and both options: overloads are removed.

6.x7.x
logException:options:completion: with nil optionslogException:completion:
logException:reason:options:completion: with nil optionslogException:reason:completion:
logException:options:completion: with optionslogException:domain:skipFrames:completion:
logException:reason:options:completion: with optionslogException:reason:domain:skipFrames:completion:
exceptionDomaindomain:
mergingRules[BugseeMergingRulesSkipFramesKey]skipFrames:
labelsaddLabels: on the report in bugseeAttachmentsForReport: — see §7.4
includeVideo— leaving the video out of a single report is not supported

A 6.x call that passed an options object without setting includeVideo to YES filed its report without video. In 7.x the same call files it with video.

domain is recorded with the report. skipFrames is how many top frames of the stack recorded for the report are left out of its signature, which groups reports into issues; a negative value counts as 0.

// 6.x
BugseeExceptionLoggingOptions *options = [BugseeExceptionLoggingOptions new];
options.exceptionDomain = @"Payments";
options.labels = @[@"checkout"];
options.mergingRules = @{BugseeMergingRulesSkipFramesKey : @1};
[Bugsee logException:exception options:options completion:nil];

// 7.x
[Bugsee logException:exception domain:@"Payments" skipFrames:1 completion:nil];

// 7.x labels, in your BugseeDelegate
- (NSArray<BugseeAttachment *> *)bugseeAttachmentsForReport:(BugseeReport *)report {
    if ([report.type isEqualToString:BugseeReportTypeError]) {
        [report addLabels:@[@"checkout"]];
    }
    return @[];
}

The delegate is asked about every report. type tells an error report from a bug or crash report, but not a logException report from a logError report or from an error report Bugsee files on its own, so a label added this way goes on all of them.

On simulators and Mac Catalyst logException files nothing; its completion is still called.

8. Privacy and secure areas​

8.1 Blackout​

New in 7.x. Blackout suppresses every capture that describes the screen — video (a black placeholder frame), the report screenshot, touch and gesture recording, and the view hierarchy. Logs, network events and traces keep flowing.

[Bugsee startBlackout];
// ... sensitive flow ...
[Bugsee endBlackout];

BOOL hidden = [Bugsee isBlackout];

Two lifecycle events report the transitions: BugseeLifecycleEventBlackoutStarted and BugseeLifecycleEventBlackoutEnded.

8.2 Secure views​

setView:asHidden: is split into two explicit methods.

// 6.x
[Bugsee setView:myView asHidden:YES];
[Bugsee setView:myView asHidden:NO];

// 7.x
[Bugsee addSecureView:myView];
[Bugsee removeSecureView:myView];

isViewHidden: is removed with no replacement. The UIView.bugseeProtectedView property and addSecureWebView: are unchanged.

8.3 Secure rectangles renamed​

Rect becomes Rectangle throughout. The ten-rectangle limit is unchanged, and so are the coordinates: points, in the screen's coordinate space. Two things behave differently:

  • Touches inside a rectangle are now dropped from the report, as they already were for secure views.
  • With several of the app's windows on the screen (iPad Split View or Stage Manager, iPhone Duo side by side), every window is recorded. A rectangle measured in a window that does not start at the screen's top-left corner must be converted to screen coordinates before you add it.
6.x7.x
addSecureRect:addSecureRectangle:
removeSecureRect:removeSecureRectangle:
removeAllSecureRectsremoveAllSecureRectangles
getAllSecureRectsgetAllSecureRectangles
setInternalSecureRectangles:(removed)

9. New capabilities​

9.1 User identity replaces email​

setEmail: recorded an email address. 7.x records an arbitrary user identifier instead — same storage, wider meaning.

// 6.x
[Bugsee setEmail:@"user@example.com"];
NSString *email = [Bugsee getEmail];
[Bugsee clearEmail];

// 7.x
[Bugsee setUserIdentifier:@"user@example.com"];
NSString *identifier = [Bugsee getUserIdentifier];
[Bugsee clearUserIdentifier];

9.2 Reading all attributes​

7.x adds getAllAttributes, which returns every attribute currently set.

NSDictionary<NSString *, id> *all = [Bugsee getAllAttributes];

9.3 Breadcrumbs​

New in 7.x. The SDK collects breadcrumbs automatically once BugseeOptionCaptureBreadcrumbs is enabled, and you can add your own. Build the breadcrumb through the SDK's factory, then record it.

id<BGSBreadcrumb> crumb = [[Bugsee getExchangeFactory] createBreadcrumb];
crumb.category = @"checkout";
crumb.message  = @"Coupon applied";
crumb.type     = @"user";
[crumb setDataValue:@"SUMMER25" forKey:@"code"];

[Bugsee addBreadcrumb:crumb];
Network filters do not reach breadcrumbs

setBreadcrumbFilter: is the only filter breadcrumbs pass through. A URL your setNetworkEventFilter: (or bugseeFilterNetworkEvent:) drops or rewrites still appears in the breadcrumb trail unless you repeat the rule in the breadcrumb filter. The built-in query-parameter sanitizer does apply to breadcrumb URLs; a custom filter does not.

[Bugsee setBreadcrumbFilter:^(id<BGSBreadcrumb> crumb,
                              BugseeBreadcrumbFilterDecisionBlock decision) {
    if ([crumb.category isEqualToString:@"internal"]) {
        decision(nil);   // drop it
        return;
    }
    decision(crumb);
}];

9.4 Notification relay​

New in 7.x. notify sends a lightweight notification straight to the app's configured messaging integrations, bypassing the bug-report pipeline — no video, logs or events are attached. Notifications are persisted offline and uploaded in batches.

There is no option to enable or disable it; it is available once the SDK has launched, and calls made before launch are ignored. title must be non-empty.

[Bugsee notifyWithTitle:@"Checkout failed"];

[Bugsee notifyWithTitle:@"Checkout failed"
                   body:@"Payment provider returned 502"
               severity:BugseeSeverityHigh
                 fields:@{@"orderId": @"A-1721"}
                 urgent:YES];

The shorter overloads are non-urgent. BugseeOptionConfigNotifyFlushDelay (also the notifyFlushDelay property) sets the upload coalescing delay in milliseconds. The default is 0 — the notification is written to disk and posted as soon as it lands there. A positive value delays the flush so that notify calls made close together batch into one upload. Same default as Android's com.bugsee.option.config.notify-flush-delay.

10. Appearance​

+[Bugsee appearance] is renamed to +[Bugsee getAppearance]. BugseeTheme itself is unchanged — every color and string property behaves exactly as in 6.x.

reportCloseButtonColor and reportSendButtonColor are deprecated: the report screen uses the system Cancel and Done buttons.

// 6.x
[Bugsee appearance].reportBackgroundColor = UIColor.blackColor;

// 7.x
[Bugsee getAppearance].reportBackgroundColor = UIColor.blackColor;

11. Cheat sheet​

Renamed — a plain search and replace does most of these.

6.x7.x
Bugsee.appearance()Bugsee.getAppearance()
Bugsee.activeSpan()Bugsee.getActiveSpan()
registerEvent:event:
registerEvent:withParams:event:params: (params now optional)
traceKey:withValue:trace:value:
Swift Bugsee.trace(key:value:)Swift Bugsee.trace(_:value:)
registerNetworkEvent:addNetworkEvent:
registerNetworkEvent:needsToBeFiltered:addNetworkEvent:requiresFiltering:
removeNetworkEventFiltersetNetworkEventFilter:nil
showReportController*showReportDialog*
setView:asHidden:addSecureView: / removeSecureView:
addSecureRect:addSecureRectangle:
removeSecureRect:removeSecureRectangle:
removeAllSecureRectsremoveAllSecureRectangles
getAllSecureRectsgetAllSecureRectangles
setEmail: / getEmail / clearEmailsetUserIdentifier: / getUserIdentifier / clearUserIdentifier
clearAllAttributeclearAllAttributes
testExceptionCrash / testSignalCrashtestCrash
uploadWithSummary:…:includeVideo:uploadWithSummary:description:severity:labels:
logError:labels:includeVideo: / logError:labels:logError:; labels through the delegate's report — see §7.2
logException:options:completion:logException:completion: / logException:domain:skipFrames:completion: — see §7.5
logException:reason:options:completion:logException:reason:completion: / logException:reason:domain:skipFrames:completion:
BugseeExceptionLoggingOptionsdomain: / skipFrames: parameters of logException; labels through the delegate's report
Swift Bugsee.launch(token:options:) (dictionary)Swift Bugsee.launch(token:dictionaryOptions:)
Swift Bugsee.relaunch(options:) (dictionary)Swift Bugsee.relaunch(dictionaryOptions:)
Swift Bugsee.uploadReport(_:)Swift Bugsee.upload(_:)
Swift Bugsee.deleteCollectedData(completion:)Swift Bugsee.deleteCollectedDataOnDevice(completion:) — see §4.5
Swift BugseeDelegate methodsNew Swift names — see §4.6
showFeedbackController[BugseeFeedback.shared showFeedbackUI]
setDefaultFeedbackGreeting:[BugseeFeedback.shared setGreeting:]
bugsee:didReceiveNewFeedback:BugseeFeedbackListener

Removed with no direct replacement.

6.xNotes
pause / resumeClosest is startBlackout / endBlackout, which is narrower — see §4.2
getDeviceId—
accessToken—
isViewHidden:—
hideKeyboard:—
setInternalSecureRectangles:—
logAssert:withLocation: / BUGSEE_ASSERTUse logException:reason:completion:
log:level:timestamp:log:level:requiresFiltering: takes the slot but does something different — it opts the message into the log filter
setDefaultCrashPriority:BugseeOptionReportingDefaultCrashPriority at launch
setDefaultErrorPriority:BugseeOptionReportingDefaultErrorPriority at launch
setDefaultBugPriority:BugseeOptionReportingDefaultBugPriority at launch
BugseeAttachmentOverrideLabels—
BugseeOptions.captureVideoAdaptiveBugseeOptionCaptureVideoAdaptive key
  1. Raise the deployment target to iOS 15 and switch the dependency to 7.x.
  2. Fix the option names first, using the tables in §2. Do this before anything else — it is the one change Xcode cannot find for you.
  3. Check the defaults that changed (§3) and pin any your app relies on — nothing warns you about these, at build time or at runtime.
  4. Build, and work down the errors. Everything in §4 to §10 shows up as a build error, except the delegate methods' new Swift names (§4.6): rename those by hand. The cheat sheet covers most of the rest.
  5. Rewire feedback through BugseeFeedback (§5) — the largest single change, and the only one that needs a new dependency.
  6. Look at your pause calls by hand. This is the one place where the obvious replacement is not quite right — blackout keeps recording logs and network traffic.
  7. (Optional) Adopt breadcrumbs, notify, and the new detection options.

Build and run after each step — the 7.x APIs are designed to be adopted in this order.

Found an issue, typo, or wrong statement on this page? Report it now →