Mastering Google Analytics Custom Variables

I’ve got a stack of posts that I want to write, and realized that the all deal with Custom Variables. So, to make sure that we’re all on the same page when it comes to custom vars, here’s my guide to Mastering Google Analytics Custom Variables.

For those of you that have not used custom variables, CVs are a way for you to insert custom data into Google Analytics. What kid of custom data? Almost any kind of data. As long as the data is available to you in the source code of a web page you can pass it to Google Analytics via a custom variable.

There are 4 parts to a custom variable:

1. The name of the variable
2. The values for each variable
3. The index or slot of the variable and the scope of the variable
4. The scope of the variable

Name & Value

Custom variables are name-value pairs of data. The name is also called the “key”. To create a custom variable you define the name of a custom variable, like Favorite Baseball Team, and then assign it different values, Red Sox, Braves, Giants, etc.

Google Analytics will show you a list of all the custom variable names in a list and then let you drill down into the list and see all of the values.

Here’s an example. I use a custom var named “Year” to track the publication year for all my posts on this blog. I can view which year had the most popular content by finding “Year” in the Visitors > Demographic > Custom Variables report.

Google Analytics custom variables report

Then I can click on “Year” to a get a list of all the values:

Values for a Google Analytics Custom Variable

Custom variables can also be used in custom reports and advanced segments. The name of the custom variable becomes the “Key” dimension and the value of the custom variable becomes the “Custom Variable Value” dimension.

Google Analytics Custom Variable Dimensions

Index or Slot

The index is a way to organize your custom variables. Index is also referred to as “slot”. At a basic level, you get 5 custom variables. But this can actually be misleading. Think of the index as a parking lot with 5 parking space. You can put or “park” a custom variable in each space.

You can technically have more than 5 custom variables, but we need to discuss the next concept, scope, and how it impacts the index.


The key to mastering custom variables is understanding the scope. The scope of a custom variables determine how long the custom variable will persist.

If we use the parking lot analogy, the scope determines how long a car will stay parked in the custom variable parking lot.

There are three different scopes for Google Analytics Custom Variables:

Page Level: A page level custom variable will only persist for as the visitor is viewing the page where the custom variable has been set. Once the visitor moves to a new page the custom variable will expire.

Visit Level: A visit level custom variable will persist for the visitor’s entire visit. Once the visit ends the custom variable will expire.

Visitor Level: A visitor level custom variable will persist for 24 months as a cookie on the visitor’s machine until the visitor deleted her cookies.

Where scope really gets complicated is when we use it with the index. Remember, you have 5 slots that can hold a custom variable. Once you place a custom var in a slot that SLOT BECOMES FILLED and you can not place another custom var into the slot.

Scope and index work in tandem to determine how many custom variables you have available at any given time.

Let’s start with a visitor level custom variable.

Think of the index as a parking lot with 5 spaces.

When you place a visitor level custom var in a slot that slot remains filled until you delete the custom var. Remember a visitor level var is stored as a cookie so you have to actually delete the cookie. So, if you set a visitor scoped custom variable in slot 1 you can NEVER use slot one again. Unless you want to erase the custom var you set in slot 1.

Every time the visitor comes back to your website slot 1 will be filled because there is a cookie (named __utmv) on the visitor machine.

PARKING ANALOGY: There is a car in parking space 1. The car has no tires… and no engine… it’s not going anywhere soon… unless it gets towed.

When you create a visit level custom variable and place it in a slot, that slot remains full for the entire visit. Once the visit ends that slot opens up and you can place another variable in that slot.

Unlike the visitor scope custom variable there is no cookie. So when the visitor comes back to your site that slot is open.

PARKING ANALOGY: There is a car in a parking space 1, but just for the day. The spot will be vacated at the end of the day and someone else can park there.

When you create a page level custom variable and place it in a slot that slot remains filled until the visitor moves to another page. Once the visitor moves to another page the slot opens up and you can place another variable in the slot.

PARKING ANALOGY: There is a car in a parking space 1, but someone is just running into a store. The engine is idling and the spot will open up in 5 minutes.

Let’s look at a couple of examples:

