Bug Reporting

If you experience a bug or crash you believe is related to PSPDFKit, please let us know.

Writing an SDK is hard. We need to interact with both platform frameworks (e.g. Apple, Google) and your application. There are many potential edge cases depending upon the app you’re building and the way you call our API. We have a large test suite and regularly write about testing on our blog, yet there will always be bugs. We usually have a fast turnaround time on issues, but there are several ways we can make the process of reproducing and fixing bugs more efficient.

We assume you’re using the latest version of Xcode and the latest version of the PSPDFKit SDK. If you aren’t, please update first and verify that the bug still exists — thanks!

Checklist for Sending a Crash Report

  • Send a symbolicated stack trace. This needs .dSYM file integration and bitcode disabled.

  • Tell us about the crash rate. Is it a single crash? What percentage of users is affected?

  • Send us steps to reproduce the issue, if possible. If you can’t reproduce the issue — for example, if the bug was reported by one of your customers or captured via a crash reporting solution — please mention this as well. If the reproduction steps are a bit fuzzy, try to outline them as best as you can. Often, a video of the procedure that triggers the issue can help us too.

  • Attach application and system logs to your crash reports if possible. This makes finding the reason much easier.

  • Please don’t send screenshots of your code. Either send a runnable sample project or a code snippet as text.

  • If you have a sample project that can reproduce the crash, we can fix it.

  • Crashes in our SDK can originate from our code, your code, vendor code, or platform provider code. It isn’t feasible, nor is it possible, to act on every crash report we receive. However, we do our best in offering a stable and reliable software product, and therefore also constantly monitor and analyze crash reports from our own PDF Viewer apps as well.

Depending upon the category of the problem, there are various options that work best for reporting. Keep reading to find out more.

Incorrect/Partial Rendering

If there’s a PDF that doesn’t render correctly, please send us the file. Before submitting it, you should verify that the latest version of Adobe Acrobat renders the file correctly. We go to extreme lengths to ensure that even partly broken files are rendered as accurately as possible.

Additionally, you should let us know which particular device and OS you’ve tested with, as different devices and versions might have different settings and fonts installed.

API Issues

  • Send us a small, runnable example project that demonstrates the issue. You can start a new project or use one of the samples we provide as a base. Often, it also helps to first try a particular issue with the Catalog sample project (which you get in the PSPDFKit Portal as part of the download). This is because it can tell us if the issue occurs with our samples as well, or only in combination with your app.

  • Send us the entire project. Sometimes an issue is based on a complex set of conditions and you may have problems isolating them in a smaller sample project. In that case, we also accept the complete project as a last resort. As part of the license agreement, we have a standard NDA that covers such software exchanges, and we’ll destroy any material we’ve received once the issue has been resolved. Since projects are usually large, a link to a ZIP file uploaded via Dropbox works best. Please also send a demo user account if one is required.

Crashes

To allow Xcode and iTunes Connect/TestFlight to symbolicate crash log files, integrate PSPDFKit into your project using Swift Package Manager or CocoaPods, or do it manually for automatic .dSYM support. Apple has a great guide, Diagnosing Issues Using Crash Reports and Device Logs, which is useful for learning more about crash logs in general.

We recommend adding logging to your crash reports to better understand why something isn’t working as intended.

Understanding Crashes and Crash Logs from WWDC 2018 is another great resource.

Crash Logs on Local Devices

To view crash logs on your iOS device, plug it in. Then, in Xcode, go to Window > Devices > View Device Logs. Select the crash you want to export, right-click, select Export Log, and send us this file. (If you haven’t opened this window for some time, symbolication might take a while, so please wait until all logs are processed before sending.)

A typical crash log looks like this. We need the complete, unmodified file to symbolicate numbers back to symbols so that we can understand and fix the crash:

Incident Identifier: 04D56C20-DC56-47D2-92AA-465EB5190548
CrashReporter Key:   c6799642fc0e394b6da37c712fa22669567ceb5d
Hardware Model:      iPhone8,2
Process:             Facebook [248]
Path:                /private/var/containers/Bundle/Application/CE3A5C58-5E69-47A7-B2DB-363CEAA97114/Facebook.app/Facebook
Identifier:          com.facebook.Facebook
Version:             28674375 (54.0)
Code Type:           ARM-64 (Native)
Parent Process:      launchd [1]

Date/Time:           2016-05-04 10:42:11.11 +0200
Launch Time:         2016-05-03 23:51:36.36 +0200
OS Version:          iOS 9.3.2 (13F68)
Report Version:      105

Exception Type:  EXC_BREAKPOINT (SIGTRAP)
Exception Codes: 0x0000000000000001, 0x00000001817ae93c
Triggered by Thread:  31

Filtered syslog:
None found

Global Trace Buffer (reverse chronological seconds):
0.413070     AppleJPEG                 	0x00000001832570c0 [0x12a83f200] Options: 720x540 [FFFFFFFF,FFFFFFFF] 00025060
0.413070     AppleJPEG                 	0x0000000183256f78 [0x12a83f200] Decoding: C2 0x02D0021C 0x00003842 0x22111100 0x00000000 70466



Thread 0 name:  Dispatch queue: com.apple.main-thread
Thread 0:
0   libsystem_kernel.dylib        	0x0000000181374fd8 mach_msg_trap + 8
1   libsystem_kernel.dylib        	0x0000000181374e54 mach_msg + 72
2   CoreFoundation                	0x00000001817acc60 __CFRunLoopServiceMachPort + 196
3   CoreFoundation                	0x00000001817aa964 __CFRunLoopRun + 1032
4   CoreFoundation                	0x00000001816d4c50 CFRunLoopRunSpecific + 384
5   GraphicsServices              	0x0000000182fbc088 GSEventRunModal + 180
6   UIKit                         	0x00000001869be088 UIApplicationMain + 204
7   Facebook                      	0x00000001001e03b4 0x10004c000 + 1655732
8   Facebook                      	0x00000001000ba4a4 0x10004c000 + 451748
9   libdyld.dylib                 	0x00000001812728b8 start + 4

Crash Logs on iTunes Connect/TestFlight

Crashes collected via iTunes Connect can be viewed either online or directly in Xcode via the Crashes Organizer (Window > Organizer > Crashes). Control-click a crash report, choose Show in Finder, and send the selected files to us.

Crash Logs during Development

Sometimes things will crash while you’re developing in Xcode. Use the bt all command in the lldb debugging console to print the stack traces of all threads — this works better than a screenshot. Often, we throw an assertion against incorrect API use. If you have an exception breakpoint set, you won’t see the contents of this message right away. Press the Continue button until the application terminates to see the termination reason. In some cases, this is enough to understand the issue and fix the incorrect use.

Xcode won’t automatically use the .dSYM file, even if your setup is correct, so stack traces from PSPDFKit will, in most cases, be incorrect/misleading. You can always pick up the original crash log from ~/Library/Logs/DiagnosticReports/ (this is the default location for crashes on macOS, including ones from the iOS Simulator).

Manually Symbolicating a Crash Report

If you have a matching binary, crash log, and .dSYM file, you can symbolicate the crash log manually using Xcode’s symbolicatecrash or atos tools.