Advanced Charles Proxy Tutorial for iOS

Get more out of Charles Proxy by learning advanced features like mapping responses to local files, automating requests and writing logs. By Emad Ghorbaninia.

Leave a rating/review
Download materials
Save for later
Share

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.
Note: This tutorial assumes you’re familiar with Charles Proxy. Still a Padawan learner? Check out Charles Proxy Tutorial for iOS first.

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.

Master detail list of the StarCharles sample app

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:

Charles Proxy prompt for automatic network settings configuration

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.

Network traffic appearing in Charles Proxy's 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.

Prompt to allow the simulator or mobile device to download the Charles root certificate configuration profile

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.

Profile Downloaded confirmation screen after downloading configuration profile

Next, open Settings. Navigate to GeneralProfile and tap Charles Proxy CA.

Install Profile screen shown in Settings under General then Profile

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:

Profile Installed screen

Finally, you need to fully trust this certificate. In Settings on the simulator, go to GeneralAboutCertificate Trust Settings.

Certificate Trust Settings screen

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

Root certificate warning

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.

Charles Proxy sequence tab showing network requests

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

Superhero tabby cat with Charles Proxy written on his tummy soaring to greatness

Note: If you had any trouble setting up Charles, check out the Charles Proxy Tutorial for iOS or the Charles FAQ page for more help.

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:

How to choose sequential output in Charles Proxy

Animated GIF showing how to focus output on a single host domain

  • Click the Sequence tab to display network calls chronologically.
  • How to choose sequential output in Charles Proxy

  • 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.
  • Animated GIF showing how to focus output on a single host domain

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.

Note: By pressing Shift-Command-O, you can see the list of Focused Hosts, add or remove domains and import and export this list.

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?

Unreadable response in the Contents screen of a request

Note: If you see Request and Response instead of Contents, click either of those. This simply means you have unchecked Combine request and response in the Viewers tab of the Charles Preferences dialog.

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.
    Drop-down menu with Enable SSL Proxying option
  2. Quit and relaunch Charles.
  3. Open ProxySSL 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!

Meaningful response displays after SSL proxying is enabled

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