Troubleshooting iOS SDK integration¶
If you encounter any issues during integration and testing of Contextual then the quickest and best way for us to help is to get a build of your app so we can test your app from our side.
To do this please get your developers to add QA@contextu.al to your test platform (Testflight, Fabric, App center etc) with the device id of
Capture a crash report from a device¶
If you ever encounter a hanging app or a crash then please try to provide us with some of the following information so that we can debug the iussue as quickly as possible.
Sharing from system settings¶
- Go to OS Settings, Find "Privacy" -> "Analytics"
- Enable "Share iPhone Analytics" and then enable "Share With App Developers"
- Go to "Analytics Data"
- You should see a bunch of .ips files here (formatted as <app_name>-<datetime>.ips), choose the one with your app name and the datetime when crash occur
- Click the right upper corner's button to share this file with us
Using the Xcode Organizer¶
This method requires you have Xcode installed on your machine.
- Launch Xcode on your desktop machine.
- Open the Xcode Devices and Simulators window. (Window menu -> Devices and Simulators, or Cmd-Shift-2.)
- Find your device in the left sidebar, then select “device logs”.
- Choose the crash (or multiple crashes) and select “Export” at the bottom of the Organizer window.
- This will copy the crash reports to your hard drive.
- Send this report to us
Capture a crash report from the iOS Simulator¶
- After a crash happen there will be a crash report generated at path
- The report will be named as <app_name>_<datetime>_<device_name>.crash
- Choose the one with your app name and the datetime when crash occur
- Send this report to us
Enclose corresponding dSYM file ¶
In order to analysis the original bug report you've sent to us, it is very important that you also enclose the corresponding dSYM file together with the report.
- Open your project by using cocoapods project launcher <app_name>.xcworkspace
- Choose project Pods on the left side panel
- Go to Build Settings
- Search for
debug information format
- Make sure it is set as
DWARF with dSYM Filefor Debug build or Release build depends on which build are you testing with
If you are testing with a debug build app you should find dSYM usually under path
~/Library/Developer/Xcode/DerivedData/<app_name>/Build/Products/Debug-<iPhone/simulator>. If you are not sure where it is, you may refer to the following steps to find them.
- Open your project in Xcode
- Find your app's
.app file under group "Products"
- Right click on the .app file, then click "show in finder"
- Go to folder "pointzi" find
pointzi.framework.dSYMand send this file to us (if you can't find the file please set
debug information formatas
DWARF with dSYM Filefor debug mode and re-compile your app again)
- If you have also installed paper-onboarding-pointzi, please go to folder "paper-onboarding-pointzi" and send
paper_onboarding_pointzi.framework.dSYMto us as well
Release build from Xcode¶
If you are testing with a release build app you should find dSYM under your archived package usually under path
~/Library/Developer/Xcode/Archives. If you are not sure where it is, you may refer to the following steps to find them.
- Go to Xcode Organizer (Cmd-Shift-6)
- Click Tab Archives
- Right click on your build, show in finder
- Right click on the .xcarchive file, show package content
- Go to folder "dSYMs"
paper_onboarding_pointzi.framework.dSYMsend them to us
Release build from Distribution¶
If you are testing with a release build app installed from a distribution method such as Testflight or Hockeyapp. You should be able to download the dSYM files from the iTunes Connect website
- Open the App Details page.
- Click Activity.
- From the list of All Builds, select a version.
- Click the Download dSYM link.
- Send all the dSYM downloaded to us.
Further information may help¶
What are the steps to replicate the issue ?¶
- Try to write steps to replicate issues including additional information such as AppKey, device version, SDK and Contextual version and Campaign name.
Provide videos to help us understand the issue better:¶
- Sometimes a recording the issue can help us understand the issue a little bit better. A good software for windows 10 is Hit the Windows key and G. For window MAC it is QuickTime Player from your Applications folder.
Sharing your app's view hierarchy¶
- Apple change things frequently, crash may happen when a layout hierarchy unexpectedly changed, please do the following command in debug mode and enclose the result to allow us to analyze the view hierarchy.
po [[UIWindow keyWindow] recursiveDescription]
Enable Debug logging¶
To enable more verbose logging from the Contextual sdk pass the
withDebugMode parameter to the
1 2 3 4 5 6 7 8 9 10 11 12 13
1 2 3 4 5 6 7 8 9
Fail to export ipa or upload to AppStore due to “Found an unexpected Mach-O header code”¶
If you meet error when exporting ipa or uploading to AppStore, as screenshot below, it’s because the binary was added into embedded framework by Cocoapod by mistake.
- Open App’s target->General.
- Remove it from “Embedded Binaries”.
- Only keep it in “Linked Frameworks and Libraries”. If step 2 removed it in “Linked Frameworks and Libraries”, add it back.
Errors: Undefined symbols for architecture¶
If you are getting errors saying 'Undefined symbols for architecture x86_64' they are mostly due to issues with Xcode linker. Below are some of the ways to solve it
Deleting the derived data folder
Clearing the Pods
Adding ObjC entry in Target >> Build Settings >> Other Linker Flags -ObjC
Undefined symbols for architecture x86_64:
nominal type descriptor for Swift.AnyHashable, referenced from:
_symbolic SDy_____ypG s11AnyHashableV in libpaper-onboarding-pointzi.a(SHCarouselLayout.o)
_OBJC_CLASS_$__TtCs12_SwiftObject, referenced from:
If you are getting this error means your Xcode project is an Objc project and not a swift project. You need to add swift references as follow
- Open ios/YourAppName.xcodeproj in Xcode.
- Right-click on Your App Name in the Project Navigator on the left and click New File…
- Create a new empty Swift file and add it to the project (make sure that Your App Name target is selected when adding)
- When Xcode asks, press Create Bridging Header and do not remove Swift file then re-run your build.
If you are getting the below error
You can fix the error by removing "(TOOLCHAIN_DIR)/usr/lib/swift-5.0/(PLATFORM_NAME)" from Project -> Build Settings -> LIBRARY_SEARCH_PATHS , as shown below