The documentation on UET events leaves something to be desired. While I was adding support for the UET events in Tag Rocket I went around in circles for a long time trying to work out exactly what events to fire, and what they should contain. This article will hopefully save people time in doing the same.

Note: BigCommerce users using Tag Rocket do not need to add these events, or any UET code to the site. Tag Rocket does it all for you 🙂

The article is aimed at developers as you will need to know how to write JavaScript and customise the examples to work with your website. It also assumes knowledge of campaigns, conversion goals, audiences and how to create and use them. Here we focus on how to create the events to make things work.

It also assumes the base UET tag has already been set up on every page. How to do that is well covered in Microsoft’s documentation and admin section.

The article focuses on advertising features and the UET events they require to work. I’ll reference sources where I can. One major source was the UET code (bat.js) itself, which I reverse engineered to see what it supported.

A typically event script looks a bit like this:

<script>
     window.uetq = window.uetq || [];
     window.uetq.push('event', 'action', {insert event data here});
</script>

Any code highlighted in red needs to be modified by the developer so that it contains the correct information for that event. Do not just copy these examples. All of them require modification to insert the correct data for your events.

The code here in blue is there to let you send events before the base UET tag is set up. You don’t need to include it if you know that line has already been added in earlier code (it is part of the base UET script).

Each event follows the same pattern.

  1. The event information is pushed into the UET queue (uetq) for later processing
  2. The first argument indicates it is an ‘event’
  3. The second argument is the name of the action the event relates to, and can sometimes be an empty string.
  4. The third argument is an object that contains all the data for the event (properties).

For brevity the examples that follow will just include the event code itself.

TL;DR;

I thought I’d sum things up first, to give an overview of what’s possible, and then go into the details.

Features

First, a quick summary of the Microsoft Ads features that can use UET events to enhance their functionality

Conversion Goals

You will have no idea how well your campaigns are working if you are not tracking success, and that’s what conversion goals are. You can use UET events to indicate when a specific conversion goal has happened, and to also indicate how valuable that conversion was (revenue). Conversion counts and their Revenue are available in reports to help you identify what is working (ROI). The data is also used to power automated bidding.

A new Product Conversion Goal type enables more accurate attribution of purchases and is required for the new Shopping Campaign For Brands. It supports more detailed product data in the UET purchase event.

Audiences (Remarketing Lists)

Audiences are lists of users that have performed certain actions. You can use audience targeting to reach specific users at the right time. UET custom events can be used to help you create audience remarketing lists based on how a user interacted with your website.

Dynamic Remarketing

This is a form of remarketing specific to ecommerce websites. UET events are used to indicate how users are interacting with products on your site. This information is used to create dynamic remarketing lists that you can use to target users as they go through the buying process (general visitors, product searchers, product viewers, shopping cart abandoners, and past buyers). It can also be used to show highly targeted product ads to those users.

More Accurate Product Attribution

Microsoft are rolling out a way to help them more accurately attribute product based ads with the product people interact with and buy. The first step seems to be the availability of a special Product Conversion Goal that supports sending more detailed product UET events. And that feature makes reference to a new shopping campaigns for brands that requires it. I believe this is going to expand.

The Big List Of Events

Now you know what UET events are used for, here is a list of all the events and event parameters I discovered during my research and developement.

Event Parameters

Each event can have an action name and a set of parameters to provide more details about the event. All events support the following parameters that can be used to identify Remarketing Audiences and/or Conversion Goals:

  • event_category = Category
  • event_label = Label
  • event_value = Value (number)

All events can also contain the following parameter for use by Conversion Goals to track the value of an event:

  • revenue_value = Revenue in reports
  • currency = 3 character currency code

Dynamic Remarketing has its own parameters which I have also seen used on custom events. Here they are

  • ecomm_pagetype = the type of page being viewed (home, searchresults, category, product, cart, purchase, other)
  • ecomm_prodid = array of product identifiers that match the merchant feeds id or item_group_id
  • ecomm_query = the query made on a searchresults page
  • ecomm_category = the name of the category on a category page
  • ecomm_totalvalue = for cart and purchase pages

