12 steps for setting up Charles Proxy with tvOS

This might not be the first time you’ve read about Charles Proxy here, but just in case you’re unfamiliar with Charles, it’s a tool that allows us to set up a workstation as a proxy between an app we’re developing and the internet. It also allows us to inspect API requests and spoof the responses.

Our QA team frequently uses Charles Proxy to do things like validate network calls, verify analytics, modify responses to perform negative testing, and more. Setting up Charles on devices is usually a pretty straightforward process. But as we recently discovered, it’s a different story when you’re working with tvOS apps.

There is no apparent way to add proxy settings, and in order to encrypt communications using SSL (Secure Sockets Layer) with Charles Proxy, you have to install the Charles SSL certificate from www.charlesproxy.com/getssl on the device you’re checking. But this is impossible on an Apple TV because there is no browser and no way to install certificates locally.

After some research, we found out Apple Configurator (a tool for quickly setting up many devices with predefined settings like Wi-Fi networks and content filters) can be used to solve both of these issues. (You can also use Wi-Fi settings and set up the proxy for only one network. You will need to select "Wi-Fi" and input your network settings along with a manual proxy using the same settings. This means the proxy won’t be used if you use a different Wi-Fi network.)

What follows is how we set up Charles Proxy to work with tvOS using Apple Configurator.

Set up a profile

In order to set up tvOS, you need to use a profile to set up a proxy.

Step 1: Download and install Apple Configurator.

Step 2: Open Apple Configurator and navigate to File -> New Profile.

Step 3: Give your profile a name and a unique identifier. Typically, you’ll be setting it up to go through the same PC you’re using, so indicating this is encouraged (e.g., Charles-JoeLaptop).

Step 4: Select Global HTTP Proxy* on the left and click configure.

Step 5: Input your IP address of the machine running Charles and 8888 (default) for the port.

• Large organizations often use Apple Configurator to set up security settings and other restrictions more easily. However, we do not often use Apple Configurator at TELUS Digital. We try to emulate real-world use cases to get the most coverage possible, which means configuring each device differently.

Step 6: If you need SSL, you need to add the Charles SSL certificate (If you’re not tracking SSL, you can ignore this part):

• Go to charlesproxy.com/getssl to get the SSL cert.
• When you download this, it will be a *.pem file containing the certificate you need. You need the certificate in a different format to add to your profile. (There are different ways you can do this, I found the simplest way was to add it to my keychain, then export it as a *.cer file.)
• Back in Configurator, select Certificates on the left and click Configure.
• This brings up a dialog to select the relevant certificate, select the one described above and click Open.‍
• It may say, “This root certificate is not trusted.” This just reflects the status of the user you’re using on the Mac.
• Save and close the Profile.

Install the profile

Step 7: Now you will need to load the Profile onto the Apple TV. This requires a USB-C adapter.

Step 8: With the Apple TV turned on, connect it to your MacBook using the USB-C adapter.

Step 9: Open up Apple Configurator.

Step 10: The Apple TV should show up under All Devices.

Step 11: Select the device and click on the Add button at the top of the window.

Step 12: Select Profiles and find the profile you created above, then click Add Profiles.

Congratulations! Now you should be able to see http and https traffic from Apple TV.

While there are many tvOS development tools available, mastering Charles Proxy is essential for any serious tvOS developer.