Search Unity

Stoking the fire: Heatmaps Rekindled

June 29, 2016 in Games | 7 min. read
Topics covered

The heat is on!

Last year, Unity Analytics released our beta version of the Heatmap system. It arose from a hack week project, which itself came from a customer simply asking me to build it (see what you get when you ask nicely?). As it happens, I write this blog post on my way to another hack week, and here we are getting ready to release a major update to our Heatmaps plugin. This update is a big leap forward on several levels, focusing on both speed and usability. The beta was pretty good. I'm proud of what we released. But we listened very carefully to user feedback, finding several things we could do better. For example:

  • The first-time user experience, frankly, sucked.
  • It took way too long to get at your data.
  • There were many problems seeing the data quite the way you wanted it.
  • And, of course, there were some bugs.

The new release addresses all these issues, speeding you up both as a first-time heatmapper, and as you progress. We may never address everyone's ideas about the "right" ways to look at the data, but I'm convinced we've added many excellent options that will please many.

This post won't be a tutorial. That sort of thing is covered in the documentation. Rather, I'll focus on explaining the new features, and why we picked each one:

Installing Heatmaps

As part of improving your first time experience with Heatmaps, we've finally pushed it to the Unity Asset Store. You can still download the installer from the Bitbucket repo, of course. Double-click the installer and BOOM! you have Heatmaps in your project, at least to a degree sufficient to immediately take it out for a test drive.

With Heatmaps installed, you'll see not one, but two new Inspectors under Windows > Unity Analytics: Heatmapper and Raw Data.


Let's start with Raw Data.

Raw Data – at near real-time speed

Hiding under Heatmaps from the beginning has been a secret-not-so-secret service called "raw data". All this means is that we store each event as it arrives at the Unity Analytics server, then make it available for you to retrieve. Heatmaps fetches that raw data and aggregates it inside Unity to display your results.

The official version of raw data has just been released and here’s the headline: it operates at near-real-time speed. How 'near'? Let's call it in the range of seconds to minutes. We think this a vast improvement over the previous system that forced you to wait hours before you could get a glance at your data.

All users with Pro licenses get access to raw data...which means Heatmaps will shift into the ranks of a Pro Analytics tool (though all existing projects will be grandfathered into the Pro tier).


We've given Raw Data its own Inspector. By doing this we're signaling an essential and important idea:

Raw Data is separate from Heatmaps.

While we use raw data to populate heatmaps, Heatmaps are just one of innumerable potential applications of raw data. So put on your thinking caps, and ponder this question: how else could you leverage raw data by displaying it inside Unity? Let us know in the comments below, or better yet: build it and share!

Use Test Data to learn how the Heatmapper works


The new Raw Data Inspector fetches raw data. But it can also generate test data that stays right on your computer. Again, this is part of improving the first time user experience. It's now possible to create lots of data in order to see how the Heatmapper (or any other raw data tool) works. None of this data ever leaves your local just sits there, ready for you to consume it.

What can you generate? Here's a list:

  • Random heatmap events
  • "Demo" heatmap events that help explain Heatmap features/scenarios
  • Freeform (non-Heatmap) data so you can experiment with ideas of your own

With the data generation feature, you can instantly create thousands of points, load them into the Heatmapper, and understand the many capabilities that Heatmaps provides.

The Heatmapper itself – superior usability


The other Inspector is, of course, the Heatmapper. Our update brings no less than a dozen improvements to this tool. All of these improvements focus around superior usability.

Custom data location
Your raw data is still stored in `Application.persistentDataPath` by default, but you can now choose any arbitrary location. This is especially helpful when playing with test data.

Remap color to visualize areas of importance

Color in a Heatmap usually refers to density. That is, if an event happens a lot in one x/y/z location, we make that location appear "hotter" than a physical location where it happened less frequently. This is still the default behavior, but you can now specify any parameter to override density.

Why would you do this? Imagine you suspect that the FPS in your game is low in places. Send Heatmap events with fps as a parameter. When you build your Heatmap, you can now choose to remap color to the fps parameter and further select a calculation to perform on that parameter. By doing so, you can see "hot" colors where FPS is low, helping you isolate where these slowdowns occur.


Remap operations to dig deeper

In addition to simply being able to remap color to a parameter, you might want to operate on the result of that parameter. Take the prior case of mapping FPS. You're probably most interested in seeing the lowest recorded values (or something on a lower end of the spectrum), to find any places where there are failures. If you're looking at hit points remaining, the mean or median value might be more your thing. Maybe you want to see the first point, or the last. We've got you covered for each of these cases by allowing you to perform operations on points that occur in the same space. Here's the complete list of supported operations:

  • Display earliest point
  • Display latest point
  • Display highest value
  • Display lowest value
  • Incremental (adds 1 for each instance)
  • Additive (adds all values together)
  • Average
  • Percentile (0-100, Median = 50)

Separate to distill groups of data

This is actually several features that all do variations of the same trick (so credit me if you're keeping score): separate your results into distinct groups. Want to break apart Heatmaps by level? We can do that. See an individual play of the game? Sure! Separate your iOS users from Android? No problem. Each list appears separately under options, allowing you to break apart your Heatmap data in various useful ways. Here's the complete list of ways you can separate your data:

  • By user (unique device)
  • By unique play session (roughly equivalent to individual plays)
  • By platform
  • Separate debug builds from non-debug
  • By one or more arbitrary fields (such as 'level')

Render real gradients for optimal customization

The original Heatmapper used three color swatches to represeAnt low/medium/high color densities. No one liked that. We now use a true gradient to display your map.


And you can save gradients you want to have available for later.

Mask data to zero in on what matters

Nothing but a handy way to trim your data by location. When you have a lot of points in 3D, it can be nice to hide some of it.


Point-to-point rendering for enhanced spatial context

There are times when understanding more than one point can be helpful. Consider an event in a first-person shooter called "LookAt". You want to know not just where the player was when she looked at something, but what she looked at. A change to the HeatmapEvent now allows you to send two positions, not just one. And you can use point-to-point rendering to display the two points and their relative orientation.


Hot tips tell you what’s behind the data

Sometimes you look at an individual point and you really want to know exactly what that point means. It's kinda red, and is approximately near some point in your game, but what is it exactly? Hot tips is a tooltip-style addition that lets you mouse over any point and know the precise data that created it.


What will you map today?

We've given you what we hope is a powerful upgrade to your analytics tool belt. Let us know what you think. Let us know how you use it. We're always hoping to build the tools that serve you best, so don't be shy. Tell us what you need next.

June 29, 2016 in Games | 7 min. read
Topics covered