How to track custom events with UET

How to track custom events with UET

Learn how to create custom events that allow you to track more than one type of conversion for a single webpage.

Microsoft Advertising allows you to track custom events on your website, such as when people subscribe to a newsletter or download a white paper, as conversions. To learn more, see Why track custom events.

Requirements

Before you start setting up custom events, make sure you have:

How to set up custom events

Step 1: Add the UET tag tracking code to your website expando image
  1. In the left pane of Microsoft Advertising, click Conversion Tracking > UET tags.
  2. Find the tag you want to use and, in the Action column, click View tag.
  3. Click Copy.
  4. In your website's code, paste the tag in one of the following locations:
    <head>Your page title 
     

    // Option 1: Insert your UET tag here, between the "head" tags.


    </head>

    <body> 

    // Option 2: Insert your UET tag here, right after beginning of the "body" tag.


       ...
    <button>Download now</button>
       ...
    </body>
Step 2: Create a conversion goal or remarketing list expando image
  • Creating a conversion goal for a custom event:
    1. In the left pane of Microsoft Advertising, click Conversion Tracking > Conversion goals.
    2. Click Create conversion goal.
    3. Give your conversion goal a name, select Event for Type, and then click Next.
    4. Choose the parameters to report when logging custom events by assigning each one you want to use a text string or numeric value. The possible parameters are:
      • Category: The category of the event you want to track. Let's say you want to track downloads of a document on a page of your site. For this example, the category could be "downloads".
      • Action: The type of user interaction you want to track. For our example, "downloadbuttonclick".
      • Label: The name of the element that caused the action. For our example, "document05".
      • Value: A numerical value associated with that event. For our example, the number of pages in the document: "4".
        The event value can be any value from 0 to 9999999 to 3 decimal places.

      Note

      You'll customize your UET tag tracking code to match the values defined here (this is discussed in Step 3). This will allow Microsoft Advertising to match these values with the custom events being logged via UET to count them as conversions.

    5. Select the Revenue value, Count, and Conversion window for this custom event goal.
    6. For UET tag, select the UET tag that you added to your website in Step 1.
    7. Click Save.

    Note

    Every action that we detect that matches your conversion goal will be counted as one conversion.

  • Creating a remarketing list for a custom event:
    1. In the left pane of Microsoft Advertising, click Shared Library > Audiences.
    2. Click Create remarketing list.
    3. For Whom to add to your audience, select Custom events.
    4. Choose the parameters to report when logging custom events by assigning each one you want to use a text string or numeric value. The possible parameters are:
      • Category: The category of the event you want to track. Let's say you want to track downloads of a document on a page of your site. For this example, the category could be "downloads".
      • Action: The type of user interaction you want to track. For our example, "downloadbuttonclick".
      • Label: The name of the element that caused the action. For our example, "document05".
      • Value: A numerical value associated with that event. For our example, the number of pages in the document: "4".
        The event value can be any value from 0 to 9999999 to 3 decimal places.

      Important

      You'll customize your UET tag tracking code to match the values defined here (this is discussed in Step 3). This will allow Microsoft Advertising to match these values with the custom events being logged via UET to count them as conversions.

    5. Set the Membership duration to tell Microsoft Advertising how far back in time to look for actions that match your remarketing list definition in order to add people to your list.
    6. For Tag name, select the UET tag that you added to your website in Step 1.
    7. Click Save.
    8. Associate audiences with ad groups or campaignsAssociate this remarketing list with an ad group
