Direct Data Beacon

• Overview
• The sendGif function
  • Function Signature
  • Parameters
  • Example
    • Simple Example
    • Complex Example
    • Checkout Example

Overview

Direct data beacons are used to collect and send performance timing data and other metadata directly to the remote Blue Triangle analytics servers. This method of sending data bypasses the traditional Hard Navigation or Virtual Turn page logic which are the primary data collection methods of the btt.js script. However the btt.js does need to be loaded onto the page before sending a direct data beacon. The use cases for sending a data beacon directly could include tracking a specific page event that requires its own timing logic, or to guarantee data collection for a checkout event in order to capture revenue data.

The sendGif function

The sendGif function is used to send analytics data directly to the remote Blue Triangle analytics servers. This function is part of the bttUT object in the btt.js script, and is designed to track page-level metrics for analytics purposes. The sendGif function automatically handles encoding and sending the beacon data to the endpoint. If certain required arguments are not provided, the function will attempt to retrieve them from local storage, for example the Session ID will be populated into local storage via the btt.js initial load. Optional arguments allow for customization and tracking of additional metrics. Below is a detailed guide on how to use the sendGif function, including descriptions of its parameters and usage examples.

Function Signature

bttUT.sendGif(pageName, requiredArgs, optionalArgs);

Parameters

pageName (String) - The name of the page being tracked. This is a required parameter and should uniquely identify the page, or name of the data beacon. This name will appear under the pageName filters in the Portal.

requiredArgs (Object) - An object containing required arguments for the beacon. If none of these values need to be overwritten, then an empty object can be passed in the function call.

• sessionID (String) - The session ID for the user. If not provided, this function will attempt to retrieve it from local storage. You may only need to set this field if sending the user to a cross-domain location where the sessionID may not be set by the btt.js, in which case you will need to transmit the sessionID and pass it in the requiredArgs objects.
• campaign (String) - The campaign name associated with the page. If not provided, it will attempt to retrieve it from local storage.
• txnName (String) - The traffic segment associated with the page. This is typically used to group related events or pages. If not provided, it will attempt to retrieve it from local storage.

optionalArgs (Object) - An object containing optional arguments for the beacon. These arguments allow for customization and additional tracking.

• pgTm (String) - The primary field for passing a performance metric timing. Must be rounded and converted to a String. For example "1050" or "501"

• pageGroup (String) - The group or category of the page. This is useful for organizing pages into logical groups. 

• orderNumber (String) -The order number associated with the transaction. When using sendGif for e-commerce tracking of the checkout event.

• cartValue (String) - The value of the cart for e-commerce transactions. When using sendGif for e-commerce tracking of the checkout event. Must be rounded and converted to a String. For example "10" or "120"

Examples

Simple Example

The following example sends a direct data beacon with the minimum necessary configurations for data collection, which passes a pageName and a performance timing.

var requiredData = {};
var optionalData = {
    pgTm: "1050",
};
var pageName = 'my-direct-beacon-name';
bttUT.sendGif(pageName, requiredData, optionalData);

Complex Example

The following example sends a direct data beacon with more configuration options specified such as sessionID, campaign, and txnName. These fields are populated by an object myData, which was ideally populated with the sessionID and campaign from another source before calling sendGif.

var requiredData = {
    sessionID: myData.sessionID,
    campaign: myData.campaign,
    txnName: "Direct Data Segment"
};
var optionalData = {
    pgTm: "1050",
    pageGroup: "Direct Data Group",
};
var pageName = 'my-direct-beacon-name';
bttUT.sendGif(pageName, requiredData, optionalData);

Checkout Example

The following example sends a direct data beacon for a checkout event, in order to collect revenue data. This would be used in cases where the normal Tag revenue capture capabilities might be limited.

var requiredData = {
    sessionID: myData.sessionID,
    campaign: myData.campaign,
    txnName: "Checkout"
};
var optionalData = {
    pgTm: "1050",
    pageGroup: "Direct Data Group",
    orderNumber: "ORDER123",
    cartValue: myData.cartValue
};
var pageName = 'my-direct-beacon-name';
bttUT.sendGif(pageName, requiredData, optionalData);