Event and visitor functions V3

Input data

The input parameters vary depending on function type, as follows:

• Event functions have an event parameter. The visit and visitor parameters are null.
• Visitor functions have visitorand visit parameters. The event parameter is null.

Event and visitor functions have additional parameters, helper, which provides helper.getAuth() and helper.getGlobalVariable() for getting authorization and retrieving global variables.

activate() function

When you create a V3 event or visitor function, default code is shown in the Code tab of the functions code editor. This code contains a global activate function. The input parameters for your function are passed to the activate() function. The following example shows activate() for an event function:

activate(async ({ event, helper }) => {

  ...

});

Change the code between the first and last lines of the default code to suit your needs.

Event object

The event object is available when a function is triggered by the event feed and contains the event data.

Data object

The data object contains the data for the incoming event.

Event object example

The following shows an example of event object data:

{
  "account": "your-account",
  "profile": "main",
  "event_id": "run-test-event-id",
  "visitor_id": "run-test-visitor-id",
  "data": {
    "dom": {
      "viewport_height": 766,
      "referrer": "",
      "viewport_width": 1440,
      "domain": "www.example.com",
      "title": "Home Page",
      "query_string": "q=help",
      "hash": "",
      "url": "https://www.example.com/?q=help",
      "pathname": "/"
    },
    "udo": {
      "tealium_event": "page_view",
      "ut.account": "your-account",
      "ut.visitor_id": "0176cb4f3482110a5ba4702e147b0006d005a065104f2",
      "page_name": "Home Page",
      "ut.event": "view",
      "search_keyword": "help",
      "ut.domain": "example.com",
      "tealium_profile": "main",
      "ut.version": "ut4.46.202006020705",
      "tealium_session_id": "1609910608323",
      "tealium_account": "your-account",
      "ut.profile": "main",
    },
    "firstparty_tealium_cookies": {
      "utag_main__sn": "12",
      "utag_main_dc_visit": "12",
      "utag_main_ses_id": "1609910610822",
      "utag_main_dc_region": "us-east-1",
      "utag_main__st": "1609913306118",
      "utag_main_v_id": "0176cb4f3482110a5ba4702e147b0006d005a065104f2",
      "utag_main__se": "66",
      "utag_main__ss": "0",
      "utag_main_dc_event": "60",
      "utag_main__pn": "5"
    }
  },
  "env": "prod",
  "post_time": 1537305808000
}

Visitor object

The visitor object is available when a function is triggered by the audience feed and contains the visitor data.

Visitor object example

The following is an example of visitor object data:

{
  "metrics": {
    "Metric 1": 1,
    "Metric 2": 2
  },
  "dates": {
    "Date 1": 1603373790000,
    "Date 2": 1603373522000,
  },
  "properties": {
    "profile": "username",
    "visitor_id": "017560818b67001bc185a07f1cd703078003405000b7e",
    "account": "user-account",
  },
  "metrics_sets": {
    "Product Categories Purchased": {
      "Shoes": 1,
      "Pants": 3,
      "Shirts": 7,
      "Shorts": 2
    }
  },
  "sequences": {
    "Hotel Search Timeline": [
      {
        "timestamp": 1681858801598,
        "snapshot": {
          "Searched Hotel City": "Paradise Island"
        }
      },
      {
        "timestamp": 1681860398985,
        "snapshot": {
          "Searched Hotel City": "Skokie"
        }
      },
      {
        "timestamp": 1681860423335,
        "snapshot": {
            "Searched Hotel City": "Las Vegas"
        }
      }
    ]
  },
  "funnels": {
    "Purchase Funnel": {
      "completed": true,
      "steps": {
        "1": {
          "timestamp": 1636661624226,
          "snapshot": {
            "product_name": "Skinny Jeans"
          }
        },
        "2": {
          "timestamp": 1636661624227,
        },
        "3": {
          "timestamp": 1636661624228,
        },
        "4": {
          "timestamp": 1636661624229,
          "snapshot": {
            "order_id": "0123456789",
            "order_total": "34.98"
          }
        }
      }
    }
  },
  "audiences": [
    "Audience 1",
    "Audience 2"
  ],
  "badges": [
    "Badge 1",
    "Badge 2"
  ],
  "creation_ts": 1603373522000,
  "current_visit": {
    "metrics": {
      "Metric 1": 1.3,
      "Metric 2": 6,
    },
    "dates": {
      "Date 1": 1603373868000,
      "Date 2": 1603373790000,
    },
    "properties": {
      "Property 1": "Chrome",
      "Property 2": "https://URL-for-website ",
    },
    "flags": {
      "Flag 1": true,
      "Flag 2": false
    },
    "property_sets": {
      "Property Set 1": [
        "Mac desktop"
      ],
      "Property Set 2": [
        "Chrome"
      ]
    },
    "creation_ts": 1603373790000,
    "total_event_count": 2,
    "events_compressed": false
  },
  "audiences_joined_at": {
    "Audience 1": 1603363523014,
    "Audience 2": 1603363523014
  }
}

Visit object

The visit object is available when a function is triggered by the audience feed and contains the data for the current visit.

Visit object example

The following is an example of visit object data:

