You can use a Text in Element Snapshot to capture data, such as the size of an item, as an event property on an event.

In the example below, we define an event on the Add to Cart element, and we capture the selected size as Size. The first step is to use visual labeling to define an event on the Add to Cart element. Once we’ve selected the element for our event, we can click Add Snapshot… in the visual labeling interface to add a Snapshot on this event:

To capture the size of the item added to the cart, we’ll set our Snapshot to Text in Element to capture the text within a specific element (1). We’ll name our Snapshot what we want the property to be called in Heap (2). 

Next we’ll use the Snapshot selector tool (3) which allows us to target an element on the page (similar to how we defined the event). With the Snapshot selector tool enabled, we’ll click the element we want to capture as a Snapshot (4). If all goes well, you should see a preview of what the property will look like once it’s captured:

Once saved, the event will trigger whenever a user clicks the Add to Cart button, and the Snapshot will capture the size of the item as a property named Size.

Once it’s been saved, you can review and update the Size Snapshot definition on the event details page.

You’ll also be able to group by the Size Snapshot in analysis.

Capture Name of Item When Item is Clicked (Multiple Events on Page)

The previous example demonstrates how to define a Snapshot for a single element on the page; what if there are multiple elements on the page that can trigger the event all with their own elements we want to capture as Snapshots?

Below is an example of this; there are multiple elements that can trigger our Click on Item event, and we want to capture the name of the item that’s clicked as a Snapshot. To capture the item names as a Snapshot, simply use the Snapshot selector tool (1) and select one of the item names (2). 

Heap will automatically detect that the item name is associated with the closest event; once the event is saved, whenever a user clicks on an item, Heap will traverse the page to capture the corresponding item name as a Snapshot property.

Just like the above, this new Snapshot will show up on the event details page, and be available for you to group by in analysis.

Capture Company Name From Sign Up Form (Text Input Field)

To capture users’ inputs on an input field, such as a text input, we can use the Form Value Snapshot to capture the value of an input field. 

In the example below, we have an event defined on the Get demo button, and we want to create a Snapshot that captures what the user inputs for Company Name. We’ll want to make sure that our Snapshot is set to Form Value (1), and we can use the Snapshot selector tool (2) to define a Snapshot on the text input field (3).

Once it’s been saved, you can review and update the Company Name Snapshot definition on the event details page.

You’ll also be able to group by the Company Name Snapshot in analysis.

Capture Search Queries

To capture search queries entered into a search bar, we can use Text to Element to capture the text in that element.

In the example below, we have an event defined on the Help Center search toolbar, and we want to create a Snapshot that captures what the user types in as a search query. We’ll want to make sure that our Snapshot is set to Text in Element (1), and we can use the Snapshot selector tool (2) to define a Snapshot on the text input field (3).

Once it’s been saved, you can review and update the search Snapshot definition on the event details page.

You’ll also be able to group by the search Snapshot in analysis.

Capture Radio Form Value 

We can also use the Form Value Snapshots to capture users’ inputs for elements such as radios and checkboxes. The example below demonstrates how to define a Form Value Snapshot for radio buttons (this is the same process for checkboxes).

In order for Heap to detect that all of the radio buttons are related, the name attribute for the input must be the same for all radios in the group. In the example below, each radio has name=”role-card”.

We’ll want to make sure that our Snapshot is set to Form Value (1), and we can use the Snapshot selector tool (2) to select one of the radio buttons in the group. 

Once it’s been saved, you can review and update the Role Snapshot definition on the event details page.

You’ll also be able to group by the Role Snapshot in analysis.

Capture Screen Dimensions

You can capture screen dimensions to attach to a pageview event by using the JavaScript snapshot below. We recommend attaching this event to a ‘view any page’ event, which will attach it to all pageviews.

Name: Screen Dimensions

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

To analyze this Snapshot, 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.

An example screenshot of how this would look on the Event details page in Heap can be found in the Pageview Snapshots section below.

Capture Screen Resolution

Finding the pixel to device ratio of your user’s screens can help you understand how your images are rendering. Note that this property returns a value of 1 or 2. Read more in the Window.devicePixelRatio article from Mozilla.org.

Name: Screen Resolution

JavaScript Snapshot: window.devicePixelRatio

Capture Orientation

You can also capture 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. This gives you the data to understand if it’s worth optimizing for different views. Use the snapshot below to capture screen orientation:

Name: Screen orientation

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

Using Snapshotted Data in Custom Properties

Custom properties are configured on a per-event basis and are limited to 255 characters. Any changes to a custom property take effect in less than 5 minutes.

Note: Custom properties are not yet available for iOS.

Pageview Snapshots

When using the visual labeling interface, 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 dataset 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 a logged-in state) to analyze how behavior changes when 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:

Snapshot Permissions

By default, only Admins and Architects can access Snapshots. You can set up custom roles to grant or revoke this permission for other roles.