Further parameters are supported for other features.

Note: any price sent should contain no more than three decimal places.

Custom Events

Dynamic Remarketing and Destination URL based Conversion Goals use events that require that the action is blank, while all other “custom events” use an action name. This effectively means Dynamic Remarketing and Destination URL based Conversion Goals have their own events system that should not be combined with custom events. Because of this I will not include them in this custom events list. How to set them up is detailed later.

This list comes from events specifically mentioned in the admin system, documentation and from reverse engineering the UET code. It’s an indication of what action names to use and what advanced parameters may be used for those actions. I’ve added columns to indicate where the event was found. Note that you can also invent your own actions for use in audiences and conversion goals.

Several Microsoft examples strangely included the use of dynamic remarketing parameter, which I have also added to the parameters list. It implies that it may be worth adding dynamic remarketing parameter to these events even if they are not meant to be used by dynamic remarketing.

ActionExtra ParametersUETGoalNotes
add_payment_info
add_to_cartitems, ecomm_prodid, ecomm_pagetype, ecomm_totalvalue , revenue_value, currency
add_to_wishlistitems, revenue_value, currency
begin_checkoutitems, coupon, revenue_value, currency
book_appointment
checkout_progressitems, coupon, checkout_step, checkout_option, revenue_value, currency Checkout_step is an integer. e.g. step 1, 2, 3…
contact
exceptiondescription, fatal
generate_leadtransaction_id, revenue_value, currency
get_directions
loginmethod
other This is probably just an example where you should change the event name to whatever you want.
outbound_click
page_viewpage_title, page_location, page_path, rep, tpp, gtm_tag_source This is an automatic event fired with the base UET tag?
purchasetransaction_id, tax, shipping, items, coupon, ecomm_prodid, ecomm_pagetype, ecomm_totalvalue, revenue_value, currency Make sure you set revenue_value and currency for this one. Required for the Product Conversion Goal or event based purchase conversion goal. Product Conversion Goals also require ecomm_prodid and ecomm_pagetype set to ‘purchase’.
refundtransaction_id, tax, shipping, items, revenue_value, currency
remove_from_cartitems, revenue_value, currency
request_quote
screen_viewscreen_name Probably related to apps
searchsearch_term There is also a ‘view_search_results’ event?
select_contentitems, promotions, content_type, content_id This may be when a product or promotion is clicked on.
set_checkout_optioncheckout_step, checkout_option
sharemethod, content_type, content_id
signup
sign_up method UET code do not use the same event as the one suggested by the above Conversion Goal
submit_lead_form
subscribe
view_itemitems This typically relates to a product page
view_item_listitems This typically relates to a category page or list of products shown on a page
view_promotionpromotions e.g. banners
view_search_resultssearch_term There is also a ‘search’ event?

The items properties are specifically mentioned for use in the Product Conversion Goal where the information is used to help attribution. From the table it can be seen that it is supported for other shopping actions that may be documented in the future. The examples page that includes examples with items says:

“This data can be used for conversion goals (e.g., custom events or product goal conversions) and targeting features (e.g., dynamic remarketing and more powerful future Microsoft Advertising features).”

Example page

Each entry in items represents a product where id, price and quantity are expected in the purchase and add_to_cart events. I’d assume id is always required. here are the supported parameters:

Item ParameterNotes
brandThe products category
categoryThe products category
creative_name
creative_slot
idThis should match the id or item_group_id in your shopping feed.
list_nameFor example, it could be a list of product in a category, so this would be the category name
list_positioninteger. I suspect this is an index to where in the list the item is positioned.
location_idThis may be to indicate the location on the page, e.g. ‘footer’
nameName of the product
pricenumber.
quantitynumber.
variant

And each promotion can contain:

Promotion Parameter Notes
creative_name
creative_slot
id
name

