Snapshots give you the ability to capture additional metadata that isn’t autocaptured by Heap out-of-the-box. Examples of what you can capture with Snapshots:
- Search queries entered by users in any search bar on your site
- The price, item name, or star rating of a product when it is added to a customer’s cart
- Form selections, such as if a checkbox, radio button, or date field in a form was clicked or not
Normally, you’d have to resort to custom tracking code to bring in these additional properties. With Snapshots, however, you can take a snapshot of this relevant data on a page, and attach them to events without the need to write extra code.
Community Quote
“One of the challenges our team has been faced with as of late is logging changes in product status (ie. in stock, sold out, backordered) for when we need to reference certain points in time. Through Heap, we were able to set up snapshots to capture the statuses for when a user engages with a product on the product page. So now when needed, we can just look at that certain day and what the engagement/statuses were.”
From Using snapshots to log changes in product status (ie. in stock, sold out, backordered)
Some important notes about how Snapshots work:
- Because you are defining new metadata for Heap to capture, Snapshots are not retroactive: they begin collecting data from the point when they were first created. So if you created a Snapshot on 3/16/2020, you will only be able to analyze that Snapshot data going all the way back to that date.
- Snapshots fire based on event definition selectors only, regardless of event definition filters. Any event definition filters present will not prevent a Snapshot from firing.
- Archiving and then restoring archived events with Snapshots results in the loss of data from the duration of time when the event was archived.
- Snapshots are not supported for mobile installations. However, they are supported on web mobile installations, including WebViews.
Creating Snapshots
Before we begin, let’s go over the different types of Snapshots you can create:
- Text in element: An element of your page as described in the DOM element selector. Each time someone interacts with this element, the full text inside the nearest matching element gets extracted, trimmed, and attached to the event as a property.
- Form Value: The value of a form field. If you’re using Snapshots to capture the text added to a form field (like our example), this is what you should select.
- Value of JavaScript: Specify any Javascript expression. Each time someone interacts with this element, the Javascript expression gets evaluated, and the return value gets attached to the event as a property. To see examples of see Executing JavaScript using Snapshots.
Note that once your Snapshot is saved, it will take 2-10 minutes for that change to show up in your heap.js file. Once heap.js is updated, it should show up in the dashboard immediately after it’s captured.
Create Snapshots via visual labeling
Snapshots can only be added to shared events, not personal events.
You can define new Snapshot properties to be attached to a new event via the visual labeling interface. This flow is meant for a use case where you are creating a new event and a snapshot at the same time. If you’re looking to create a snapshot to add to an existing event, see Add Snapshots via the Events Page.
To create a Snapshot via visual labeling, complete the steps below:
1. Launch the visual labeling interface and select the element on the page you want to configure a Snapshot for. In an example from Heap’s contact page, we may want to collect and analyze responses to the ‘What can we help you with?’ question, so we’ll click on this element.
2. A pop-up will appear for you to define the event. Click the Add Snapshot button at the bottom of that pop-up.
3. In the next section, choose the type of Snapshot, add a property name, and define the element via it’s CSS selector. Click the snapshot target icon to bring up a visual element selector.
4. Click the Add Snapshot button, which will take you back to the define event section. Click Next, complete the create definition fields, then click Define Event to save your new event with snapshotted data.
Add Snapshots via the Events Page
To create a snapshot to add to an existing event, complete the following steps:
1. Navigate to Definitions > Events and click on the event you want to add a Snapshot to.
2. On the event details page, click the + Add Snapshot button, then configure the Snapshot fields. You can use the Property Name field to add an existing Snapshot, or create a new one by adding the new Snapshot name and setting the rest of the fields.
3. Last but not least, click the Update Event button to save this Snapshot to your event.
Use Cases
For a full set of Snapshot use cases, see the Snapshots section of the Help Center.
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.