Step 3: Modify the UET tag tracking code in your website expando image
Following on our example in Step 2, let's say that the custom event you want to track on your webpage is people clicking the "Download now" button (this would be an Action event, as discussed above).
  1. Add the following custom event JavaScript below the UET tag that you added to your webpage's code in Step 1:
    <head>Your page title 
    </head>

    <body>

     // Let's say this is where you pasted the UET tag in Step 1.


    <script>Your UET tag is here.</script>

     // Here is where to paste the following JavaScript:

    <script>
       window.uetq = window.uetq || [];
       window.uetq.push ('event', 'Replace_with_Event_Action', {'event_category': 'Replace_with_Event_Category', 'event_label': 'Replace_with_Event_Label', 'event_value': 'Replace_with_Event_Value'});
    </script>



       ...
    <button>Download now</button>

       ...
    </body>
  2. Give this code snippet a function name. The function name can be anything, as long as it hasn't already been used in your website. In this example, we're naming it "GetCustomEvent()":
    <head>Your page title 
    </head>

    <body>
    <script>Your UET tag is here.</script>

    <script>

       function GetCustomEvent() {

       window.uetq = window.uetq || [];
       window.uetq.push ('event', 'Replace_with_Event_Action', {'event_category': 'Replace_with_Event_Category', 'event_label': 'Replace_with_Event_Label', 'event_value': 'Replace_with_Event_Value'});

       }

    </script>

       ...
    <button>Download now</button>

       ...
    </body>
  3. You now need to customize your webpage's code to call this function when the appropriate action occurs. In our example, the custom event is a click of the "Download now" button, so we'd need to add a call in the button's code:
    <head>Your page title 
    </head>

    <body>
    <script>Your UET tag is here.</script>

    </script>

    <script>
       function GetCustomEvent() {
       window.uetq = window.uetq || [];
       window.uetq.push ('event', 'Replace_with_Event_Action', {'event_category': 'Replace_with_Event_Category', 'event_label': 'Replace_with_Event_Label', 'event_value': 'Replace_with_Event_Value'});
       }
    </script>

       ...
    <button OnClick="GetCustomEvent()">Download now</button>

       ...
    </body>
  4. Note the four different parameters in the custom event JavaScript: 'event', 'event_category', 'event_label', and 'event_value'. These correspond to the parameters you had the option to define for your custom event conversion goal in Step 2. In the JavaScript you added, the parameters have placeholder values assigned to them:
    <head>Your page title 
    </head>

    <body>
    <script>Your UET tag is here.</script>

    </script>

    <script>
       function GetCustomEvent() {
       window.uetq = window.uetq || [];
       window.uetq.push ('event', 'Replace_with_Event_Action', {'event_category': 'Replace_with_Event_Category', 'event_label': 'Replace_with_Event_Label', 'event_value': 'Replace_with_Event_Value'});
       }
    </script>

       ...
    <button OnClick="GetCustomEvent()>Download now</button>

       ...
    </body>
  5. The JavaScript you added needs to return a value to Microsoft Advertising when the custom event occurs, and that value needs to match what you entered in Step 2. In our example, we are tracking button clicks, which are Action events as shown in Step 2 (and are represented by 'event' in the JavaScript). So we would need to modify the placeholder value of the 'event' parameter (and we can remove the other three parameters):
    <head>Your page title 
    </head>

    <body>
    <script>Your UET tag is here.</script>

    <script>
       function GetCustomEvent() {
       window.uetq = window.uetq || [];
       window.uetq.push ('event', 'downloadbuttonclick', {});
       }
    </script>

       ...
    <button OnClick="GetCustomEvent()>Download now</button>

       ...
    </body>
  6. Save and deploy your edited website code.
Tips for working with custom events expando image
  • uetq is a JavaScript object instantiated by the UET tracking code when the page is loaded.
  • The code inside the <script></script> tag should be instantiated when the user action (for example, a button click) is complete. It could be wired up directly to an onclick event or wrapped inside a JavaScript function that is wired to the onclick event.
  • The command 'event' is always required, even if you're not reporting any Event action. If that's the case, you can set Event action either as:
    • Empty. For example:
      <script>
         window.uetq = window.uetq || []; 
         window.uetq.push('event', '', {'event_category': 'Replace_with_Event_Category', 'event_label': 'Replace_with_Event_Label', 'event_value': 'Replace_with_Event_Value'});  
      </script>
    • One of the following actions that might help you identify the event action in the future:
      add_payment_info, add_to_cart, add_to_wishlist, begin_checkout, checkout_progress, exception, generate_lead, login, page_view, purchase, refund, remove_from_cart, screen_view, search, select_content, set_checkout_option, share, sign_up, timing_complete, view_item, view_item_list, view_promotion, view_search_results
      For example:
      <script>
         window.uetq = window.uetq || []; 
         window.uetq.push('event', 'add_payment_info', {'event_category': 'Replace_with_Event_Category', 'event_label': 'Replace_with_Event_Label', 'event_value': 'Replace_with_Event_Value'});  
      </script>
  • If you're only tracking Event action, you can remove the other parameters from the code. For example:
    <script>
       window.uetq = window.uetq || []; 
       window.uetq.push('event', 'Event action', {});  
    </script>
  • You can use any string value for Replace_with_Event_Category, Event action, and Replace_with_Event_Label.
  • You can send the event value without quotes given that it's a numerical value. For example, <button onclick="window.uetq = window.uetq || []; window.uetq.push({ 'event_category':'Video', 'event':'Play', 'event_label':'Product Demo', 'event_value':5 });">Play</button>. Event value 5 is passed without quotes.
  • You can also pass variable revenue with the custom events. To learn more, see How to report variable revenue with UET.
Notes
  • You can validate that your custom events are working using the UET Tag Helper.
  • To see an example of a custom event UET tag tracking code installed in the body of a webpage, visit this webpage (English only), right-click in the webpage, and then click View source or View page source depending on your browser. On this page, you'll also see some buttons. Clicking each button will trigger a custom event. If you use a third-party monitoring tool like Fiddler, you can see the HTTP request generated to bat.bing.com to report each custom event.
  • As your webpage loads, it triggers the UET tag, resulting in a number of HTTP requests. The most important request is to "bat.bing" (the one that looks like "http://bat.bing.com/action/0?ti=..."). This request tells Microsoft Advertising about the user visits to your webpage. You can use third-party tools such as Fiddler to monitor all the requests that your browser is making when your webpage loads.
  • For custom events, an additional HTTP request is triggered to report the same to Microsoft Advertising. The request is similar to the bat.bing but it has different parameters to report custom event (as opposed to just page visit).

See more videos...