Purchase Conversion Goals

For ecommerce sites the most important thing to set up is a purchase based conversion goal. This is so you know if your campaigns are working. Microsoft provides instructions on how to create a conversion goal.

It’s even better if you also set up events to provide the revenue values for those conversions. There are three different types of conversion goals that you can chose from for Purchases, each with different event needs:

Destination URL Based Purchase Conversion Goal

This is probably the most used method as it has been around the longest. But not the best. I’d recommend using the later mentioned Product based conversion goals if you can.

The goal is set up in admin to fire when a user visits a specific page (make sure your goal indicates that revenue values may vary). To send the revenue data for this goal requires this relatively simple script on that page:

window.uetq.push('event', '', {revenue_value: 9.95, currency: 'USD'});

In this case the action has to be a blank string, and you need to enter the correct revenue_value and currency.

Note that the later purchase event for dynamic remarketing can be used in place of this event. If you implement that you do not need to implement this one.

Event Based Purchase Conversion Goal

This next option lets you specify the name of the action that indicates a purchase . By default it is ‘purchase’. And you should also state that revenue values may vary. Then this code is required on your purchase conversion page:

window.uetq.push('event', 'purchase', {revenue_value: 9.95, currency: 'USD'});

The only difference here is that there is a name for the action, which has to match the name used in the conversion goal.

Like in the previous example you need to dynamically insert the bits in red with the correct values for each purchase.

Before adding this, look into the product based goal event (next) which sends the same event with more data…

Product Based Purchase Conversion Goal

This is the new kid on the block, and is capable of sending a lot more data to Microsoft. Here is an example based on the default code they provide. The action can be any name, but I suggest using ‘purchase’. This way the same event could support event and product based goals.

window.uetq.push('event', 'purchase', {
  ecomm_prodid: ['P1', 'P2', 'V3'], 
  ecomm_pagetype: 'purchase', 
  revenue_value: 25.99, 
  currency: 'USD'
});

There is the usual revenue_value and currency. It then adds a few parameters normally reserved for dynamic remarketing (dynamic remarketing ignores this event as it does not have a blank action, see later for its events).

The ecomm_prodid parameter is the important one here. It is used to identify all the products that have been purchased. Each string in the array has to match the id or item_group_id value in your merchant centre feed. Think of the item_group_id as the products identifier, while the id is the identifier for the variant they bought.

Microsoft provides an examples page that includes an order confirmation page example that takes this event a step further. And there are some instructions about it:

window.uetq.push('event', 'purchase', { 
    transaction_id: '123456789',
    ecomm_prodid: ['P1', 'P2', 'V3'], 
    ecomm_pagetype: 'purchase',
    ecomm_totalvalue: 25.99,
    revenue_value: 25.99,
    event_value: 25.99,
    currency: 'USD',
    items: [ 
        { 
          id: 'P1', 
          quantity: 2, 
          price: 5.00 
        }, 
        { 
          id: 'P2', 
          quantity: 1, 
          price: 5.99 
        }, 
        { 
          id: 'V3', 
          quantity: 1, 
          price: 10.00 
        } 
      ] 
    }
);

I could not find any reference to transaction_id outside of the example.

For some reason the example added ecomm_totalvalue. It’s unclear what it is used for, but revenue_value is used for the conversion value.

The extra items data is used in the new shopping campaigns for brands. items does support more properties (see the table in the TL;DR; section), but that is all the examples include at the moment.

I added event_value so that it can be used to create audiences based on how much a customer spent.

Other Event Based Conversion Goals

Microsoft Ads lets you create many other goals and provides some conversion goal categories as suggestions. When you are creating a conversion goal it provides you with a list of these goal categories. When you select one it then gives the the option to make it an event based goal.

These conversion goals by default use the events Action to connect an event with a goal. And during the setup process it will provide you with the basic event code to run when the goal is completed. I used that information to help put together the events table in the TL;DR; section.

