Dimension Widening: Import data directly into Google Analytics

There are lots of different ways to put data in Google Analytics. You can collect data from a website with JavaScript. You can collect data from an app using an SDK (Android or iOS). Or you can collect data from any network connected device using the measurement protocol.

But there’s another way to add data to Google Analytics – you can import data using a feature called Dimension Widening.

You can add data to Google Analytics a number of ways - including Dimension Widening.

You can add data to Google Analytics a number of ways – including Dimension Widening.

With Dimension widening you can import additional dimensions and metrics directly into Google Analytics via a CSV upload or programmatically import data via an API.

Let’s take a look at how you might use Dimension Widening to augment the data in your account, and ultimately do better analysis.

Why Add More Data?

Analytics is more valuable when you can align the tool more closely with your business strategies and tactics. Adding additional data, like customer history, content publishing information, advertising cost data, etc. can help provide context to your data, thus making it easier to gauge performance and identify opportunities for improvements.

Adding additional data can also streamline your reporting (yes, basic reporting still happens) by consolidating all of your data in a single system that everyone has access to.

That’s where Dimension Widening comes in.

It is a mechanism to move data into Google Analytics.

How Dimension Widening works

You can upload two types of data to Google Analytics: Dimensions and Metrics.

A dimension is an attribute of a user or the sessions she creates.

A metric counts something – like time, money, clicks, etc.

When you use Dimension Widening you are uploading values for one or more dimensions or metrics.

You can upload values for existing dimensions/metrics or you can upload values for new dimensions/metrics that do not exist in Google Analytics.

When Google Analytics process the data it will join your custom data to the the existing data using something called a key.

The key binds your data, the data uploaded in a CSV file or sent programatically, to the Google Analytics data. When Google processes the custom data it will look at the value for the key, and then try to find the same value in the Google Analytics data.

If Google Analytics finds a matching keys then it will take the data in that row of the custom data and pull it into Google Analytics.

The key links your custom data to the data in Google Analytics.

The key links your custom data to the data in Google Analytics.

There are four basic steps to configuring Dimensioning Widening.

1. Identifying the data you want to import.

Step one is really simple, identify the data that you want to add to Google Analytics.

Remember, you can import a value for any dimension or metric that currently exists in Google Analytics. OR you can import values for custom dimensions and custom metrics that are not normally found in GA – more on this below.

When choosing the data you want to import ask yourself this – what data to I need to understand the behavior of my users? How can I make my analytics life easier by consolidating data in Google Analytics?

You also need to define your key. This is obviously critical. If you can’t define a key then you can’t import data.

2. Create the schema in Google Analytics.

Once you define your key and the dimensions/metrics you want to import it’s time to add the schema to Google Analytics. Think of this step as telling Google Analytics how to interpret the CSV file (or data feed) that you will import.

Choose a property in the admin section, then choose Data import and Dimension Widening.

The Dimension Widening settings are in the Data Import section of a property.

The Dimension Widening settings are in the Data Import section of a property.

To begin you need to name the data set you will import. You can actually upload multiple data sets (more on this later), so make sure you name it something very descriptive, like “Campaign Data” or “Content Information”.

Then choose the view where you would like the data applied.

Every data set must have a name, and you must specify which views to apply the data to.

Every data set must have a name, and you must specify which views to apply the data to.

TIP: Dimension widening will permanently change the data in a reporting view! It’s a good idea to test your dimension widening on a TEST view before applying it to your main reporting view.

Now add the schema. First, add the key that you’ve defined for your data.

Next, specify the dimensions and metrics that you want to add.

You must enter a schema into Google Analytics. Add the key along with the dimensions you would like to widen.

You must enter a schema into Google Analytics. Add the key along with the dimensions you would like to widen.

Here’s something cool – as you choose your key and dimensions Google Analytics will automatically show you the column headings that you will need to add to your CSV file.

As you add your schema Google Analytics will provide the column headers for your CSV file.

As you add your schema Google Analytics will provide the column headers for your CSV file.

Notice that they’re not the names that appear in the drop down boxes. They’re the dimension/metric names that are used in the API. Fear not – you don’t need to understand what they mean.

3. Build your CSV file.

Once you finish defining your schema choose save.

