Skip to main content

Track Shopper Events

Note:

If you have Live, Video Consultation or Shoppable Video integrated on the same website, you only need to implement these enhanced tracking events once.

Prerequisites
  • You must have already integrated a Bambuser product (Live Shopping, Shoppable Video, or Video Consultation) on your website.
  • Ensure your website's cookie consent mechanism allows for the necessary Bambuser cookies (_bamls_usid, _bamls_lcte) to be set for users who have consented, as tracking relies on these cookies.
Migrate from Legacy Conversion Tracking

Did you implement Bambuser's Conversion Tracker before June 2025, see Migrating from Legacy Conversion Tracking for details on how to migrate to the new Shopper Events Tracking.

Introduction​

By integrating the Bambuser tracking library, you can send Ecommerce shoopper events to Bambuser for enhanced insights and analytics around the shoppers that have interacted with any of the Bambuser products.

You can choose to implement the Bambuser tracking library in two ways:

  1. Directly on your website: It allows you to send events directly to Bambuser without any additional setup.
  2. Using Google Tag Manager: It allows you to send events to Bambuser using the Google Tag Manager template. This is useful if you are already using a tag manager to manage your website's tracking.

How it works​

Bambuser tracking requires cookies to be set to function correctly. You are responsible for configuring cookie settings during the implementation of each Bambuser product. If you use our tracking library but the required Cookies have not been set, the tracking library will not send any data to Bambuser.

Cookies​

Bambuser applications automatically sets the cookies below. These cookies are used by the application tracking itself and the Bambuser Shopper Events Tracker to find out whether a purchase is relevant to track to Bambuser. If the below cookies exist and are valid, the purchase is considered as a conversion and is tracked. If cookies are restricted, removed, or expired, Bambuser Shopper Events Tracker does not track the purchase.

NameRequiredExpiration dateProductDescription
_bamls_lcteYes30 days (Configurable for Live and Shoppable Video)
  • Live
  • Video Consultation
  • Shoppable Video
Structured data containing expiry timestamps for relevant server locations after which purchases will no longer be applicable for conversion tracking.
_bamls_usidYes1 year
  • Live
  • Video Consultation
  • Shoppable Video
Unique identifier for a user. Used to attribute Bambuser statistics to a single site user.
_bamls_seidYes30 min
  • Live
  • Shoppable Video
Unique identifier for a session in which a Bambuser show or video was watched. Used in tracking to attribute statistics to a single session.
_bamls_cuidWill be replaced by _bamls_lcte1 year
  • Live
  • Video Consultation
  • Shoppable Video
Unique identifier for the merchant. Used as a common denominator for all tracking performed by Bambuser to easily enable reporting and workspaces per merchant.
_bamls_caidOnly for legacy attribution, replaced by _bamls_lcte30 days
  • Video Consultation
Unique identifier for the last Bambuser call that the user had on the merchant site. Used to attribute Bambuser statistics to a specific customer interaction.
_bamls_shidOnly for legacy attribution, replaced by _bamls_lcte30 days (Configurable)
  • Live
Unique identifier for a Bambuser show. Used to attribute statistics to a single show. This also - similar to source/medium in Google Analytics - enables attribution of purchases (that do not occur within the embedded stream) towards the show.
_bamls_litsOnly for legacy attribution, replaced by _bamls_lcte30 days (Configurable)
  • Live
The timestamp for the last known interaction in a Bambuser show. This is used in conjunction with _bamls_shid to measure at what point in time after a user viewed a show, the actual purchase was made.

Example User flow​

  1. A shopper visits your website and interacts with a Bambuser product (e.g., watches a Live stream, views a Shoppable Video, or books a meeting for Video Consultation).
  2. The Bambuser embed script sets the _bamls_usid and _bamls_lcte cookies in the user's browser
  3. The shopper adds a product to their cart or wishlist, or makes a purchase. (This can happen days after the initial interaction with the Bambuser product)
  4. The Bambuser tracking library is called to send the event data to Bambuser
  5. Bambuser processes the data and provides insights into the shopper's behavior and interactions with Bambuser products on your website and their subsequent journey. This helps you understand the impact of Bambuser products on your website's performance and conversion rates.

Direct Implementation​

GTM If you are using Google Tag Manager, see Bambuser LiveShopping GTM template.

The Bambuser tracking library is a JavaScript library that allows you to track shopper events on your website. It is designed to be easy to implement and can be used with any website.

The script exposes a tracking function window._bambuser.track() on the window object, which you can call to send events to Bambuser.

1. Include the Bambuser Tracking Library​

To enable direct event tracking, include the Bambuser tracking library by adding the appropriate script tag to your website's HTML. It's generally recommended to place scripts before the closing </body> tag, but they can also be placed in the <head>.