Conversion goals can also use the following event parameters to match an event with a goal.

  • event_category = Category
  • event_label = Label
  • event_value = Value (number)

Typically only the action is used to make the match with the goal.

window.uetq.push('event', 'contact', {}); 

However you will see good uses for these extra parameters when I talk about Audiences. So it can be worth setting them in the event if it makes sense.

Goals also let you specify the revenue associated with the goal. These take effect if you set the goals Revenue to “Conversion action value may vary”. The revenue value is used in reports and automated bidding.

  • revenue_value = used for reporting
  • currency = 3 character currency code

e.g. you may want to say a subscription is worth $10.

window.uetq.push('event', 'subscribe', {revenue_value: 10, currency: 'AUD'});

You can also create your own goals that fire from your own events. Pick a category that you want to group the goal under and give it a relevant name and edit the custom event parameters to match the event you want to use.

Event Base Remarketing Audiences

Custom events can also be used to define audiences (remarketing lists). When you add an Audience, select “Remarketing list” then set “Whom to add to your audience” to “Custom events”.

Audiences can use the event action and the same core event parameters to decide if a user is part of an audience.

  • event_category = Category in the audience builder
  • event_label = Label in the audience builder
  • event_value = Value in the audience builder (number)

This is what a typical custom event would look like:

window.uetq.push('event', 'action', {event_category: 'category', event_label: 'label', event_value: value});

For example, you could add these properties to an add_to_cart event so that you could create a very specific audience like “Added a men’s shoe worth over $100 to the cart”. Note there is a more detailed example further down in this article.

window.uetq.push('event', 'add_to_cart', {
     event_category: 'shoes', 
     event_label: 'mens blue boot size 12', 
     event_value: 105.95
});

Or you could provide more info for an outbound_click event so that you could create audiences for people who visited one of your social media pages.

window.uetq.push('event', 'outbound_click', {
     event_category: 'Social', 
     event_label: 'Facebook'
});

Note: this means any existing event that has an action name can be used to build an audience. And you can add the special event parameters to those events to let you refine the audience even more.

Dynamic Remarketing

Dynamic remarketing lists require their own set of events to send product data that power the dynamic part of dynamic remarketing. In particular these events need an empty action name and the following parameters when it comes to ecommerce based dynamic remarketing:

  • ecomm_pagetype = the type of page being viewed (home, searchresults, category, product, cart, purchase, other)
  • ecomm_prodid = array of product identifiers for products shown on the page
  • ecomm_query = the query made on a searchresults page
  • ecomm_category = the name of the category on a category page
  • ecomm_totalvalue = for cart and purchase pages
  • revenue_value = value used for conversions. probably not related to dynamic remarketing
  • currency = 3 character code for the currency used in any prices
  • items = this was seen in one example for cart pages implying items may be supported by dynamic remarketing

The ecomm_prodid values are done in the same way as before. They must match the item_group_id or id values in your merchant centre product feed.

The ecomm_totalvalue, ecomm_category and ecomm_query parameters are using in these examples and I have confirmed them in the UET code. If you specify any prices (no more than 3 decimal places) I’d recommend you also send the currency parameter.

I believe revenue_value is included on the purchase page example so that the same event can be used for destination URL based revenue tracking as well as dynamic remarketing.

To some examples…

Home Page

This ones is nice and simple (example from Microsoft):

window.uetq.push('event', '', {
    ecomm_pagetype: 'home'
});

Search Results Page

Based on an example from Microsoft.

window.uetq.push('event', '', {
    ecomm_query: 'widgets',
    ecomm_prodid: ['P1', 'P2', 'P3'],
    ecomm_pagetype: 'searchresults'
});

In this case you need to enter the query term used and list the product that showed up in the results. Note that typically you only show product not variants on a page like this.

At some point adding the items parameter may be of value.

Category Page

Based on an example from Microsoft.

window.uetq.push('event', '', {
    ecomm_category: 'Red Widgets',
    ecomm_prodid: ['P1', 'P2', 'P3'],
    ecomm_pagetype: 'category'
});

