Advanced Charles Proxy Tutorial for iOS

Charles Proxy offers developers and testers an immediate look at network traffic. But there’s a lot to learn beyond the basics.

If you’ve ever wanted to change response data without asking the back-end server to test the client, report a server-side bug or reproduce a state on the client that needs a specific back-end response, advanced Charles Proxy features offer solutions.

In this tutorial, you’ll manipulate the response from the Star Wars API (SWAPI) to your own custom API in the StarCharles app. Along the way, you’ll:

• Set up Charles.
• Use the mapping tool and breakpoints.
• Perform repetitive actions with the rewrite and repeat tools.
• Save network activity to disk.
• Share reports with others.

Getting Started

Download the project materials by clicking the Download Materials button at the top or bottom of this tutorial.

Open StarCharles.xcodeproj in the starter folder.

StarCharles lists the films and characters of Star Wars, as provided by SWAPI. Build and run to see how it works.

Behind the scenes, each time you tap a film or a character, the app makes a sequence of requests to get the information it displays next.

Look at the following groups in Xcode:

• Network: Contains NetworkService.swift, which defines all the networking interactions.
• Models: Includes all the data models.
• ViewModel: Contains ViewModel.swift, which is the core of the project. It calls all the APIs, maps to the local models and updates the views.
• Views: Includes all the view-related code.

Now, you’ll install and configure Charles Proxy to observe the communications between StarCharles and SWAPI.

Setting up Charles

Your first step is to get a web debugging setup working. To do this, you’ll:

• Download and install Charles.
• Let Charles automatically configure your network settings.
• Download and install SSL certificates onto each simulator or device where you want to observe encrypted network communication.

First, download the latest version of Charles Proxy for macOS, which is v4.6.1 at the time of this writing. Double-click the DMG file, accept the license agreement and drag the Charles icon to your Applications folder to install it.

Charles Proxy isn’t free, but it does offer a free 30-day trial. Because Charles only runs for 30 minutes in trial mode, you may need to restart it throughout this tutorial.

Configuring Network Settings

Launch Charles. It should ask for permission to configure your network settings automatically. If it doesn’t, press Shift-Command-P to see this prompt:

Click Grant Privileges and enter your password, if prompted. Charles starts recording network events as soon as it launches. You should already see events popping into the left pane.

Installing SSL Certificates

Charles sits between a web browser and an API. It uses its own root certificate, also known as a certificate authority (CA), to dynamically create and sign certificates it sends to your local browser, letting you view network traffic as plain text.

For this to work, you must install and trust the Charles root certificate on the device or in the simulator where you want to view network requests and responses.

Go to the simulator that’s running StarCharles. Open Safari, then enter chls.pro/ssl.

If you don’t see this alert, you might need to restart Charles. Try it, then reload the web page in Safari on the simulator. Tap Allow to download the configuration profile containing the root certificate.

Next, open Settings. Navigate to General ▸ Profile and tap Charles Proxy CA.

Tap the blue Install button in the upper right-hand corner, then tap Install again on the following Warning screen. Once you’ve fully installed the profile containing the Charles Proxy CA, your simulator screen will look like this:

Finally, you need to fully trust this certificate. In Settings on the simulator, go to General ▸ About ▸ Certificate Trust Settings.

Under Enable Full Trust for Root Certificates, toggle Charles Proxy CA on and tap Continue after reading the root certificate alert.

Build and run. Tap Films, then tap a specific film. Next, tap a character. Navigate around the app to make some network calls. Check out how each row you tap in StarCharles shows a CONNECT request to swapi.dev in Charles.

Congratulations, making it this far means you managed to set up Charles completely. Onward and upward!

Focusing on a Host

By default, Charles tracks all network calls on your Mac. Right now, you’re interested in just one specific host: https://swapi.dev/. You can avoid the distraction of seeing every network request in Charles by focusing only on this domain.

Follow these steps to focus on a single domain:

• Click the Sequence tab to display network calls chronologically.
• Right-click on any swapi.dev request, then click Focus on the drop-down menu.
• Check Focused to the right of the Filter field to constrain the displayed traffic to just the calls to swapi.dev.

With that, you added one domain to the focus list. At any time, you can disable the Focus filter and choose any other domain to focus on instead.

Enabling SSL Proxying

Take a look at what’s inside one of the swapi.dev requests. Select any request, then click the Contents tab in the lower part of the screen. Whoa, what is that?

If a request’s contents appear garbled, you need to enable SSL proxying. This tells Charles to use its root certificate, which you installed earlier, to communicate with a domain where you’ve enabled SSL proxying. To do this:

1. Right-click any swapi.dev request, then choose Enable SSL Proxying from the drop-down menu.
   
2. Quit and relaunch Charles.
3. Open Proxy ▸ SSL Proxying Settings. Confirm that swapi.dev appears as an included location in the SSL Proxying tab.
4. Tap the little broom in the main Charles window to sweep out the existing traffic. Then, navigate around StarCharles to make network calls.
5. Now, select any swapi.dev request and select the Contents tab.

Ah, much better!

Explore all the content pane tabs to get a deeper look inside Star Wars.