Shopify Installation

Installing Heap on your Shopify store will allow you to track your shop’s click events and pageviews in real-time. Once installed, Shopify events will include data going back to the date you installed Heap.

Installation

To install Heap in your Shopify store, you will need to insert the code snippet below into your shop’s theme file.

Navigate in Shopify to the theme.liquid file associated with your shop’s theme. Follow Shopify’s Editing theme code instructions if you do not know how to access this file.

<script type="text/javascript">
    window.heap=window.heap||[],heap.load=function(e,t){window.heap.appid=e,window.heap.config=t=t||{};var r=t.forceSSL||"https:"===document.location.protocol,a=document.createElement("script");a.type="text/javascript",a.async=!0,a.src=(r?"https:":"http:")+"//cdn.heapanalytics.com/js/heap-"+e+".js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(a,n);for(var o=function(e){return function(){heap.push([e].concat(Array.prototype.slice.call(arguments,0)))}},p=["addEventProperties","addUserProperties","clearEventProperties","identify","removeEventProperty","setEventProperties","track","unsetEventProperty"],c=0;c<p.length;c++)heap[p[c]]=o(p[c])};
    heap.load("YOUR_APP_ID");
    var customerId = '{{ customer.id }}';
    var customerEmail = '{{ customer.email }}' || '{{ checkout.email }}';
    heap.addUserProperties({'Name': '{{ customer.name }}','email': customerEmail,'CustomerID':'{{ customer.id }}','TotalSpent':'{{ customer.total_spent }}'});   
</script>

Make sure the snippet is between the <head> tags:

Once you have saved the snippet, you will begin to see Shopify events coming into Heap via the Live data feed.

You can collect additional types of data, such as the customer's name or the total amount they spent, by adding them into the theme.liquid page via Heap's addUserProperties API. You can add as many calls as you want to this snippet.

Tracking Checkouts

In addition to the installation snippet, add one of the scripts below to your checkout page. This will ensure that Heap is tracking checkouts.

The script you use will depend on if your shop has Shopify Plus or not. Please check if you use Shopify Plus to ensure you pick the correct script for your shop.

How to add a checkout snippet to your shop:

  1. In your Shopify account, navigate to Settings > Checkout and accounts > Checkout settings and find the Order Status section. Follow Shopify's instructions for customizing the order status page if you are unable to locate this section.
  1. Based on your use case, insert one of the below scripts into the Additional scripts box and click Save. You only need to use one of these scripts:

You DO NOT have Shopify Plus

<script>
window.heap=window.heap||[],heap.load=function(e,t){window.heap.appid=e,window.heap.config=t=t||{};var r=t.forceSSL||"https:"===document.location.protocol,a=document.createElement("script");a.type="text/javascript",a.async=!0,a.src=(r?"https:":"http:")+"//cdn.heapanalytics.com/js/heap-"+e+".js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(a,n);for(var o=function(e){return function(){heap.push([e].concat(Array.prototype.slice.call(arguments,0)))}},p=["addEventProperties","addUserProperties","clearEventProperties","identify","removeEventProperty","setEventProperties","track","unsetEventProperty"],c=0;c<p.length;c++)heap[p[c]]=o(p[c])};
    heap.load("APP ID");
const flattenObject = (data, prefix) => {
      let result = {}
      for (var key in data) {
        var currentPrefix = key;
        if(prefix) currentPrefix =  prefix + '.' + key;
        if (typeof data[key] == 'object' && data[key] !== null) {
          var flatten = flattenObject(data[key], currentPrefix)
          result = { ...result, ...flatten }
        } else {
          result[currentPrefix] = data[key];
        }
      }
      return result
    }
{% if first_time_accessed %}
    window.Shopify.checkout.line_items.forEach((lineItem) => {
      heap.track('Purchased line item', flattenObject(lineItem));
    });
    
    // Remove line items from the checkout event. They were sent as individual events. 
    let checkoutEventProperties = {...window.Shopify.checkout}; 
    delete checkoutEventProperties.line_items;
    heap.track('Checkout', flattenObject(checkoutEventProperties));
    heap.addUserProperties({email: window.Shopify.checkout.email, customer_id: window.Shopify.checkout.customer_id})
{% endif %}
 </script>

You have Shopify Plus

<script>
const flattenObject = (data, prefix) => {
      let result = {}
      for (var key in data) {
        var currentPrefix = key;
        if(prefix) currentPrefix =  prefix + '.' + key;
        if (typeof data[key] == 'object' && data[key] !== null) {
          var flatten = flattenObject(data[key], currentPrefix)
          result = { ...result, ...flatten }
        } else {
          result[currentPrefix] = data[key];
        }
      }
      return result
    }
{% if first_time_accessed %}
    window.Shopify.checkout.line_items.forEach((lineItem) => {
      heap.track('Purchased line item', flattenObject(lineItem));
    });
    
    // Remove line items from the checkout event. They were sent as individual events. 
    let checkoutEventProperties = {...window.Shopify.checkout}; 
    delete checkoutEventProperties.line_items;
    heap.track('Checkout', flattenObject(checkoutEventProperties));
    heap.addUserProperties({email: window.Shopify.checkout.email, customer_id: window.Shopify.checkout.customer_id}
{% endif %}
</script>

The Checkout custom event being sent into Heap has the properties available on the {{ checkout }} liquid object from Shopify. A list of the properties included in the {{ checkout }} object can be found in Shopify's checkout docs.

You’re ready to check out how many users are purchasing items from your site! For more help customizing your Shopify page, visit Shopify’s documentation.

📘

For customers using ReCharge Apps app with Shopify

Subscriptions by ReCharge is a popular eCommerce app that integrates with Shopify. To successfully track the entire customer journey across both Shopify checkout and ReCharge checkout, contact ReCharge support for assistance setting up ReCharge on your own domain. If you have any questions, feel free to contact [email protected]!

Tracking Identity (optional)

If you are unsure about your identity schema, see our Using Identify guide.

If you already call heap.identify with email in another part of your codebase, and you plan on sending Shopify data to the same Heap environment, use the email option listed below.

Do not use the heap.identify calls listed below if you use a different property (not email or customer id) to identify users. This will cause one user to show up as two distinct users and pollute your dataset.

Note that this only applies when you’re sending data to the same Heap environment.

Identities in Heap should always be globally unique for each unique user so you can track user activity across sites and platforms. When a user is identified, their past sessions and event activity from when they were anonymous are now tied to that identity. This allows the user to use multiple devices/browsers to access your website with a single identity.

Heap uses Shopify liquid variables to call the identify API, which look like this: {{ customer.email }}.

You can identify Shopify customers in Heap via their Shopify Customer ID or email. The Shopify Customer ID is the unique ID that Shopify assigns to each unique customer who shops in your store. You can learn more about this in Shopify's dev docs.

Here are some important considerations when choosing your identifier for Shopify:

  • If you have customers who check out with something besides email, such as if they signed up via their phone number, then you should use Shopify Customer ID as your identifier.
  • If you have multiple Shopify stores, and you want to analyze user activity across different stores, you should use email as your identifier. This allows you to track activity across your Shopify stores.
  • If you have a Shopify site and other sites not hosted by Shopify, you should use email as your identifier. This allows you to track user activity across different stores.

For an in-depth explanation of identity along with examples, see the Using Identify guide.

Identifying your users

If you want to identify your users, you’ll need to add one of the heap.identify calls below to your checkout page. Review the identity information above to choose the correct snippet.

  1. In your Shopify account, navigate to Settings > Checkout and accounts > Checkout settings and find the Order Status section. Follow Shopify's instructions for customizing the order status page if you are unable to locate this section.
  2. Paste the appropriate snippet before the closing script tag: </script>
var customerEmail = '{{ customer.email }}' || '{{ checkout.email }}';
    heap.identify(customerEmail);
var customerId = '{{ customer.id }}';
    heap.identify(customerId);

Known Limitations

  • We recommend that you have login enabled. If you do not have login enabled, we will not be able to identify users by their customer.id or customer.email until after they have completed the checkout process.

Multiple Shopify Stores

If you want to install Heap for multiple Shopify stores for cross-site tracking, reach out to us via the Get support page.