Logo for tanaschita.com

Quick guide on Proxyman for iOS development

Learn how to use Proxyman to inspect network traffic for your iOS application.

04 Jul 2022 · 8 min read

Proxyman is a proxy server app available for macOS that enables us to view networking traffic, including traffic from iOS applications. It provides the possibility to configure the iOS simulator or device to pass its HTTP and HTTPS requests and responses through Proxyman, so we are able to inspect and even change the data in our testing and debugging process.

This guide provides an overview on Proxyman and its features with a focus on iOS development.

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.

Proxy as interactor between client and server.
Proxy as interactor between client and server.

Getting started with Proxyman

Proxyman provides a free version with all essential features that can be downloaded on the official download page.

After installing and launching the app, it asks for permission to install a proxy helper tool to configure system proxy settings. When finished, Proxyman directly starts recording network traffic.

When calling a URL, for example in a browser, the requests pop up in the flow list panel.

Proxyman start screen.
Proxyman start screen.

Selecting a request in the flow list panel shows request and response details in the flow content panel.

Enabling SSL Proxying

As shown above, we cannot inspect the HTTPS response yet because it is encrypted. 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.

To change that we need to install the Proxyman Root Certificate. Proxyman will then act as a man-in-the-middle, which enables us to see the HTTPS traffic in plain text.

To install the Proxyman Root Certificate:

  1. Open Certificate ▸ Install Certificate on this Mac in Proxyman's menu.
  2. Select Install & Trust in the opened window and enter your password when prompted.
  3. Open Tools ▸ SSL Proxying List > add a specific domain, a wildcard or and app to enable SSL proxying.
SSL Proxying List window
SSL Proxying List window.

After finishing the steps, we are now able to read encrypted responses from the domains and apps we listed.

Inspecting network traffic from an iOS simulator or device

To be able to see traffic coming in and out from an iOS application, Proxyman provides the possibility to install the Proxyman Root Certificate on an iOS simulator or device.

To install the certificate on a iOS simulator:

  1. Launch an iOS simulator, for example by running the app from Xcode.
  2. Open Proxyman's menu Certificate > Install Certificate on iOS > Simulators.
  3. In the opened iOS Simulators Setup window, just click install and trust and then reboot the simulators.
iOS Simulators Setup
iOS Simulators Setup

Now, networking traffic from the iOS Simulator should show up in the flow list panel.

Since Proxyman installs the certificate only on booted iOS simulators, repeat the process when running the app on a different simulator.

To setup Proxyman with an iOS device, open Certificates > Install Certificate on iOS > Physical Devices. Proxyman will guide you step by step through the process.

Limiting results to specific apps or domains

To limit network traffic showing up in the flow list, for example to only one specific domain, we can use the pin tool.

Pinning a domain
Pinning a domain

After selecting the domain or app to pin, drag it into the pin section in the source list panel. Or alternatively right-click and select pin.

Repeating, editing and composing requests

To repeat a request without resending it manually, we can use the repeat tool by selecting a request in the flow list, right-clicking it and choosing Repeat.

Repeat a request
Repeat a request

Alternatively to the Repeat option, there is an Edit and Repeat option to edit a request before resending it. It allows to change query, header values and body of the selected request.

We can also compose a fully new request using the compose button in the menu or by selecting Tools > Compose Request.

Using breakpoints to intercept and edit requests and responses

The breakpoint tool allows us to edit the content of a request or response on the fly.

Right-clicking the request and selecting Tools > Breakpoint opens the following breakpoints dialog.

Adding a breakpoint
Adding a breakpoint

It provides different options to configure which requests and responses should be intercepted.

After creating the breakpoint, Proxyman will open a new editing window as soon as it receives a request or response we want to intercept. It allows us to modify the data as we wish before continuing the execution with new changes.

Using map local tool to change responses

Being able to change responses is a really useful feature when developing apps, for example to simulate different scenarios or errors and see how our app responds.

The map local tool enables us to setup a custom response by right-clicking the request and selecting Tools > Map Local.

Changing the response with the map local tool
Changing the response with the map local tool

In the opened window, we can edit the response directly or choose a local file that will serve as response.

Exporting request and response data

To export or share networking data with others, we can copy a cURL by right-clicking the request and selecting Copy cURL or use one of the export options by selecting Export.

Request and response exporting options
Request and response exporting options

After choosing a destination, Proxyman will create two .txt files with all relevant network data for the selected request and response.

Further reading

Proxyman offers more features and tools like map remote, saving sessions, GraphQL debugging, simulating different network conditions, scripting and more. Check out their official documentation to find out more.

Newsletter

Like to support my work?

Say hi

Related tags

Articles with related topics

Latest articles and tips