Skip to Content

Integrating Usermaven with UltraCart

This guide provides a complete, step-by-step walkthrough for a full-funnel, best-practice integration of Usermaven analytics on your UltraCart store.

By following this guide, you will achieve a powerful analytics setup that includes a professional, branded checkout experience and complete e-commerce funnel tracking from Add to Cart to Purchase. This allows you to understand the complete customer journey and pinpoint drop-off points with precision.

Prerequisites

Before you begin, please ensure you have the following ready:

  • Admin access to your UltraCart or StoreFronts interface.
  • An active Usermaven account.
  • Your unique Usermaven identifier and tracking code. For details on finding it, please see our guide on how to get your Usermaven identifier and tracking code.
  • Access to your domain’s DNS management (e.g., at GoDaddy, Cloudflare, etc.).

Part 1: Foundational setup — configure a custom checkout domain

This is the most critical step for a professional and robust setup. Using your own subdomain for checkout (e.g., checkout.yourstore.com) keeps customers within your branded environment and eliminates all cross-domain tracking complexities.

Step 1: Locate the custom hostname setting

This setting is in a different place depending on your UltraCart interface.

  • For the newer StoreFronts UI:

    1. Navigate to StoreFronts from the main menu.
    2. Click Settings → Domain. The Custom Host Name setting is here.

  • For the classic UltraCart UI:

    1. Navigate to Configuration from the main menu.
    2. Click Checkout → Custom HostName.

Step 2: Configure your domain & CNAME record

  1. In the appropriate Custom HostName field, enter the full subdomain you wish to use (e.g., checkout.yourstore.com).
  2. UltraCart will provide a Target HostName (typically ssl.ultracart.com). Copy this value.
  3. Log in to your domain registrar and create a new CNAME record pointing your chosen subdomain to the UltraCart target.
  4. Note on SSL: UltraCart will automatically provision a Let’s Encrypt SSL certificate for your new domain. This usually completes within 30 minutes of your CNAME record becoming active. If your SSL isn’t active after 24 hours, open a ticket with UltraCart support.

Part 2: Core tracking installation — pageviews & purchases

Now we will install the scripts to track all site-wide pageviews and the final, successful purchase event.

Step 1: Install the base script in your theme header

This loads the main Usermaven library on every page of your store.

  1. Navigate to Configuration → Checkout → Screen Branding Themes.
  2. Click Edit next to your active theme.
  3. Select the Screens tab, then click on Header to open its editor.
  4. Paste your standard Usermaven Tracking Snippet into the editor and click Save.

Step 2: Install the conversion script

This script runs on the “Order Complete” page to identify the customer and track the purchase.

  1. While still in the theme editor, click on the Conversion & Tracking tab.

  2. In an available text box, paste the following complete script block. Remember to replace YOUR_KEY with your actual Usermaven unique identifier.

    <!-- Usermaven loader (guarded) + Purchase tracking -->
<script>
  if (!document.getElementById('um-tracker')) {
    (function () {
      window.usermaven =
        window.usermaven ||
        function () {
          (window.usermavenQ = window.usermavenQ || []).push(arguments);
        };
 
      var t = document.createElement('script'),
        s = document.getElementsByTagName('script')[0];
 
      t.defer = true;
      t.id = 'um-tracker';
      t.setAttribute('data-tracking-host', 'https://events.usermaven.com');
      t.setAttribute('data-key', 'YOUR_KEY'); /* ← replace with your workspace key */
      t.setAttribute('data-randomize-url', 'true');
      t.setAttribute('data-autocapture', 'true');
      t.src = 'https://t.usermaven.com/lib.js';
      s.parentNode.insertBefore(t, s);
    })();
  }
</script>
 
<script type="text/javascript">
  // This script runs only after a successful purchase.
 
  // 1. Identify the user in Usermaven.
  if (window.usermaven && '[Email]') {
    usermaven('id', {
      id: '[CustomerProfileOid]',
      email: '[Email]',
      first_name: '[BillingFirstName]',
      last_name: '[BillingLastName]',
    });
  }
 
  // 2. Track the purchase event with financial data.
  if (window.usermaven && '[OrderId]') {
    usermaven('track', 'Purchase', {
      order_id: '[OrderId]',
      value: parseFloat('[Subtotal]'),
      revenue: parseFloat('[Total]'),
      currency: '[CurrencyCode]',
      shipping: parseFloat('[Shipping]'),
      tax: parseFloat('[Tax]'),
    });
  }
