Bug Reporting

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

Writing an SDK is hard. We need to interact both with Apple's frameworks (especially UIKit) and also your application. There are many potential edge cases depending on 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 always will be bugs. We usually have a very fast turnaround time on issues. There are several ways how 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 on the category of the problem, here's what works best for reporting:

Incorrect/Partial Rendering

If there's a PDF that does not render correctly, please send us this file. You should verify that the latest version of Adobe Acrobat renders the file correctly before submitting it. We go to extreme lengths to ensure that even partly broken files are rendered as accurately as possible. Also let us know what particular device and OS you've tested with, as different devices and versions might have different settings/fonts installed.

API Issues

  • Send us a small, runnable example project that shows off the issue. You can start a new project or use one of the samples that we provide as a base. Often it also helps to first try a particular issue with our catalog sample project (you get this as part of the download in our customer portal). It's very helpful to know if an issue happens with our samples as well as 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. We have a standard NDA as part of the license agreement which also covers such software exchange and we will destroy any material 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, use our manual setup to integrate. CocoaPods does not allow automatic .dSYM uploads yet, but you can still use it if you rely on a 3rd-party crash reporting service. Apple has a great guide on Understanding and Analyzing iOS Application Crash Reports to learn more about crash logs in general.

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, then right click and select Export Log and send us this file. (If you have not opened this window for some time, symbolication might take a while - 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 we can understand and fix the crash.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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 both online or directly in Xcode via the Crashes Organizer (Window -> Organizer -> Crashes). Control-click a crash report and choose “Show in Finder” and send the selected files to us.

Crash Logs During Development

Often 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 don'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 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 OS X, 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.

3rd-party Crash Reporting Services

We recommend using a 3rd-party crash reporting service instead of solely relying 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, where a 3rd-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. There's also a comparison website to see which service has a higher success rate on stack trace symbolication.

iOS Considerations

To enable symbolication of PSPDFKit crash logs for iOS on these services, you need to upload the PSPDFKit.framework.dSYM and PSPDFKitUI.framework.dSYM file that is provided as part of the PSPDFKit.dmg download, next to the .dSYM file for your own application. (a dSYM file contains symbol information and is specific to a particular build of your application/our SDK)

See the Crashlytics guide or the HockeyApp guide for details how these symbolication files can be uploaded.

With HockeyApp you may extract a raw crash log via "View Raw Log" -> "Download". That way we can perform the required symbolication manually as well. Crashlytics currently does not allow such a raw export yet, although we've contacted them and they are working on such a feature.

Screen Captures/Videos for iOS

QuickTime can be used to record the screen of an iOS device. Here's a detailed how-to to set this up. Screen recordings are particular helpful to demonstrate an interaction or UI issue that is not simply a crash.