Quick guide on Charles Proxy for iOS development

Charles is a proxy server that enables us to view the networking traffic between our iOS app and the internet.

We can configure the iOS simulator or device to pass its networking requests and responses through Charles Proxy, so we’ll be able to inspect and even change the data in our testing and debugging process.

Recap on proxies

A proxy is an application that acts as an intermediary between a client requesting a resource and the server providing that resource. So instead of connecting directly to a server, the client directs the request to the proxy, which performs the request, receives the response and then directs the response to the client.

When communicating over HTTPS, encryption prevents proxy servers and other middleware from eavesdropping on sensitive data. SSL/TLS encrypts the networking traffic using certificates generated by trusted certificate issuers.

For Charles to be able to decrypt and show us encrypted traffic, it offers to generate its own certificate that we install on our iOS simulator or device and explicitly trust it. We'll look at that in more detail later.

Getting started with Charles

Charles Proxy isn’t free, but offers a free 30-day trial that can be downloaded on the official Charles download page.

After installing and launching the app, Charles should ask for permission to automatically configure our network settings. When granted, Charles will change our computer's network configuration to route all traffic through it. This allows Charles to inspect all network events to and from our computer.

After granting privileges, Charles directly starts recording network traffic that we see on the left pane.

When calling some URL for example in a browser, we should see the requests pop up in the left pane of Charles.

To be able to see the traffic coming in and out from an iOS simulator, follow these steps:

1. Quit the iOS Simulator
2. Launch Charles
3. Open menu Help > SSL Proxying > Install Charles Root Certificate in iOS Simulators

This will install the Charles Root Certificate into all iOS Simulators. Now, we should also be able to see the networking traffic from the iOS Simulator in Charles.

To setup Charles with an iOS device, check out the official documentation. Charles also offers a Charles for iOS app that can be used instead to monitor networking traffic for iOS devices.

Charles sessions

When we start Charles, a new session is automatically created by default and contains all recorded information. In most cases, we'll only need one session. Sessions can be saved and re-opened for example for sharing with others.

Recording

Charles records requests and responses to the current session for us to inspect. We can start and stop recording by using the record button in the top toolbar.

By default, Charles tracks all network calls. We can control the recorded traffic by opening Proxy -> Recording Settings in Charles menu and adding the API endpoints we want to observe. Port 443 is the standard port for HTTPS traffic.

To be able to see the encrypted traffic, we also need to add the same endpoints to Proxy -> SSL Proxying Settings.

News from tanaschita.com: I'm now offering sponsorship

By publishing a new article on different iOS topics every week, tanaschita.com is constantly growing in the developer community and may provide a great audience for you as a sponsor. Click here to learn more.

Structure and sequence view

In the left pane of the Charles app, we can switch between the structure and the sequence view.

The structure view lets us view the requests in a tree organised by the host name and the directories within the host.

The sequence view lets us view the requests in the sequence that they occur.

Note: If you don't see any requests in the sequence view, uncheck the Focused checkmark or mark the endpoints you want to see as focused by right-clicking them in the structure view.

Request and response views

When choosing one request in the left pain, we get a detail view on the right side.

As we can see above, the top area shows the request with query parameters, form parameters, cookies, authentication and JSON headers. The bottom area shows the response. For both, we can switch between different views of the same data like text, raw, json etc.

Chart view

The chart view in Charles shows us request and response times of each request.

Simulating slow networking

Charles can be used to adjust the bandwidth and latency of the network connection. This allows us to test our application under poor networking conditions. Go to Proxy -> Throttle Settings to see the available options.

We can apply throttling to all requests or only to specific hosts, so the rest of our networking requests aren't slowed down.

Manipulating requests and responses

Being able to manipulate response data is a great way to test how the app handles unexpected values.

Charles breakpoints tool lets us intercept and manipulate requests and responses before they are passed through Charles.

Check out the guide on Manipulating requests and responses with Charles (coming soon) for more details on this topic.

Further reading

Charles offers even more advanced tools like repeating, automatic rewrites, map local, map remote, cache and cookies control and more. Check out their official tools documentation to check those out.