note

If your website is connected to both Bambuser data regions, it is sufficient to include only one of the scripts. The Bambuser tracking library will automatically detect from the users _bamls_lcte cookie which data region to send the events to.

<script src="https://cdn.liveshopping.bambuser.com/metrics/bambuser.min.js"></script>

Dynamically include the script tag​

In your website's HTML, you can dynamically include the Bambuser tracking library script tag using JavaScript. This can be useful if you want to load the script conditionally or at a specific point in your page's lifecycle.

note

In frameworks like React, Vue, or Angular, you can use the framework's lifecycle methods to include the script dynamically. However, be careful to ensure that the script is loaded before you call the window._bambuser.track() function and ensure that you call the track function only once per event.

warning

If you dynamically include the library, there is a risk the user close the tab or navigates away before the script has loaded and the browser could then discard the event.

The below example shows one way to dynamically include the library and queue up events that can be sent once the library is loaded.

<script>
  let queuedTracking = [];
  function trackQueuedEvents() {
    queuedTracking.forEach((trackingData) => {
      window._bambuser.track(trackingData.eventType, trackingData.eventData);
    });
    queuedTracking = []; // Clear the queue after processing
  }
  function trackBambuserEvent(eventType, eventData) {
    // Check if the Bambuser tracking library is loaded
    if (window._bambuser && window._bambuser.track) {
      window._bambuser.track(eventType, eventData);
    } else {
      queuedTracking.push({ eventType, eventData });
      const bamSrcElm = document.createElement("script");
      bamSrcElm.src = "https://cdn.liveshopping.bambuser.com/metrics/bambuser.min.js";
      bamSrcElm.onload = trackQueuedEvents;
      document.head.appendChild(bamSrcElm);
    }
  }
</script>

2. Send Event Data​

To send event data to Bambuser, you need to call the window._bambuser.track() function with the event data as an argument. The event data should be in the form of a JavaScript object.

note

The below examples only what data to provide the window._bambuser.track(eventType, eventData) function. Ensure you have properly loaded the tracking library according to previous section.

The purchase event will provide insights into conversion rates and product performance through the different Bambuser tools.

NameValueTypeRequiredDescription
eventTypepurchaseStringYesIdentifies the event type. Must be 'purchase'.
transactionSee exampleTransactionObjectYesAn object containing details of the transaction.
productsSee exampleArray<ProductObject>YesAn array of product objects included in the purchase.
window._bambuser.track(
  'purchase',
  {
    transaction: {
      id: 'abcd',
      currency: 'USD',
      subtotal: 70.99, // Monetay value of order, price * quantity of all products. Tax, shipping cost and order level discount excluded
      total: 81.25, // subtotal - discount + tax + shippingCost
      discount: 2.00, // Order level discount applied to the subtotal. Product level discount should already be included in the subtotal price
      tax: 8.27,
      shippingCost: 3.99,
      shippingMethod: 'Home delivery',
      coupon: 'SUMMER_SALE', // Coupon applied to transaction rather than individual product
    },
    products: [ // This is an array of products purchased
      {
        id: '314-7216-102',
        name: 'Tennis Shoe Classic - Size 10',
        image: 'https://example.com/images/314-7216-102.jpg',
        price: 70.99, // Original price 75.99
        currency: 'USD',
        discount: 5.00, // The discount applied to this product, if applicable
        coupon: 'SUMMER_SALE', // The coupon applied to this product, if applicable
        quantity: 1,
        brand: 'Plausible Co.',
        category: 'Footwear > Sports > Tennis',
        location: 'https://example.com/products/314-7216',
      },
    ],
  }
);

Product Object​

The Product Object is used to provide detailed information about a product in the context of Bambuser tracking events. It includes essential attributes that help identify and describe the product being tracked.

NameValueTypeRequiredDescription
id314-7216-102StringYesThe unique identifier of the product.
quantity1NumberNoThe quantity of the product being refunded.
nameTennis Shoe Classic - Size 10StringYesThe name of the product.
imagehttps://example.com/images/314-7216-102.jpgStringNoThe URL of the product image.
price70.99NumberYesThe monetary value of the product, discount already applied. Original price 75.99 in this example.
discount5.00NumberNoThe discount of product in original purchase, if applicable.
couponSUMMER_SALEStringNoThe coupon used in the original purchase, if applicable.
currencyUSDStringYesThe currency of the product price.
brandPlausible Co.StringNoThe brand of the product.
categoryFootwear > Sports > TennisStringNoThe category of the product.
locationhttps://example.com/products/314-7216StringNoThe URL of the product page.

Transaction Object​