Example 1: A visitor on a news site logs in. I set 5 visitor scoped custom variables. This means that whenever the visitor comes back to the website ALL five slots are filled. I can never use any other custom variables unless I erase or over-write one of the existing variables.

Example 2: A visitor is on a blog. Each blog post is categorized 3 ways using a page level custom variable. on every page I set the same 3 custom variables. When a visitor logs in I set a visitor custom variable to identify them as a member. So now I have 3 page level variables and one visitor level variable. The slot that contains the visitor level variable will always remain full, so I need to make sure that I always place my page level variables in the same slots.

Example 3: A visitor logs into a news site. I set 5 page level custom variables when they log in to record various pieces of information about their membership. One the next page I fire of 5 different custom variables to record information about their past browsing history. In this senario I have actually set 10 custom variables. How? Because they are all page level custom variables. The slots associated with a page level custom var open up when the visitor moves to a new page.

Hopefully this explains how you can technically have more than 5 custom variables.

The Code

Like everything else in Google Analytics, you implement Custom Variables using JavaScript. All of the topics we discussed above, index, name, value and scope, are all part of the JavaScript.

Here’s the standard Async code snippet:

_gaq.push('_setCustomVar',index,'name','value', scope);

The index is a number, from 1 through 5.

The scope is also a number. A value of 1 indicates a visitor scoped custom variable, a value of 2 indicates a visit level custom variable, and a value of 3 indicates a page level custom variable.

The name and the value are just plain text. Whatever you enter into the code above will be pulled into Google Analytics.

Where do you put this code? That’s the hard part. You place this code when you want to create a custom variable. You may want to categorize all of the pages on your site using a page level custom variable. In this case you might place the custom var code in the standard GA code snippet, like this:

Or, if you’re going to identify someone as a ‘member’ of your site, you might place the code on a page after the visitor logs in. Like this:

But you can also attach the code to visitor action, like onClick events.

You can also create custom variables for mobile devices using the iOS SDK and the Android SDK. How cool is that!

And some of the super nerds I work with at Cardinal Path have been able to hack custom variables and set them using the Google Analytics Mobile Tracking code for low-end mobile devices.

Regardless of the platform that you’re tracking, you can probably use a custom variable.

Super Nerd Stuff

Custom variables are not without their limitations and oddities. Here are a few things you need to be aware of when implementing:

1. What happens if you place a custom variable in a slot that is already filled? The last value placed in the slot is applied to the visit.

2. Custom variables are sent to Google using the same invisible image request. In the old days (ie two months ago) the size of this request was limited to 2048 characters by the browser. Because this limitation can really restrict data collection, Google decided to limit the size of your custom variable. This means that the name – value combination must be less than 64 characters. I know, this sucks.

BUT, Google has since changed how it collects data. The size of the image request is now 8000 + characters. So, in theory, Google could kill the 64 character CV limit. But they have not…

3. Custom Variable processing lags the standard data processing by about 24 hours. However, if you add a custom variable to a custom report it will be visible. I know, completely weird. This is really only for very, very big sites, where data processing can lag in general.

4. Page level custom variables are more-or-less the same as an event. When you create an Advanced Segment using a page-level custom variable, GA will return the number of visits that included that custom var. So, if you don’t have enough slots available you may want to consider using an event.

5. When you set a custom variable the data is sent immediately back to Google Analytics via an image request. This means that if you set a custom variable, on the last page of a visit and AFTER the pageview is recorded, that custom variable will NOT be collected by Google Analytics. If you can, put your custom variable code BEFORE _trackPageview().

That’s ALL I have to say about custom variables. Hopefully this gives you a good baseline understanding of how they work and how to implement them.

If you’re using custom variables leave a comment. I’d love to hear how you’re using them.

