Bug Reporting

Writing an SDK is hard. We need to interact with both Apple’s frameworks (especially UIKit) 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 in our blog, yet there will always be bugs. We usually have a very 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 are using the latest version of Xcode and the latest version of the PSPDFKit SDK. If you are not, please update first and verify that the bug still exists — thanks!

Please do not send screenshots of your code. Either send a runnable sample project or a code snippet as text.

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

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 as part of the download in our customer portal). 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 will 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.

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 have not opened this window for some time, symbolication might take a while, so please wait until all logs are processed before sending one.)

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

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 usage. 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 in order to see the termination reason. In some cases, this is enough to understand the issue and fix the incorrect usage.

Xcode will not 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/ (the default location for crashes on macOS, including ones from the iOS Simulator).

Manually Symbolicating a Crash Report

Third-Party Crash Reporting Services

We recommend using a third-party crash reporting service instead of relying solely on iTunes Connect. This allows you to discover more issues and will lead to a more stable product and greater customer satisfaction. iTunes Connect only shows the most common crashes and is quite slow to update, whereas a third-party service will show all crash reports. There are several services; the most common ones are Crashlytics/Fabric by Google (formerly Twitter), HockeyApp/MobileCenter by Microsoft, and Bugsee, which can also record a video leading up to the crash. Additionally, there’s a comparison website to see which service has a higher success rate on stack trace symbolication.

With HockeyApp, you may extract a raw crash log via View Raw Log > Download, enabling us to perform the required symbolication manually as well. Crashlytics currently does not yet allow such a raw export, although we’ve contacted the company and it is working on such a feature.