{
    "metrics": {
      "Metric 1": 1.3,
      "Metric 2": 6,
    },
    "dates": {
      "Date 1": 1603373868000,
      "Date 2": 1603373790000,
    },
    "properties": {
      "Property 1": "Chrome",
      "Property 2": "https://URL-for-website ",
    },
    "flags": {
      "Flag 1": true,
      "Flag 2": false
    },
    "metrics_sets": {
      "Product Categories Purchased": {
        "Shoes": 1,
        "Pants": 3,
        "Shirts": 7,
        "Shorts": 2
      }
    },
    "property_sets": {
      "Property Set 1": [
        "Mac desktop"
      ],
      "Property Set 2": [
        "Chrome"
      ]
    },
    "sequences": {
      "Hotel Search Timeline": [
        {
          "timestamp": 1681858801598,
          "snapshot": {
            "Searched Hotel City": "Paradise Island"
          }
        },
        {
          "timestamp": 1681860398985,
          "snapshot": {
            "Searched Hotel City": "Skokie"
          }
        },
        {
          "timestamp": 1681860423335,
          "snapshot": {
              "Searched Hotel City": "Las Vegas"
          }
        }
      ]
    },
    "funnels": {
      "Purchase Funnel": {
        "completed": true,
        "steps": {
          "1": {
            "timestamp": 1636661624226,
            "snapshot": {
              "product_name": "Skinny Jeans"
            }
          },
          "2": {
            "timestamp": 1636661624227,
          },
          "3": {
            "timestamp": 1636661624228,
          },
          "4": {
            "timestamp": 1636661624229,
            "snapshot": {
              "order_id": "0123456789",
              "order_total": "34.98"
            }
          }
        }
      },
    },
    "creation_ts": 1603373790000,
    "total_event_count": 2,
    "events_compressed": false
}

Authenticate with a service provider

Functions require authentication to access some service providers, such as Facebook or Google. For more information, see Adding an Authentication to a Function. When you add an authentication, a unique token ID for the authorization token is returned.

When a function makes an HTTP request using the token ID, it is automatically replaced with the token before the request is sent. The following example shows how to use helper.getAuth() to get the token ID:

activate(({ helper }) => {
  console.log(helper.getAuth("TEST_AUTH"));
});

For information on adding authentication for an event or visitor function, see Adding an Authentication to a Function.

Manage global variables

You can create and store key/value pairs, referred to as global variables, that specify string variables or constants. These global variables can be used in multiple functions. Global variables can be added, edited, and deleted from the Code tab of the functions code editor. Functions can retrieve the value of a global variable, but cannot modify it.

For more information on adding and editing global variables, see Managing Functions.

Get a global variable value

Functions that use the V3 runtime use helper.getGlobalVariable() to retrieve global variables, as follows:

activate(({ helper }) => {
  console.log(helper.getGlobalVariable("TEST_GLOBAL_VAR"));
});

Get an attribute name or attribute value by attribute ID

Attribute names can be changed, which can cause problems when code references attributes by name. To avoid problems with attribute names changing, you can reference attributes by ID. Event and visitor objects have a getAttributeNameById() method that you can use to get an attribute name based on its ID. You can also get the value of an attribute using the getAttributeValueById() method. The following example shows how this works.

If you enter the following in the code editor, when you enter the opening parenthesis, a list of attributes and associated IDs is displayed:

You can enter part of the attribute name to filter the list. When you select an attribute, its ID is added to your code after the parenthesis. The list of attributes works the same way for getAttributeValueById().

Send an event to Tealium Collect

Event and visitor functions can create a new event based on the event or visitor object and send the event to Tealium Collect. The following example shows how to send an event to the Tealium Collect HTTP API:

activate(({ event }) => {
  if (event.data.udo.is_collect_candidate) {
    const newEventPayload = { new_key: "complex data derived from the event" };
    const config = {
        tealium_account: 'newAccount',
        tealium_profile: 'newProfile',
        tealium_datasource: 'datasourceId'
    };
    
    track(newEventPayload, config)
        .then(response => {
            if (!response.ok) {
                throw new Error(`Network response was not ok. Status code: ${response.status}.`);
            }
    
            console.log('Status code:', response.status);
            return response.text();
        })
        .then(data => console.log('Result:', data))
        .catch(error => console.error('Error:', error.message));
  }
});

Use the fetch() API to make HTTP Requests

The fetch API is available for functions to make HTTP requests, as shown in the following example. For more information, see Fetch.

activate(({ event }) => {
  // The assumption is that event.data.udo.user_country is defined and matches the API
  event.data.udo.user_country = "usa";
  
  fetch(`https://restcountries.eu/rest/v2/name/${event.data.udo.user_country}`)
    .then(response => {
      if (!response.ok) {
        throw new Error(`Network response was not ok. Status code: ${response.status}.`);
      }
      return response.json();
    })
    .then(data => console.log('Capital:', data[0].capital))
    .catch(error => console.log('Error:', error.message));
});

The following example shows fetching a resource from the network, returning a promise that is fulfilled when the response is available.

const fetchResponsePromise = fetch(resource [, init])

The Request interface of the Fetch API represents a resource request and is defined as follows:

const myRequest = new Request(input[, init]);

Functions can use the Headers interface of the Fetch API to perform various actions on HTTP request and response headers. Headers() is defined as follows:

const myHeaders = new Headers(init);

The Response interface of the Fetch API represents the response to a request and is defined as follows:

const myResponse = new Response(body, init);

The following browser-specific functionality is not supported:

• cache
• credentials
• referrer
• referrerPolicy
• signal
• keepalive
• redirect
• mode

Use URLSearchParams methods to build a URL query string

The URLSearchParams interface defines utility methods to work with the query string of a URL. This example shows using URLSearchParams to build a query string for a URL.

function jsonToURLSearchParams(data) {    const params = new URLSearchParams();    buildURLSearchParams(params, data);    return params;}function buildURLSearchParams(params, data, parentKey) {
    if (data && typeof data === 'object' && !(data instanceof Date)) {
        Object.keys(data).forEach(key => {
            buildURLSearchParams(params, data[key], parentKey ? `${parentKey}[${key}]` : key);
        });
    } else {
        const value = data == null ? '' : data;

        params.append(parentKey, value);
    }
}