</script>

For more details on these functions, see our docs on Identifying Users and Tracking Events.

  1. Click the main Save button at the top of the theme editor.

Part 3: Advanced funnel tracking

This section is highly recommended. It allows you to analyze your complete sales funnel by tracking when users add items to their cart and when they start the checkout process.

Step 1: Track “add to cart” events

Choose the method that best fits your store’s theme.

This is the most reliable method for modern themes that use AJAX to update the cart.

  1. Navigate to Configuration → Checkout → Screen Branding Themes → Edit → Items tab.

  2. Edit the item template that controls your product pages.

  3. Scroll to the bottom of the template and add the following script block:

    <script>
  if (window.ucApp && window.usermaven) {
    ucApp.subscribe('itemAdded', function (payload) {
      usermaven('track', 'Add to Cart', {
        productId: payload.item.itemId,
        productName: payload.item.description,
        price: payload.item.cost,
        currency: payload.cart.currencyCode,
      });
    });
  }
</script>

Method B (For classic/non-AJAX themes): Use onclick

  1. In your item template (same location as above), find the HTML for your “Add to Cart” button (e.g., <input type="submit">).

  2. Add the following onclick attribute directly to that HTML tag.

    onclick =
  "usermaven('track', 'Add to Cart', {
    productId: '[ItemId]',
    productName: '[ItemName]',
    price: parseFloat('[Cost]'),
    currency: '[CurrencyCode]' });
  return true;";

Pro Tip: Token availability (e.g., [ItemName]) can vary by theme. To verify the correct tokens for your theme, go to the Screens tab in your theme editor and click the Template Context link.

Step 2: Track “begin checkout” events

This event fires when a user arrives at the first page of your checkout flow.

  1. Navigate to the Screens tab within your theme editor.

  2. Identify the first screen in your checkout flow. It might be named ‘Customer Profile’, ‘Shipping Information’, or simply ‘Checkout’. Click its name to edit the template.

  3. Scroll to the very bottom of the template editor and paste the following code block:

    <script>
  if (window.usermaven && '[Subtotal]') {
    usermaven('track', 'Begin Checkout', {
      value: parseFloat('[Subtotal]'),
      currency: '[CurrencyCode]',
      item_count: parseInt('[Items]'),
    });
  }
</script>

  4. Save the template, then save the theme.

Part 4: Verification and testing

After completing the setup, perform a full end-to-end test to ensure all events are firing correctly.

  1. Test the funnel: Go to your live store. After each action, check your Usermaven Events Stream in a separate browser tab to see the events appear in real-time.

    • Click “Add to Cart” on a product.
    • Proceed to the checkout page.

  2. Test a full purchase: Complete a test purchase from start to finish. We recommend using a 100% off coupon code.

  3. Confirm the conversion event in your browser: On the final “Thank You” page, use one of the following methods to confirm the event fired correctly from your browser.

    Method A: Check the console (quick test)

    1. Open your browser’s Developer Tools (F12) and select the Console tab.
    2. Run this command: 
      window.usermavenQ && console.log(window.usermavenQ);
    3. Expected Result: You should see an array of events. This may include auto-captured events. Verify that your explicit identify and track('Purchase', ...) calls are present.

    Method B: Inspect the network request (definitive test)

    This is the most reliable method, as it shows the actual data sent to Usermaven’s servers.

    1. Open your browser’s Developer Tools (F12) and select the Network tab.
    2. In the “Filter” box, type events to isolate the tracking requests.
    3. After your purchase is complete, a new request to https://events.usermaven.com/api/events should appear in the list.
    4. Click on this request. Select the Payload (or Request) tab to inspect the data that was sent. You should see the JSON payload containing your identify and Purchase event details.

  4. Final check in Usermaven: Review your Usermaven dashboard. You should see the events in Configure > Custom events section, the complete user journey, including all funnel events and the final purchase revenue, attributed correctly to your test user in the Contacs hub > Users section and reflected in the dashboard.

Last updated on
Installing Usermaven