Debugging On-Device PhoneGap Applications with “Charles” Network Proxy

Have you ever been testing or developing an application, and things just don’t seem to be working as you’ve expected? Just imagine that the data that you are receiving from the server isn’t exactly what you’d expect… even worse, what if this is happening in an application that you’ve already released to the app store, but not in your local debugging environment? Debugging this type of error can be difficult, but it can be made MUCH easier by taking advantage of a network proxy.

A network proxy server acts as an intermediary between the client and server. In this case, we are talking about using a network proxy server to intercept and analyze all web traffic occurring between a mobile device and the application server. The network proxy/monitor that I use very often in development is Charles.

Charles lets you inspect (and even intercept and change) all HTTP traffic either on your local machine, or on mobile devices that you control.  In this case I am using it to analyze the HTTP traffic for a PhoneGap application, but it actually intercepts all HTTP traffic for the device – even HTTP requests made by native applications or “release” applications obtained via the App Store.  It won’t give you insight into the code within an application – just insight into all HTTP-based network communication.

Check out the video below to see it in action:

From the Charles proxy, you’ll be able to see every HTTP request. Once you select an HTTP request, you’ll be able to view pretty much everything about it… round-trip time, request/response size, HTTP headers, query parameters, HTTP POST data, and of course, the response payload.

If you want, you can even use the Breakpoint Tool to intercept HTTP requests and modify the response payload before it’s returned back to your application.

To get started using the network proxy with your own applications, just follow the instructions provided in the Charles FAQ. You will quickly be “up and running” with the proxy, and able to inspect all HTTP traffic within your applications.

Once you’ve installed and launched Charles on your computer, you’ll need to set the HTTP proxy settings on your mobile device. For iOS devices, go into settings for your Wi-Fi connection, and set up a “Manual” HTTP proxy. Then enter the IP address for the computer that is running Charles, and port 8888. Note: The device and your computer should be on the same network segment.

This also works for Android devices too. You’ll need to go into the “Advanced Settings” for your Wi-Fi connection, select “Manual” proxy, enter your computer’s IP address for the proxy hostname, and specify port 8888 as used by Charles.

Once you’ve got this configured, you can view all HTTP traffic in all of your applications. This is particularly useful for debugging query parameter and server response issues on devices. If you’re using the PhoneGap Emulator, you can just use Chrome’s Developer Tools without having to worry about configuring a proxy.

The application that I was debugging in the video is my US Census Browser, an open source PhoneGap application for visualizing US Census data. You can download this application for yourself via:

The source code for the US Census Browser is also freely available on github at: