Snapshots give you the ability to capture additional metadata about actions that are occurring on your site. For example, if a user enters a search query, you might also want to know the actual search query they entered. If a user adds an item to their shopping cart, you might want to know the item name, star rating, and price of the added item.

Normally, you'd have to resort to custom tracking code to bring in additional properties. With Snapshots, however, you can snapshot relevant data from a page and attach them to events without the need to write extra code.

You must be an Architect or Admin in Heap to access Snapshots. For more details about default permissions, see Teammates and Permissions.

To get started, just launch the Event Visualizer, select an element, and then click 'Add Snapshot'. Below is an example of how to use Snapshots to capture the text provided in an email field.

Alternatively, you can use Custom Properties by going to the Events tab, clicking '+ Set Property', and manually configuring snapshotted data for use in custom properties.

Use Cases

Capture Screen Dimensions & Orientation

To capture screen dimensions, set up a Graph and group by this property to make sure that your product looks good on all the most popular screen sizes. This is handy for both designers and product managers.

Name: Screen Dimensions

Snapshot: window.screen.width + ' x ' + window.screen.height

An example screenshot of how this would look on the Event details page in Heap can be found at the bottom of this doc.

You can also capture their screen orientation (on pageload only: APIs for tracking orientation changes are not supported across all popular browsers). This is helpful for understanding how users are consuming your content. Is your site optimized for landscape viewing? Most are not. This gives you the data to understand if it’s worth optimizing. With increasingly large mobile devices, this might become more useful over time.

Name: Screen orientation

Snapshot: (function() { if(window.innerHeight > window.innerWidth){ return "Vertical" } else { return "Horizontal" } })();

Call APIs

Snapshots can be used to call arbitrary JavaScript; this snippet adds your users’ most current timezone as a property. Once captured, you can create and add these segments to your analysis to understand how well your geographically targeted ads are performing.

Name: Add timezone as user property

Snapshot: (function() { var tz = Intl.DateTimeFormat().resolvedOptions().timeZone; heap.addUserProperties({ "Timezone": tz }); })();

Check if Users Have Enabled Browser Push Notifications

On modern browsers, you can check how many of your users have enabled your browser push notifications. You can do something similar for checking location permissions if your app depends on it. (This is only supported in select modern browsers.) If no one is allowing them, is it worth supporting? On the other hand, if you have great adoption but no one clicks on them, then perhaps your copy could use some work.

Name: Add push notification status as user property

Snapshot: navigator.permissions.query({ name: 'notifications' }).then(function(result) { heap.addUserProperties({"Notifications Permission": result.state }); })

Capture User State

This example captures the logged-in user state from a site using Tealium. Other common examples include page_type, site_section, or visitor_type. Use this type of data for high-level content analysis, or to understand how user state affects key behaviors. For example, do your users tend to buy more if they can get through checkout quicker because they are logged in with their saved data?

Name: Logged In

Snapshot: utag_data.customer_logged_in

Analyze Image Types

eCommerce companies often AB test their images. But how can you tell which type of photography converts best: a lifestyle action shot vs a standard product shot? This example captures name of the the image file when clicked. Assuming you have some semantic data in the title that denotes the shot type, you can use this data within a Defined Property to analyze the effectiveness of different image types.

Name: Image

Snapshot: $('src').split('/').pop()

This example requires jQuery on your website to execute correctly.

Capture Page Load Time

Due to DOM event timing, this can’t be added as an event property, though you can write code similar to the Call APIs use case and fire a track call with the property. See how page load time affects your key funnels by starting your analysis with this event and grouping by load time!

Name: Page load

Snapshot: (function() { var interval = setInterval(sendTrack, 200); function sendTrack() { if (performance.timing.domComplete != 0){ var loadTime = (performance.timing.domComplete - performance.timing.navigationStart) / 1000; heap.track('Page Load', { 'Load Time': loadTime }); clearInterval(interval); } } })();

Navigation timing events do not update after changes to the History API. The above method will not work on Single Page Applications.

Types of Custom Properties

Custom properties are configured on a per-event basis and are limited to 255 characters. There are two ways to snapshot data:

  • Text in Element: Specify a DOM element selector. Then, each time someone interacts with the element defined in the event, the full text inside the first matching DOM element gets extracted, trimmed, and attached to the event as a property. Direct descendent selectors and pseudo-classes are supported in Custom Properties for more fine-grained targeting.
  • Value of Javascript: Specify any Javascript expression. Then, each time someone interacts with the element defined in the event, the Javascript expression gets evaluated, and the return value gets attached to the event as a property. In your Javascript expression, you can use the variable event to refer to the triggering DOM event. For instance, a Javascript property of $('data-id') will attach the value of the data-id attribute of the target element each time the event occurs.

This example requires jQuery on your website to execute correctly.

Any changes to a custom property take effect in less than 5 minutes. Unlike autocaptured event properties, custom properties are not retroactive.

Custom properties are triggered by a user's interaction with the CSS selector in the defined event. As a result, they are available to use in analyzing the events on which they were defined, but will also be applied to other defined events if another event definition uses the same selector.

Note: Custom properties are not yet available for iOS.

Pageview Snapshots

When using the visualizer as presented above, you're able to define custom properties that are attached to interaction events (clicks, form submissions, etc.). If you're looking to apply custom properties to a pageview event when a page loads (and all subsequent events on this page), then you'll need to define a Pageview Snapshot within our Events tab manually.

Pageview Snapshots allows you to attach custom properties to any pageview as well as all events that occur on that pageview. This allows you to enrich your data set by adding custom properties through a point-and-click interface or custom JavaScript written in Heap’s UI. This means there's no need to commit to your codebase and wait for a release cycle.

Using Pageview Snapshots, you can:

  • Add properties (such as logged-in state) to analyze how behavior changes when a someone is logged in vs. logged out (similar to our addEventProperties API example).
  • Understand how the number of items in a cart impacts consumer behavior, or add category information to all events in an eCommerce browsing experience.
  • Complement Heap data with metadata that already exists in your data layer. Simply add properties you store on the client side in a JavaScript object to automatically attach to all events that Heap captures.
  • Call other client-side methods to trigger other behavior or send event data to other services when a pageview event occurs.

To attach a custom property to a pageview:

  1. Define an event for the pageview event of interest
  2. Add a custom property from the text in an element or through a custom JavaScript expression

Here's an example of our use case for capturing Screen Dimensions with Snapshots:


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.