In this case ecomm_category can be used to identify the category.

Note that typically you only show product not variants on a page like this.

At some point adding the items parameter may be of value.

Product Page

Based on an example from Microsoft.

window.uetq.push('event', '', {
    ecomm_prodid: ['P1'],
    ecomm_pagetype: 'product'
});

Only one product id is required in this case.

At some point adding the items parameter may be of value.

Cart Page

The example they provided for this is a bit mixed. It at first looks like a dynamic remarketing event (no action), but then it adds items. No harm in adding the extra parameters and items if you can. It also implies that items could be used on all dynamic remarketing events that list products.

window.uetq.push('event', '', { 
    ecomm_prodid: ['P1', 'P2', 'V3'], 
    ecomm_pagetype: 'cart',
    ecomm_totalvalue: 25.99,
    revenue_value: 25.99,
    currency: 'USD',
    items: [ 
        { 
          id: 'P1', 
          quantity: 2, 
          price: 5.00 
        }, 
        { 
          id: 'P2', 
          quantity: 1, 
          price: 5.99 
        }, 
        { 
          id: 'V3', 
          quantity: 1, 
          price: 10.00 
        } 
    ] 
});

Note, the items in a cart can be products or variants. Their id may match the merchant feeds id or item_group_id.

Purchase Page

In this case the example they provided for purchase had an action name, which means it would not work for dynamic remarketing. So an alternate event is required.

window.uetq.push('event', '', { 
    ecomm_prodid: ['P1', 'P2', 'V3'], 
    ecomm_pagetype: 'purchase',
    ecomm_totalvalue: 25.99,
    revenue_value: 25.99,
    currency: 'USD',
    items: [ 
        { 
          id: 'P1', 
          quantity: 2, 
          price: 5.00 
        }, 
        { 
          id: 'P2', 
          quantity: 1, 
          price: 5.99 
        }, 
        { 
          id: 'V3', 
          quantity: 1, 
          price: 10.00 
        } 
    ] 
});

The properties in blue are not required for dynamic remarketing. Adding revenue_value and currency means this event should also work for sending revenue for the destination URL based conversion goals. I’ve added the ecomm_totalvalue and items parameters so it matches up with how the example for cart pages looks.

Other Page

Any other page type not covered in the above:

window.uetq.push('event', '', {
    ecomm_pagetype: 'other'
});

More Accurate Product Tracking And Purchase Attribution

I’ve already shown the new Product conversion goal example that uses the items parameter which is said to improve how ads and products are attributed. The events table from the start also lists some undocumented events that also support items. I suspect this is part of a new system that gathers a lot more product information and user flow data.

Microsoft provide an example for an add to cart event which also uses the items property, along with some properties from the dynamic remarketing world. Here I’ve expanded on their example so that it could also be used for creating advanced audiences or conversion goals.

window.uetq.push('event', 'add_to_cart', { 
    ecomm_prodid: ['V3'], 
    ecomm_pagetype: 'product',
    ecomm_totalvalue: 10.00,
    revenue_value: 10.00,
    event_category: 'shoes', 
    event_label: 'mens blue boot size 12', 
    event_value: 10.00,
    currency: 'USD',
    items: [ 
        { 
          id: 'V3', 
          quantity: 1, 
          price: 10.00 
        } 
      ] 
    }
);

The UET code indicates that the following events may be part of this new more detailed tracking system. The events seem very familiar (GA4):

  • view_item_list
  • view_item
  • view_promotion
  • view_search_results
  • select_content
  • add_to_wishlist
  • add_to_cart
  • remove_from_cart
  • begin_checkout
  • checkout_progress
  • set_checkout_option
  • add_payment_info
  • purchase
  • refund
  • login
  • sign_up

I’d recomend creating custom events based on the suggested action names and try and fill in as much data as possible so that they can be used to power Conversion Goals, Audiences and these future features.