Troubleshooting iOS SDK integration

NOTE

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 744d3c12be72e17a5e3c76f8be809ce17469def0

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

Note

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 ~/Library/Logs/DiagnosticReports/
• 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 File for Debug build or Release build depends on which build are you testing with

Debug build

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.dSYM and send this file to us (if you can't find the file please set debug information format as DWARF with dSYM File for 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.dSYM to 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"
• find pointzi.framework.dSYM and paper_onboarding_pointzi.framework.dSYM send 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 registerInstall method.

Swift 

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate
{
    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
    {
        // Replace 'MyApp' with your app_key, registered in the Contextual Dashboard.
        // Set 'withDebugMode' to 'true to enable debug logging.
        Pointzi.sharedInstance().registerInstall(forApp: "MyApp", withDebugMode: true)
        return true
    }
}

Objc 

#import "StreetHawkCore_Pointzi.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Replace 'MyApp' with your app_key, registered in the Contextual Dashboard.
    // Set 'withDebugMode' to 'YES' to enable debug logging.
    [POINTZI registerInstallForApp:@"MyApp" withDebugMode:YES];
    return YES;
}

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.

Solution:

• 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

Example 1:

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

rm -rf ~/Library/Developer/Xcode/DerivedData 

Clearing the Pods

pod cache clean 'pointzi' --all
pod install

Adding ObjC entry in Target >> Build Settings >> Other Linker Flags -ObjC

Example 2:

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.

Example 3:

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

---

Last update: 2024-01-14