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.
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.
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:
- Open Certificate ▸ Install Certificate on this Mac in Proxyman's menu.
- Select Install & Trust in the opened window and enter your password when prompted.
- Open Tools ▸ SSL Proxying List > add a specific domain, a wildcard or and app to enable SSL proxying.
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:
- Launch an iOS simulator, for example by running the app from Xcode.
- Open Proxyman's menu Certificate > Install Certificate on iOS > Simulators.
- In the opened iOS Simulators Setup window, just click install and trust and then reboot the simulators.
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.
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.
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.
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.
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.
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