You’ll be presented with two options: get more details of your CSV file OR get an API key to upload your data programatically. Let’s focus on the Get Schema option.

Once you define your dimension widening schema you can download a CSV template or get an API key.

Once you define your dimension widening schema you can download a CSV template or get an API key.

Click the Get Schema button.

This window contains some really useful information. First, a list of the column headers that you need to add to your CSV file. This includes your key and all the other dimensions that you are adding to Google Analytics.

There’s also a way to download a CSV template for your specific data. The template is just an Excel file with the headers added to the first row.

Google Analytics will provide the column headers for your CSV and provide a CSV template that you can fill with your data.

Google Analytics will provide the column headers for your CSV and provide a CSV template that you can fill with your data.

4. Upload your CSV file or Send Data via API

Remember, there are two ways to add your data – via an API or manually via a file upload process. Let’s focus on the later – the file upload.

This isn’t too complicated, just click upload :) Once the file is uploaded Google Analytics will widen your data as it is processed.

You can check on the processing of your data using the Refresh button.

You can check on the processing of your data using the Refresh button.

NOTE: when you use Dimension Widening the data you import is NOT applied to historical data. Your data is only applied going forward.

I find that GA can process the file very fast (minutes). You may want to refresh your list often to determine if the new data has been added.

That’s it! That’s the basic process.

But you probably want to use Dimension Widening to import custom data, not data that’s already in Google Analytics. Let’s take a look at how to do that.

How to add Custom Data

You can also add custom dimensions and custom metrics to Google Analytics via dimension widening. The process is almost exactly the same. The only difference is that you must first define your custom dimensions or metrics in the Google Analytics admin section.

To upload a dimension or metric that does not exist in Google Analytics you must first define those custom dimensions or metrics.

To upload a dimension or metric that does not exist in Google Analytics you must first define those custom dimensions or metrics.

There’s not a lot of configuration here. Just give your dimension a name and choose a scope.

NOTE: You can only widen between dimensions and metrics of same scope. For example, you can’t widen from user scope Key to Hit scope dimensions. Check out this (somewhat old) article on Custom Variables to learn more about scope.

That’s it. Now you can choose these custom dimensions (or metrics) when you add your schema for Dimension Widening.

Once you define a custom piece of data it will be available in the Custom Data schema interface.

Once you define a custom piece of data it will be available in the Custom Data schema interface.

Then create your CSV file with the correct headers and upload your data.

Note: Custom Dimension and metrics are only available in Google Analytics customizations – this includes custom reports, custom segments and dashboards. They can also be used in certain analysis tools, like secondary dimensions.

An Example: Uploading simple publisher data

Let’s say I’m a publisher. I want to add the publication year, author for each article. My key to join my data with GA data is the URL of each page. I already defined two custom dimensions, one for page publication year and one for page author.

I’m going to define my data schema in Google Analytics.

Defining a custom data in your dimensions widening schema.

Defining a custom data in your dimensions widening schema.

Now I build my CSV file using the correct headers for my key and dimensions that I would like to widen.

A sample CSV file with custom dimensions.

A sample CSV file with custom dimensions.

Next I upload my file…

And finally, I have data in my custom dimensions. Here I can see the data in a Custom Report.

Custom Dimensions can be used in a Custom Report, Unified segment or other customization features.

Custom Dimensions can be used in a Custom Report, Unified segment or other customization features.

Best Practices for Managing CSV files

You might want to widen your data based on multiple keys. For example, you might want to widen your product data (using the product ID as a key) and your campaign data (using campaign name as a key).

In this case you’ll need to define two different schemas and upload two different CSV files. Make sure you name them something logical!

Another thing to consider is when to update your CSV files.

For example, let’s say that you’re a publisher, and you’re uploading new data about your content. But you’re publishing new content every day. And probably multiple times a day. You would need to upload a new CSV file every time you publish content. This is too manual. In case you probably want to consider a programmatic solution.

Use the CSV file for things that do not change often. Use the API for things that change a lot!

What about JavaScript and real-time collection?

Given my previous example, you may be asking yourself, “can’t I just collect custom data in real-time using JavaScript?”

Absolutely!

You could do something fancy, like add the data to a data layer, then pull it into some custom dimensions. No problem!

