Chapter 06

Data layer: how to pass blog category data

By Anna Tomalik

In the previous chapter, we showed you how to pass blog author data using a CSS selector. But there’s another way to access data on your site or app –– a data layer.

A data layer is a space where you can store information and use it for your tags, triggers and variables. Your developers can create the data layer by writing it into the page code. For example, information about a blog post in the data layer could look like this:

<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
 'blogCategory': 'Home budget'
 'blogAuthor': 'John Doe'
 });
</script>

This command window.dataLayer = window.dataLayer || []; creates a data layer. This command window.dataLayer.push() adds information to the data layer using key-value pairs. In our example, the key-value pairs are:

  •  'blogCategory': 'Home budget'
  •  'blogAuthor': 'John Doe'

As you can see, the key is a category of things like a blog category or blog author. Each key can have different values. For example, a blog category key can have values like ‘Home budget’, ‘Savings’, ‘Investments’ and the like.

If you don’t want to ask developers for help with adding a data layer to the page source, you can also use a tag to push that information to the data layer and then access it. We’ll show you how it can be done in an example.

For developers: The default data layer name is dataLayer, but you can change it to a custom one. Read more

Add the data layer to a page

Let’s say we’d like to access data about a blog category on our site. We can’t access it with a CSS selector, so we need to hard-code a category to each page.

To add the data layer to a page, follow these steps:

  1. Go to Menu > Tag Manager.
  2. Navigate to Tags.
  3. Click Add new tag.
  4. Name the tag. Example: (data layer) Blog category.
  5. Choose the following tag type: Custom code (async).
  6. In Tag code, we’ll paste the following code:
    <script>
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
     'blogCategory': 'Home budget'
     });
    </script>
    Data layer script in Piwik PRO

    Note: Our key-value pair is:  'blogCategory': 'Home budget'. You can replace it with your data.

  7. In Tag triggers, click Add new trigger.
  8. We’ll create a page view trigger that will run only on a page with a 'Home budget' category.
    Page view trigger in Piwik PRO

    Note: If we wanted to add information about the 'Home budget' category to other blog posts, we would add more triggers with the correct page URLs. The tag fires when any of the attached triggers is present.

  9. Click Save for the tag.

    Now we’ll do one more thing. We’ll set this tag as a priority so that it fires before other tags. This way, we’ll make sure that the information it contains will be available for all variables and tags.

  10. Navigate to Settings.
  11. On the left, click Tag priority.
  12. Drag your tag to the priority list.
    Prioritized tags in Piwik PRO

    Note: Even if you prioritize tags, they will fire when they are triggered. Remember that triggers control tags, and always check triggers when your tags don’t fire the way you want them to.

  13. Click Save.
  14. Click Debug.
  15. We’ll go to the page with the 'Home budget' blog category.
    Blog post category on a site
  16. Check if the tag fired for this page view.
    Debug mode in Piwik PRO
  17. When you’re happy with how the tag works, click Publish.

Okay, we’ve set the data layer for our blog page. Now we need to pass the information that it holds to Analytics. For that, we’ll use a variable and custom dimension. Read on.

Add a data layer variable

When you want to pull some data from your data layer, you can use a dedicated data layer variable.

To add a data layer variable, follow these steps:

  1. Go to Menu > Tag Manager.
  2. Navigate to Variables.
  3. Click Add new variable.
  4. Name the variable. Example: Blog category.
  5. Select the following variable type: Data layer.
  6. In Data layer variable name, type the key exactly as it is written in the code. In our example, it’s blogCategory.
    Data layer variable in Piwik PRO
  7. Click OK.
  8. Click Debug.
  9. We’ll go to the page with the 'Home budget' blog category.
    Debug mode in Piwik PRO
  10. Navigate to Events log in debug mode.
  11. Click stg.PageLoad on the event list.
  12. Navigate to Variables.
    Debug mode in Piwik PRO
  13. Look for your variable on the list and see if the value is assigned correctly.
    Debug mode in Piwik PRO
  14. If everything looks okay, go back to Tag Manager and click Publish.

Done! Your variable now holds information about the blog category. As the last step, we need to set up a custom dimension to pass that data to Analytics.

Add a custom dimension

To add and set up a custom dimension, follow these steps:

  1. Go to Menu > Analytics.
  2. Navigate to Settings.
  3. On the left, click Custom dimensions.
  4. In Event dimensions, click Add an event dimension.
    Custom dimension in Piwik PRO
  5. Name the dimension.
  6. Click Save.
  7. After creating the custom dimension, note Dimension ID.
    Custom dimension in Piwik PRO
  8. Go to Menu > Tag Manager.
  9. Navigate to Tags.
  10. On the left, click Piwik PRO. This is the tag with the tracking code.
  11. In Collect data for custom dimensions, click + Add a dimension.
  12. Enter Dimension name from step 7.
    Custom dimension in Piwik PRO
  13. Enter Dimension value. This is our variable {{ Blog category }}.
    Custom dimension in Piwik PRO
  14. Scroll down to the bottom and click Save.
  15. Click Publish.
  16. You can quickly check if data is collected correctly by going to Menu > Analytics > Settings > Tracker debugger.
    Custom dimension in Piwik PRO

    Note: Data in the tracker debugger appears instantly. Data in reports appears in about 30 minutes.

  17. After data is collected, you’ll see it under Menu > Analytics > Reports > Custom dimensions.
    Custom dimension report in Piwik PRO
  18. You can also see your custom dimension under Analytics > Reports > Session log.
    Custom dimension in Piwik PRO

    Tip: You can also use your custom dimension in a custom report.

Note: In this chapter, we showed you how to use a data layer with key-value pairs. But sometimes you might want to use a data layer to add a new event. Then you can use the following functions:

  • dataLayer.push({event: 'event_name'});
  • dataLayer.push({event: 'event_name', event_key: 'event_value'});

The added events can be used in a data layer event trigger and tags.