On-Device Debugging With PhoneGap & iOS 6

Want to debug your PhoneGap apps, complete with breakpoints, DOM & CSS inspection, profiling, and more?  This is all possible with the PhoneGap Emulator, which allows you to leverage Chrome’s Developer Tools inside of the desktop Chrome browser (covered in detail here).  However, did you also know that you can have a rich debugging/development experience in an app that is actually running on a device?

Since the release of iOS 6 last Summer, we’ve all had the ability to debug PhoneGap apps while they are running on external iOS devices, or inside of the iOS simulator. I’m surprised how often I hear that people are not aware of this feature. With iOS 6 you can use Safari’s developer Tools to connect to any HTML content on the device, either in the mobile Safari browser, or inside of a web view. PhoneGap apps fall into that second category, they are based upon iOS system web view.

You can check out a preview of remote debugging on iOS in the video below:

In order to take advantage of this, you’ll first have to enable the remote web inspector for Safari on iOS. Just follow the instructions for “Debugging Web Content on iOS” from Apple – be sure not to skip the “Enable Web Inspector on iOS” section, which is hidden by default.  You have to enable this in iOS Settings in order for the desktop Safari Browser to be able to connect to any web content on the mobile device.

Once enabled, you can lever the full capabilities of Safari’s Developer Tools, including DOM & CSS inspection and modification, JavaScript breakpoints, storage, resources, exceptions, console logging, and more…


Unfortunately, this is only available for PhoneGap on iOS devices at this time. Android enables remote debugging inside of the Chrome browser, however that isn’t enabled for PhoneGap apps *yet*.  Whenever Google enables Chrome for web views inside of apps, it’s on!

  • http://www.johncblandii.com John C. Bland II

    We use this at times but it is REALLY difficult to get right. Safar is very fickle with large JS files and crashes often.

    You also cannot see the very beginning of your app startup because you have to click through Safari to start debugging.

    Phonegap debugging on device can be very difficult and painful at times.

    • http://www.tricedesigns.com Andrew

      True, the startup debugging can be tricky b/c you’ll have to reconnect to Safari. However I have not run into the crashing issue, and I’ve got a few very complicated apps. How big are your “large” files?

  • http://mobileicecube.com/ Ville

    Thanks so much! I was aware I could do this with the simulator but never figured out how to enable it on the device. So useful that I can finally properly debug my app with the camera on device.

  • ahmad kas

    Hi Andrew,
    May I aks you something, I was upload an app using phonegap API to download and store the file on to iPad but apple rejected the app because this:

    We found that your app does not follow the iOS Data Storage Guidelines, which is required per the App Store Review Guidelines.

    In particular, we found that on launch and/or content download, your app stores 8.89 MB. To check how much data your app is storing:

    – Install and launch your app
    – Go to Settings > iCloud > Storage & Backup > Manage Storage
    – If necessary, tap “Show all apps”
    – Check your app’s storage

    The iOS Data Storage Guidelines indicate that only content that the user creates using your app, e.g., documents, new files, edits, etc., should be backed up by iCloud.

    Temporary files used by your app should only be stored in the /tmp directory; please remember to delete the files stored in this location when the user exits the app.

    Data that can be recreated but must persist for proper functioning of your app – or because customers expect it to be available for offline use – should be marked with the “do not back up” attribute. For NSURL objects, add the NSURLIsExcludedFromBackupKey attribute to prevent the corresponding file from being backed up. For CFURLRef objects, use the corresponding kCFURLIsExcludedFromBackupKey attribute.

    For more information, please see Technical Q&A 1719: How do I prevent files from being backed up to iCloud and iTunes?.

    Whats should I do ? I have set BackupWebStorage to “none” on config.xml and reupload but apple still rejected the app.

    please help I dont know how to do and I’m Used cordova 2.4


    • http://www.tricedesigns.com Andrew

      What are you storing? That does seem like an awful lof content to put into storage just to access content. If you need to store files locally, you can use window.requestFileSystem(LocalFileSystem.TEMPORARY, 0, onSuccess, onError); from the file API to get access to temporary storage. More detail at: http://docs.phonegap.com/en/2.7.0/cordova_file_file.md.html#LocalFileSystem

  • Tom Wilson

    I’ve found that if you put an alert at the start of your javascript, the code will be delaying in executing, then you can start the debugger and after you click the alert, your code continues to execute and you can then continue to debug.

  • http://www.garthwaite.info Paulo

    I also had difficulty debugging startup code.

    I found that it helped to set a breakpoint in the startup code and then go to the console in Web Inspector and enter: window.location.reload()

  • Jan Becicka

    I tried it on my iPad and it does not work. I’m able to inspect pages on Mobile Safari, but not real device. I can inspect the very same phonegap app on iPhone Simulator, but when I run it on real device I see only “No Inspectable Applications”
    Any idea what I’m doing wrong?

  • http://omnispear.com Jared Armstrong

    Thanks for posting this. I have been trying to figure out better ways to debug phonegap applications.

  • John

    Is there a way to do the same for IOS5?

    • http://tricedesigns.com/ Andrew Trice

      There is a tool called iWebinspector that will work for iOS 5.0 in the iOS simulator, but not on an actual device: http://www.iwebinspector.com/

  • Alexander

    The link to apple instructions is broken. 🙁

  • Anirudh Goel

    you say on device debugging but are using a simulator 🙁 how to do it on a real device?