The point is that you don’t always have the time or the IT resource to implement the data collection. Even if you use a cool technology like tag management, it may be that the data you want to add comes from an isolated system. And that it would take too much effort to transport the data from it’s home all the way to the web server.

Dimension widening can be seen as a somewhat faster, less IT intensive way of joining your data together.

Things to be aware of…

Ok, a few things that you need to be aware of when using Dimension widening.

1. Your data is NOT applied to historical data. Your data is only applied going forward.

2. You can NOT widen on ALL dimensions. You can NOT widen on the following dimensions:

  • custom variables
  • product dimensions and metrics
  • campaign dimensions
  • time-based dimensions (hour, minute, etc)
  • geo-dimensions (country, city, etc)

3. If you would like to expand your dimensions and populate Custom Dimensions you MUST use Universal Analytics. The reason is that Custom Dimensions only exist in Universal Analytics. They do not exist in the previous version of Google Analytics.

4. You can not change a schema once it has been entered into Google Analytics. You must delete the schema and then define your new schema.

I know some of these caveats may seem limiting, but remember, this is just the initial version. I know the team is working hard to expand the functionality.

Do you think you will use Dimension widening? If so how? Feel free to share your examples below!

Be Sociable, Share!

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

    Comments

    1. says

      This is awesome and is definitely something more people should implement. It is surprising how much of a skewed pictured the data in GA can give when not viewed in context. For example, an advertising source may appear to be the most effective due to the revenue it generates but if it is operating at a loss due to a high cost, it’s actually not effective at all.

      It’s great to know it’s now even easier to get the whole picture.

    2. Eduardo Cereto says

      Also worth mentioning that it’s still forbidden to send PII (Personally identifiable information) into Google Analytics and Dimension Widening doesn’t change that.

      You can’t use a generic dimension to widen and add PII information

    3. says

      Using Dimension Widening to import data directly to Google Analytics gives great insight. With this information Marketing and analytics will come into handy and will be more useful.

    4. Leon Cappel says

      Hi Justin,

      Thank you for providing so much information – it already helped me a lot :-)

      I’m trying to get my head around one thing though: how do you link the custom dimensions and custom metrics from UA to existing dimensions? Or can that only be done with dimension widening?

      I ask this, because I’m trying to enhance the Site Search report with things like ‘average nr of results’, ‘no results’, ‘times facet used’, ‘rank of clicked result’. And I don’t know how to connect the search term to ‘times facets used’.

      In dimension widening you can give a key to connect the imported data with the existing data. Is this possible just with the javascript for custom dimensions and metrics added to the search result page?

    5. Ranyere Rodrigues says

      The translation files feature available in paid-for tools has finally arrived – great stuff! GA is not only leading/pushing the analytics market but also catching up, and as a result becoming a more robust and comprehensive tool. When (if, although it could be more a matter of when than if) personally identifiable information is allowed, than GA will be sending a serious message to its competitors.

      Do you agree, Justin?

    6. says

      How would Google Anaytics feel if on upload data about a public figure was included. For example If someone wanted to use Anlytics to process data using on court performance of NBA players or politcal data? Is that considered PII or something else? A bit of a hypothetical but wonder your thoughts?

      • says

        @Glenn: Hmm…. Interesting question. My first response is that you can not add anything personally identifiable to Google Analytics, that includes name, email address, IP address, etc. Second, I don’t think Google Analytics would process the data you reference effectively. GA is a digital analytics tool. And while you could massage the data you specify to fit into GA, I’m not sure it would give you good results.

    7. Evan Parker says

      It seems like, depending on what you’re looking to do, segmentation could still be more valuable than dimension widening.

      In the above example, adding the publishing year doesn’t seem to add much, as the year is in the URL and thus easily segmented. PLUS, segmentation allows a rearward-looking view, unlike dimension widening. But, for things like cost/revenue data, dimension widening seems like it’s the way to go.

      How cool would it be if there were two-way integration with Google Tag Manager? You could establish a macro in GTM that pulls, say, a goal value from Google Analytics that you uploaded via dimension widening, and then fires tags based on that. For example, when someone visits a page that has a high micro/macroconversion value, a remarketing tag is fired.

      • says

        @Evan: Your correct, adding year published may not be the best example. I was just working with what I had :) But not all sites have the year in the URL. In fact many are moving away from that. Regardless, the point is that any data can be imported to GA.

        And I love your suggestion about GTM/GA integration. I think that falls into the Personalization category, which is all the rage right now.

    8. says

      Nice improvement !
      I’m just wondering why it is not applied to historical data (like SAINT classifications in Omniture world) and without date range application if we can use it on campaign and product dimensions… :(
      Can we get these two capabilities on the Premium version ?

    9. says

      Thank you Justin for the bright explanation.

      I think that the last features in Analytics (UA etc.) are going to change this tool from “for every user” tool to PRO’s one
      /-:

      • says

        @Shuki: Thanks for the feedback. I think the goal of Google Analytics is to provide an enterprise class tool to everyone. But the challenge is to manage the features so they are approachable and easy to use. We’ll certainly take try to make GA easy to use for everyone.

    10. says

      This is really awesome! It is going to simplify most of the consolidation burdens that I now need to treat with events.
      BUT… if we need to create a new view, we will be either losing past history or loosing the current widening when we widen in current views sometime in the future.
      If I recall, UA didn’t support some features… Should we migrate all accounts in which we intend to widen to UA before widening? Or, will there be a merge tool in the future? ( remain with ga.js + create new UA view in which to widen and merge them in the future)
      Thanks a lot for your wisdom on this one.

      • says

        @xavier: Great question. Universal Analytics is very close to standard GA. If there are features in GA that do not exist in UA, and you need those features, then wait. There will be feature parody and there is a migration tool. BUT, you can choose to use Dimension Widening now, and when you migrate to UA all of that data will also be migrated.

    11. Evan Parker says

      Can you use this method to tie back to individual events or visits?

      The reason I ask is because we’d like to feed in as much data as possible from our call tracking system (Mongoose Metrics) into GA. Could we use a unique (to the call, not to the person – no PII involved) call “serial number”, pass that in as a custom dimension to GA, and then import attributes like call duration, operator who handled, etc. into GA along that primary key?

    12. Ilya Klestov says

      I’m not sure I fully understand that :
      Your data is NOT applied to historical data. Your data is only applied going forward.
      How it will works if I want to import the Cost Data manually.

    13. Brenton says

      Do you know why I am only seeing Behavior, Custom Dimensions, and Visitors for selecting my Widen-To dimensions and metrics? I would like to use some under conversions. I have eCommerce tracking on and using Universal Analytics.

        • Brenton says

          Thanks Justin. In the meantime, do you know of a way to update transaction revenue data in GA with my own data? After orders are submitted, they can be touched in a number of ways and sometimes that $ value changes. I would like to import the true revenue amount back into GA. Any ideas?

          • says

            @Brenton: The only want to change the data is to submit ANOTHER transaction, with the same transaction ID. This will cause GA to update the transaction value. For example, if the original transaction was $100, and you submit another transaction with a value of -$30, then the transaction will now have a value of $70. But note, that this does not change all of your historical data.

    14. Stan says

      Justin, thanks for great post!
      You mentioned “product data (using the product ID as a key)” widening.
      How can that be done? There is no such key in the “key” drop down.
      Custom dimension?

    15. says

      Great article @Justin – just wondering why we can’t do dimension widening for custom variables? Is it limit by system? I think if we would like to map CRM data into GA data – we may need to use custom variable to widening with custom dimension?

    16. Mark Terry says

      Could you use a Custom Dimension to record a user ID, then when a contact form is submitted, apply that user ID to a CRM (much like an order number)? Dimension widening could then be used by using the same user ID via csv or the API.

    17. says

      I must understand something – when you wrote that “Your data is NOT applied to historical data. Your data is only applied going forward” – how did you applied the year and the author name to the URLs?

      • says

        @Shuki: When you use dimension widening, google analytics does not apply the imported data to your historical data. Data that has already been processed can not be update or changed. So if you import data it will not be applied to your historical data. In my example I applied the value of author and year by linking it to the data using the URL as a key. But author and year values are not applied to historical data. I hope that makes sense.

    Trackbacks

    1. […] both options to a couple of different exam questions, so they’re definitely worth reviewing. Dimension widening, according to Google’s Justin Cutroni, allows you to import additional metr…. Measurement protocol is something entirely different. It’s a part of Universal Analytics […]

    Leave a 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=""> <strike> <strong>