Skip to content

Using Charles Proxy to verify mobile apps networking behavior

Jump to bottom
Ettore Pasquini edited this page May 17, 2021 · 9 revisions

Overview

Charles Proxy or any other proxy software can be very useful to diagnose networking issues for a mobile app, in particular in relation to possible network or server issues, which are often hard to predict or test against. On this document we focus on Charles and iOS devices, but the approach will be similar for different proxies or different mobile platforms.

Charles Set-up

  1. Download it from https://www.charlesproxy.com -- There's a free trial available. After that, usage is time-boxed to 1 hour per session, and a there's a 10 second delay every time you launch it. It's well worth it to buy the license.
  2. Install the required Charles Root Certificate on your computer by following these instructions: https://www.charlesproxy.com/documentation/using-charles/ssl-certificates/ -- For Windows follow the instructions for "Windows / Internet Explorer". Wait before continuing to set anything up on your mobile device, and instead verify that the cert is installed correctly your computer. It should look something like this (this is Keychain Access on macOS, Windows will have something similar wherever certificates are managed:

Charles Root cert on macOS

  1. Next you need to install a profile on your iOS device. This profile contains a certificate the will allow you to decrypt all SSL / HTTPS traffic that goes through Charles. Follow the instructions under "iOS devices" from the same page above. Note that where it says to "Set your iOS device to use Charles as its HTTP proxy" you need to choose Manual proxying and use the IP address of the machine running Charles. The IP address is available in Charles's Help menu > "Local IP address". As for the port, use 8888. Secondarily, where it says "Open Safari", it means "open Safari on your iOS device": if you're not prompted to install a profile, it means something is wrong in your Charles setup on your computer, or you did not correctly configure your iOS device to reach your computer as proxy.
  2. In Charles, enable SSL proxying in Proxy menu > SSL Proxying Settings..., then in the Settings tab of the window that opened up, check the "Enable SSL Proxying" checkbox and add "*" under "Include". This should be the default, but it's worth checking.
  3. At this point you should be able to run SimplyE and see the requests/responses that go out from your device, decrypted. If you still see them encrypted, try quitting and reopening Charles. Another useful page to diagnose SSL issues is this one.

Focus

Charles shows EVERY url your device hits. I find very useful to "focus" on the hosts that I care about and hide everything else. To do this, choose View --> "Focused Hosts..." and enter these hosts:

*.librarysimplified.org
platform.nypl.org
https://librarysimplified.org
*.openebooks.us
*.openebooks.net
*.overdrive.com
isso.nypl.org
(or any other library URLs you are testing against)

This way Charles will highlight requests to those hosts and hide everything else under "Other Hosts."

Response Rewrite Set-up

To test how the app behaves when requests (for whatever reason) fail, it's really convenient to use the response rewrite feature that Charles offers.

  1. From the Tools menu, choose "Rewrite..."

rewrite-summary

  1. Click "Add" on the bottom left of the pop-up window to add a rewrite set.
  2. Then add a URL you wish to rewrite. If you have used the app for a while as you were testing it out, you can just pick one of the URLs the app tried to reach. If you want to test the loading of a particular page in the app and you don't know which api call serves that page, clear the session with the "broom" icon in the toolbar, then load the page again on the device, and you will see its related URL show up.

For example, in the image above I added 2 locations: one for the libraries list and one for Circulation manager authentication document.

If the URL you're looking for does not appear in Charles, it might be because it's being cached by the app. The app has a hidden way to clear its caches: go to the Settings tab and tap 7 times in rapid succession on the version number. A "Testing" item will appear and you'll be able to wipe the caches there. (Any options available under "Testing" are officially not supported and are strictly for QA purposes only.)

  1. The bottom right of the window is where you specify how you want to rewrite the response. It's also possible to rewrite the requests the app sends out. The possibilities here are many. If for example you want to simulate a 500 server error, click on "Add" and enable:
  • Response Status --> Replace with "500 Internal Server Error"

response-status-rewrite

  • Body for Response --> Replace with any plain text you want

body-rewrite

At this point requests to that URL should fail and Charles should show it in its UI:

charles-main

Charles allows to rewrite requests and responses in pretty much whatever way you want. For example, to verify how the app behavior changes in relation to caching, you could modify the cache control headers in the response. Or you could add/remove a query param from the request to see how the server responds in real time. The possibilities are endless!

Clone this wiki locally