Ode to Charles & Map Local

There once was a tool with a feature
The merits of which like a preacher
I praise on this blog
And I’m almost agog
For it’s part of my normal procedure

If there is one tool in my toolbox that I have to point out, it’s “Charles” by Karl von Randow.

Sure, there are others that are useful (Firebug, Omnibug) or even beautifully efficient (Sublime Text), but no other tool is as important for me as Charles.

I have mentioned Charles before, but today I want to show you my two most common use-cases.

Track the Tracking

Charles sits between the browser and the Internet as a proxy. It muscles itself in automatically when you launch it, so no messing around with proxy settings is needed.

Once started, it can show a structural view (“Structure”) or a timeline (“Sequence”).

A lot of people use the structural view but I am a big fan of the timeline, mainly because it is better suited for troubleshooting or checking work in progress.

Here’s what I do:

  1. Switch to “Sequence”
  2. Add a filter (e.g. “/b/ss”) so I only see the traffic I’m interested in
  3. Select the “Request” tab where I can see the URL parameters spelled out individually

Looks like this:

Charles “Sequence” View with a Filter
Some things I do when I use Charles:

I use the “Request” tab, “Query String” sub tab, to see what “variables” the tracking call contains. In the screenshot, we see s.pageName (set to “home”), some events, props and eVars. We even see some Dynamic Variables (eVar11 will have the same value as prop11, and prop14 will contain the contents of the s_vi cookie).

“Request” Tab / “Query String” Sub Tab
I can switch to the “Cookies” sub tab where I can see the content of my “s_vi” cookie. I can also see two cookies called “s_pers” and “s_sess”. Those are used by the “Cookie Combining Utility” and contain other cookies, so to speak.

“Request” Tab / “Cookies” Sub Tab
On the “Response” tab, “Cookies” sub tab, I can see exactly what cookies the server has sent, along with expiration, domain and path.

“Response” Tab / “Cookies” Sub Tab
If you are looking for more control and/or options, Charles has you covered. While I do not use any of these routinely, they certainly have come in handy in the past, mainly the ability to repeat a request to the server. You can change the request before re-sending it as well!

Repeat / Edit a Request in the “Sequence” View

Trick the Tracking

Here comes the ultimate killer feature for anybody who builds for or works with anything on the WWW: “Map Local”.

My top use case: modify the s_code.js file and see the results in the live environment.

This is useful in a lot of situations.

  1. When you want to upgrade the core Javascript code
  2. When you want to upgrade, add or remove a plugin
  3. When you want to test Campaign tracking, maybe with live campaigns or paid search
  4. When you want to troubleshoot, maybe start with a simplified version of the s_code.js file

So how does it work?

First you download whichever file it is that you want to work on from the web site and store it locally. Next, you tell Charles to serve the local file rather than the original. Then, you alternate between your editor and the browser, making changes and checking them.

The great thing about this is that the browser has no idea what is happening. “Map Local” is completely transparent!

So, go to Tools > Map Local (or simply press Ctrl+Shift+L) to call up the Map Local Settings dialog.

“Map Local” Settings Dialog
Click the “Add” button to add a new mapping or double-click an existing mapping to edit it. The Edit Mapping dialog window appears.

“Edit Mapping” Dialog
In this dialog, you specify what exactly you want to map, and what file to use instead.

You can leave some of the fields empty. As an example: if the “Protocol” field is set to “http” Charles will only map files served via HTTP, not HTTPS, but if you leave the “Protocol” field empty, it’ll match both. The same goes for the “Port”, “Query” and even the “Path” field. Careful with the latter!

Close both dialogs and you’re good to go.

A simpler way of adding a “Map Local” to a remote file is via the Structure or Sequence view.

Just find the file, right-click it, then select “Map Local…”

“Map Local” in “Sequence” View
Note that if the file is mapped already, Charles displays a helpful tick mark next to it!

“Map Local” with Tick in “Sequence” View


Charles is not the only proxy out there, of course. You can achieve the same using Fiddler, I’m sure.

If you only want to track the tracking, not trick it, there are a lot of tools, including the Adobe Javascript Debugger and Bloodhound.

Pro tip: when you’re done developing and testing, make sure you disable “Map Local”!

I can assure you that by the next time you are looking at something, you’ll have forgotten all about it, and you will see inexplicable effects and a live s_code.js file that looks old, even though you’ll be sure IT just pushed live the latest version. You’ll curse browser caches, proxies and — oh, wait a tick … proxies … d’uh.

Happened to me more often than I’m prepared to admit.

This one goes out to Karl!

14 thoughts on “Ode to Charles & Map Local

  1. Can I sing the ode too? 🙂 Absolutely love the tool. In the past I was always sweating when making updates to s_code and hoping that all goes ok and the site won’t go dead because my update to s_code. With Charles I can always test beforehand and no more sweating! My favourite tool for debugging (or should I say variable testing) is omnibug, so simple and beautiful.

    Ps. Great blog, fantastic job! There are too few SiteCatalyst blogs. I started my own, but let’s see can I write anything useful since you have pretty much covered all the things I was thinking to write.


    1. Hi Antti!

      Thank you very much for the feedback, I’m glad you find this useful.

      I would absolutely encourage you to write as well. I think it is less about the content and more about the individual view each of us have on the different topics. I am sure you can add unique insights and perspective. And you’re right, there are not enough blogs out there right now about our topic.


  2. That’s true. Don’t have all the answers yet regarding to SiteCatalyst, but would like to share my learnings/insights, and maybe that starts new discussions. Let’s see what happens. Thanks for the encouragement.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.