Bug Reporting

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

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 Android Studio 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.

Incorrect/Partial Rendering

If there’s a PDF that does not 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][PSPFKit Guide Framework Size].

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.

Crashes

Stack traces that contain PSPDFKit methods contain obfuscated names of packages, classes, and methods. To allow us to quickly retrace the crash, please always send us the stack trace in plain text format, together with the PSPDFKit version number your app is using.

Obtaining Stack Traces

  • Crashes are usually emitted to logcat. Please don’t make a screenshot of a logcat view; plain text stack traces will help us investigate your problem faster.

  • If you can reproduce your crash while debugging:

    1. Add a breakpoint to the affected line.
    2. Click on the “Get thread dump” button.
    3. Click on the “Export to Text File” button in the newly opened “Dump” tab.
    4. Send us the generated file.
Generate thread dump

Third-Party Crash Reporting Services

We recommend using a third-party crash reporting service instead of relying solely on the Google Play Developer Console. This allows you to discover more issues and will lead to a more stable product and greater customer satisfaction. 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.

NDK Crash Reports

If PSPDFKit is crashing natively (i.e. inside the native libraries), please provide us with a native crash dump. You can define the path for crash dumps via PSPDFKit#setNativeCrashDumpPath and download a minidump from that path from your device using adb pull /path/to/crashDump. Dumps are in the Google Breakpad format and are also accepted by crash reporting services like Crashlytics or HockeyApp.