The Transaction Object is used to provide detailed information about a transaction in the context of Bambuser tracking events. It includes essential attributes that help identify and describe the transaction being tracked. This object is particularly important for the purchase and refund events, as it contains information about the transaction ID, total amount, and other relevant details.

NameValueTypeRequiredDescription
idabcdStringYesThe unique identifier of the transaction. Preferably, this should reference the transaction ID of the original order, otherwise it should be unique for this refund.
subtotal70.99NumberNoThe price * quantity of all products in the products array.
currencyUSDStringYesThe currency of the transaction.
couponSUMMER_SALEStringNoThe coupon used for the original purchase, if applicable.
discount2.00NumberNoThe total discount applied to the original order, if applicable.
total87.18NumberYesTotal amount refunded, which is the subtotal - discount + shippingCost (if refunded) + tax.
tax14.2NumberYesTax related to the refunded products, if applicable.
shippingCost3.99NumberYesThe shipping cost for the original purchase.
shippingMethodHome deliveryStringNoThe shipping method used for the original purchase.

3. Test the Implementation​

See Verification for how to test the implementation.

Tag Manager Implementation​

1. Installing the Bambuser Live Shopping tag​

Our tag is available on Google Tag Manager Community Template Gallery. To find it, you simply:

  1. Go to "Templates" in the left hand side menu
  2. Under "Tag Templates", press the Search Gallery button
  3. You should now see the "Import Tag Template" view. Either search for (search icon in the top right) "Bambuser Live Shopping" or simply scroll down until you find it and click on it.

You should now see the view below. Click "Add to workspace" and confirm the required permissions by pressing "Add" in the popup that appears. That's it!

img

note

We may update the tag. When we do, you will be notified in Google Tag Manager that an update is available.

2. Set up a tag​

You can either start from Bambuser's recipe or create the tag manually. Using the recipe and configuring it to your needs is the recommended way to go.

  1. Import recipe

    If you'd like to start with a pre-configured example, you can download and import the GTM recipe. This recipe will create the required variables, triggers, and tags for you.

    This recipe builds on Google Analytics Ecommerce standard. If you are already using this standard, you will need minimal or no extra configuration from the imported recipe.

    Even if you do not use Google Analytics Ecommerce standard, it may be easier to start with the recipe and edit the variables rather than doing everything manually.

    Download the recipe

    To import the recipe, go to Admin > Import Container in GTM img

    Select what tags, variables and triggers to import img

  2. Edit to your need
    If you use some other standard than Google Analytics Ecommerce standard, you can edit the variables to your needs. Important things to edit:

    • cjs - Bambuser Products Object Verify the field mappings from where it picks the product information in the datalayer.
    • cjs - Bambuser Transaction Object Verify the field mappings from where it picks the transaction information in the datalayer.
    • Verify the triggers for each of the Event tags are triggers that your site is generating. Or disable the Tags for the events that you do not want to track.

3. Test the implementation​

  1. Preview the tag
    Click on the Preview button in the top right corner of the GTM interface. This will open a new tab with your website in preview mode.
  2. Check the tag firing and variable values In GTM's preview mode, use the debug panel (typically at the bottom of your website) to verify that your Bambuser tag fires on the correct triggers. Inspect the Variables tab in the GTM debug panel when the tag fires to ensure your configured variables contain the expected data.
  3. Check the network requests Open your browser's developer tools (usually F12 or right-click > Inspect) and navigate to the Network tab. Filter requests by a term like events to isolate tracking requests sent to Bambuser.
  4. Check the data sent Inspect the payload of these network requests. Verify that the event data (e.g., eventType, products, transaction) is structured correctly and contains the accurate values as per your GTM variables.

4. Publish the GTM Container​

Once you have tested the tag and confirmed that it is working correctly, you can publish the changes in Google Tag Manager. This will make the tag live on your website and start sending data to Bambuser.

Tracking on a subdomain​

You will need an extra configuration if your checkout page is served under a subdomain of your main domain.

For example:

  • The player is embedded on https://example.com or https://www.example.com
  • But the checkout page is served under https://checkout.example.com

By default, the cookies created by the player will not be accessible from the pages served under subdomains. You can make the cookies accessible on both the main domain and its subdomains (*.example.com) by configuring domain attribute for cookies in the player configuration. Set the domain name without the protocol (https:// part) and prefixing it by a dot (.example.com).

Example for Live player:

window.onBambuserLiveShoppingReady = function(player) {
  player.configure({
    cookie: {
      // Keep the dot prefix to allow cookies to be read from example.com and *.example.com
      domain: '.example.com',
    },
  });
};

Verification​

It is a good practice to verify the implementation by placing a test order.