Be Sociable, Share!

    Like this post? Sign up to get posts delivered to your inbox.


    1. says

      Great post, Justin. It’s a shame that you can’t reliably set more than five. The _gaq.push([‘_setMaxCustomVariables’,10]); isn’t reliable enough. Presumably this is related to the character limit? If that’s been increased, maybe we’ll be able to set more than five one day.

    2. says

      Great post, as always Justin. The parking lot is a great analogy – I promise to use it and give you credit. ;-)

      It’s also worth mentioning that currently Custom Variables get URL encoded, so while it looks like you are setting “New York Mets” as a value, in the reports it looks more like “New%20York%20Mets”. Hopefully this is something that Google can address soon.

      Can’t wait to see more from your stack!

    3. Rubens Santos says

      Very enlightening post!

      Regarding the super nerd stuff number 3 (lags the standard data processing by about 24 hours): after implemented custom variables in a certain site we saw a lag of about 24 hours (but with no sure that things happend strictly at the same time).

      Right now, after reading your post, I can see that we are not having this lag in this site. The lag is small, the same as we have in another site, with the same size, that never used custom variables.

      (more precisely, for both sites, reports with some filters are with small lags and the control reports – with no filter – have a huge lag, for both sites).

      This information about what affects the delays is official or empirical?

      Thanks a lot!

      • says

        @Rubens: Thanks for adding some empirical evidence! This may be on some larget accounts, but looking at some smaller data sets it seems to be updating quite fast! I’ll update the post. Thanks!

    4. Christie says

      Hi Cutroni,
      I’m curious about what you said regarding hacking the google analytics tracking code for mobile (low-end). Could you show me the example of it?

      thanks :)

    5. Eli says

      Thanks for the nice article. I was wondering: Our Tech Team set up a CV “logged-in”/”logged-out” user (I am not sure if they did this on a visit or visitor level, but it makes sense to make it on a visit level, right? Otherwise the user will always count as logged-in…). When we create an Advanced Segment based on the Logged-in Users CV, does it include the PVs which were generated by those users BEFORE they logged-in? If someone comes to the site, views 3 pages and then logs-in, will those 3 pages appear in the Content Report in the Logged-in Users Segment? My guess is yes, because Advanced Segments capture the entire session and thus also the PVs before the log-in and after the log-out, if the user stays on the site, but I just wanted to get a second opinion. If i want to know how many PVs were generated on my site or a single page by logged-in vs. non-logged-in users, I can never tell for sure then, can I? I would know how many PVs were generated in SESSIONS, during which the users logged-in. Is this correct? Thanks!

      • says

        @Eli: Great question. I agree that a visit level custom variable is perfect for tracking “logged in” users. What this means to the data is that the pages that a visitor views before logging in will be grouped with the pages they view after logging in. This occurs due to the sessionization you describe. I’m trying to understand the data here. But I think I agree that just knowing the pageviews based on visits where the visitor logged in, at some point, is enough. I’m not sure I would need to break that down further and analyze pre and post login pageviews.

        I hope that helps.

    6. says

      @Tyson, @Justin: Looks like Google fixed the escaping issue on Friday. This issue is this now breaks filters that were set up with keys including escaped characters. The way we found around this is to add an OR clause in the filter that matches keys with both escaped and unescaped versions. e.g. key is “User%20Login” OR key is “User Login”. This way, you keep the history of the metric and the data collected after the change.

    7. Antti Nylund says

      I tried to use Custom Vars in session level and access that value stored in cookie. For some reason only time cookie stores value is when scope is visitor level. To my logic it should store value also in session level.

      In the utm call everything seems fine and information is sent to GA.

      Does GA somehow handle session level internally?

      I used a “dummy” event call to initiate the Custom Variable call because I needed to connect it with an event on that page. Dunno if this is a valid tip for those who need to counter that part 5 in super nerd section.

      Thanks for any insights and thanks for this article

      • says

        @Antii: Yes, session level custom variables are maintained at the server level, the value is not stored in a cookie. The only custom variable data stored in a cookie is visitor-copred custom variable.

    8. says

      Is it possible to change the label of custom variables? I mean, while displaying report, can I change “Custom Variable (Value 1)” to “My Value One”, “Custom Variable (Value 2)” to “My Second Value”, and so on?

      • says

        @Mukesh: Great question! Unfortunately no. But I think Google should embrace your suggestion and make that change ASAP. It would make the reporting easier for everyone.

        Thanks for the feedback!

    9. Michael says

      Hey Justin-

      Great post. Where I work we figured out how to write the Google Website Optimizer combination number (0 for original through variation 1,2,3,4,5 etc.) to a Google Analytics Custom Variable. Which now opens up all the other possible dependent variables available in GA beside “conversion” and also opens up the ability to look at how particular segments (new visitors, returning visitors, international, Safari browsers, etc.) are performing in the test. Awesome. (One caveat with segments – obviously sampled data depending on site traffic.)

      • says

        Michael: Thanks for the top Michael. Identifying Website Optimizer variations is a great use of custom variables. It’s the easiest way to integrate Google Analytics and Website Optimizer. We actually teach this technique in the Seminars for Success program, it’s a very popular hack.

        Thanks for the comment!

    10. Nick says

      Very good. This post is very helpful for me. I’m just starting using google analytics. So your post helps me a lot. Thanks for sharing.

    11. says

      Hi Justin,

      Great analogies in here. Definitely helps to visualize how to set up your custom variables. I would recommend adding a code snippet for attaching custom variables to onClick events. And how cool about being able to create custom variables for mobile devices using the iOS SDK and the Android SDK!!!

      Thank you for the excellent information.


    12. Eli says


      Thanks for the great post. This post cleared up all of the conceptual questions I had about how GA uses slots to store custom variables. The “car parking” analogy was very helpful.

    13. says

      Thank you Jim. It’s a useful guide indeed.
      I did not understand though whether using page level custom variables rather than events gives you any advantage. (or vice versa)

    14. says

      Hey Justin,

      I know this article is more than a year old, but I was hoping you could answer a quick question on CV’s. If I add a CV to a page, so I can track all customers who login to a site, will this affect the standard reports I have or will I only see these metrics when building customer reports/advanced segments to specifically report on that custom variable.

      To give an example, if I want to determine the bounce rate for customers vs non customers – could I use a CV to set a visitor level session for a customer and then build an advanced segment to remove these guys from a custom report which shows me things like bounce rate, page depth, etc.

      Hope that makes sense

      • says

        @Kieran: There is a Custom Variables report, but your standard reports will not be affected. You can segment by your custom variables, using Advanced Segments or Secondary Dimensions, but the basic reports won’t show your custom vars by default.

    15. says

      Is it possible for the value to retrieve the logged in users’ usernames. We are trying to track visitors to password-protected php pages by their username. I am grateful for any help you could give this novice.Thank you.

      • says

        @Amy: It’s against the Google Analytics terms of service to collect any personally identifiable information. I would try and collect something anonymous, like a simple indicator if the user is a Member or Non-member. Hope that helps.

    16. Sam Hirbod says

      Hi again Justin,
      hope all is well!

      I was just wondering if there is something in particular I should think about if I would like to use the Generic HTML Tag method (with GTM) in order to implement custom variables? Is it even a good idea to use the GTM in this scenario?


      • says

        @Sam: Sure, you can use Custom HTML tag in Google Tag manager to implement a custom variable. Just remember that custom variables to not generate a hit back to the Google Analytics server. The data is sent on the _next_ hit to the server. So if you want to make sure you custom variable is sent to Google you should fire an event after the custom variable.

    17. Rokas says

      Hello Justin,

      Great post. I’ve been reading about CV, and couldn’t find an answer to this question:
      Say I have memberships on my site, and those memberships vary in length 7 days or a month and etc. If I set the VC on visitor level when a user buys membership to track how paying members behave and filter out the whole month I would get wrong data, as some of the users will no longer be paying (7 days), is that correct? Some of the purchases are tracked using event tracking others using e.commerce.


      • says

        @Rokas: That’s correct. A user level custom variable will persist as a cookie on the user’s machine. If their membership expires in seven days you will manually need to delete that cookie.

        Thanks for the question.

    18. Raghu says

      Oh My God. Now I got the clear picture of Custom Variables. Class explanation Justin. The Analogy is just simple and meaningful.

      Thank you……

    19. says

      @Beth: Filters need a lot of work and it’s something that the team talks about a lot. Filtering on a CV is something that I think is critical. While I can’t comment about specifics I think any filtering tool will focus on all the dimensions.


    Leave a Reply to 5 Google Analytics Custom Variables for Ecommerce – Analytics Talk Cancel reply

    Your email address will not be published. Required fields are marked *

    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>