• Expand/CollapseMenu
Help
Customer Data Hub
Getting Started
Collecting Data
Enriching Data
Visitor & Audience Data
Sending Data
Storing Data
Functions
Visualizing Data
Administration
Advanced Topics
FAQ
Back

Writing Functions

This article provides information on the functions execution environment, getting test data from your website, and using the JavaScript Console API.

For information on creating a function, see Managing Functions.

In this article:

Execution Environment

The functions execution environment is built on the GraalVM JavaScript runtime and runs ECMAScript 2020 compatible code. If an error occurs, the error message is written to the log file. Functions can also write messages to the log.

Functions have the following limitations:

  • Functions cannot use third-party libraries.
  • Functions have 32 MB of memory.
    If a function attempts to use more than 32 MB, the following error is written to the log:
    Exception 400 BAD REQUEST - OutOfMemoryError: memory limit 32 mb is exceeded.

Rate Limits for Data Transformation Functions

Data transformation functions have the following execution limits:

  • 1 hour of execution time per minute OR
  • 250,000 invocations per minute (15 mm per hour)

If functions exceed either limit, the following message is displayed in the Functions Overview:

throttle-msg.png

For more information on rate limits and function throttling, see Data Transformation Functions.

Execution Time Limits for Event and Visitor Functions

Event and visitor functions have 10 seconds execution time. If a function exceeds this time, the following error is written to the log:
Exception 504 - Invocation timeout limit exceeded.

Test Payloads

After you have written a function, you can test it in the Test tab. Suggested test data is shown under Test Input, which you can modify as needed. In addition, you can use a function to get real data from your website for testing.

Before you begin, make sure you have done the following:

  • Configured Tealium IQ to collect data from a website or other source.
  • Configured data sources, event feeds, and audiences.
  • Verified that the event feed or audience contains the correct data to trigger the function.

There are two methods for obtaining test data from your website, as follows:

  • From the Console Log
  • Using Trace

Getting Test Data From a Log File

This section provides instructions for the following steps to get test data from a log file:

  • Create a function to write data to the log.
  • Copy the data from the log file to the Test tab.

Create a Function to Write Data to the Log File

Follow these steps to write event and visitor data to the log file:

  1. Create a new function, then delete the example code and enter the following code, which writes the event and visitor data to the console log.
    import { event, visitor } from "tealium";
    console.log('Event object:' + JSON.stringify(event));
    console.log('Visitor object:' +JSON.stringify(visitor));
  2. Click the Configuration tab, and set Status to ON.
  3. Click Done, then click Save/Publish.
    Wait briefly for the changes to apply.

Copy and Format Log File Data

  1. Go to your website and do the actions required to trigger the function.
    Wait 1 to 2 minutes to allow the data to be collected.
  2. In the Functions Overview, click the function that you created to write data to the log.
  3. Click the Logs tab, then open a log entry to see the JSON object.
  4. Copy the JSON code and format it in any JSON formatting tool.
  5. Click the Test tab, and paste the formatted JSON code into the Test Input editor.
  6. Click Save As, enter a name for the test input in the pop-up, and click Save As.

Getting Test Data Using Trace

  1. In the code editor, create any JavaScript code. For example:
    console.log("Hello World!");
  2. Click the Configuration tab and set the Status to ON, then click Done.
  3. Save and publish.
  4. Start the Trace tool.  For more information, see Trace.
  5. On your website, do the actions required to trigger the function.
  6. In the Trace tool, click the Action Processed notification, then locate the event or visitor object under "payload", and copy the object.
  7. Go to the Test tab, delete the current code, and paste the event or visitor object into the Test Input editor.
  8. Click Save As, enter a name for the test input in the pop-up, and click Save As.

Trace can also be used if you need to test functions that have been published to your site. The trace log includes information for functions.

Using the JavaScript Console API

Use the JavaScript console functions to write messages and errors to the log.

console.log() , console.info(), and console.debug() log messages go to the info output stream. console.warn() and console.error() log messages go to the error output stream.

The info and error output streams are each limited to 10 Kb of data per function invocation. If log messages exceed this limit, the log file will contain the first 10 Kb of data and end with the following message:
Output was too large and has been truncated.

The console object provides other methods that are supported by functions. For more information, refer to any JavaScript specification for the console object. The following additional console methods are supported:

  • assert()
  • count()
  • countReset()
  • group()
  • groupEnd()
  • time()
  • timeEnd()
  • timeLog()

Console API Output

The output from most console functions is shown in the Messages section of the Logs display. For example:

Messages:

Function Start

Output from console.warn() and console.error() is shown in the Errors section, below the Messages output, as follows:

Errors:

Warning - page not found
Error - variable not defined

console.assert()

If a function is triggered on EventStream and console.assert() is called as follows:

console.assert(visitor, "visitor not defined");
The visitor object is only defined when the trigger is AudienceStream, so the assertion is false and the output is as follows:
Assertion failed: visitor not defined

console.group() and console.groupEnd()

console.group() and console.groupEnd() can be used to format related messages in the log. console.log() messages that follow console.group() are indented in the log. The indentation ends after console.groupEnd() is called.

If the function code contains the following:

console.group("Event info:");
console.log("Account: ", event.account);
console.log("Visitor ID: ", event.visitor_id);
console.groupEnd();

The output is as follows:

Event info:
  Account:  Acme Mfg
  Visitor ID:  017407a1d9e50019633c3cea732703079011607100bd6

console.time() and console.timeLog()

When a function calls console.time(), there is no output. The time that console.time() was called with that string is noted. When console.timeLog() is called with the same string, "Current Time: " in this example, the output is the specified string followed by the time elapsed since console.time() was called:

Current Time: : 1ms

After a function calls console.timeEnd() , console.timeLog() cannot be called until console.time() is called again.

console.count() and console.countReset()

Each time console.count() is called with the same string, the count is incremented. The output of console.count() is the string followed by the count. If console.count("Current count: "); is called twice, the output is as follows:

Current count: : 1
Current count: : 2

console.countReset() resets the count for the specified string to zero.

Using Crypto-ES.js

Crypto-ES.js is a library of encryption algorithms available for use in functions. Crypto-ES provides hashing, encoding, and cipher algorithms.  For more information, see Crypto-ES.

The following example shows how to encrypt and decrypt text:

import CryptoES from 'crypto-es';

var encrypted = CryptoES.AES.encrypt("Message", "Secret Passphrase");
console.log(encrypted);
var decrypted = CryptoES.AES.decrypt(encrypted, "Secret Passphrase");
console.log(CryptoES.enc.Utf8.stringify(decrypted));

Using TweetNaCl.js

TweetNaCl is a crypto library that implements secret-key authenticated encryption, public-key authenticated encryption, and hashing and public-key signatures. The TweetNaCl library is available only for event and visitor functions.

Import the TweetNaCl.js module into your event or visitor function as follows:

import nacl from 'tweetnacl';

For more information, see NPM TweetNaCl.js.

Best Practices for Functions

This section provides best practices for functions to avoid exceeding the memory and execution time limits.

Run Tests to Determine Execution Time

Data transformation functions are limited to 150 ms of execution time. Event and visitor functions are limited to 10 seconds of execution time.

There are a lot of factors that affect function execution time. To verify that a function can execute in the allowed time, run several tests with the expected event payload.

Normalize the Universal Data Object (UDO)

The data layer contains basic information about the page where the event occurred. The UDO is a more dynamic structure that contains information for specific event type, which means the size of the event may vary. The recommended maximum event size is 50 KB. To keep the data compact, remove redundant data entries. If the same data occurs in multiple fields (for example, in the data layer and in the UDO), it is a candidate for removal from the UDO. If a chunk of data is not required for a particular event type, it is also a candidate for removal from the event UDO.

Use Partial Import for Standard Modules

The execution environment provides standard modules that support partial import, including CryptoES.

Import only the required functionality for a module, instead of importing the entire module. For example:

import { MD5 } from 'crypto-es/lib/md5.js';

Avoid the Use of Debugging Log Messages

Before publishing a function to your production environment, remove or comment out console.log messages that are used for debugging purposes.

For example, avoid using JSON.stringify to send the entire event to the log. Use log messages for specific variables instead, as shown in the following example:

console.log(event.data.udo.property_to_track);

Use the flatten() Built-in Module

The built-in flatten() module can be used to flatten any nested object, which is particularly useful for data transformation functions. Transformation functions can work with nested data structures, such as arrays of objects or nested objects, but need to flatten the incoming event so that it does not contain nested data structures.

Use JavaScript Optimizations

Use JavaScript optimizations for intensive tasks, such as iterating over an array or object properties.

Example of Iterating Over an Array

const array = [1, 2, 3];
const arrayLength = array.length;

for (let i = 0; i < arrayLength; i++) {
    const arrayItem = array[i];
}

Example of Iterating Over Object Properties

const obj = { a: 1, b: 2, c: 3 };
const keys = Object.getOwnPropertyNames(obj);
const keysLength = keys.length;

for (let i = 0; i < keysLength; i++) {
    const keyName = keys[i];
    const value = obj[keyName];
}

Additional Information

☰

Copyright All Rights Reserved © 2008-2022

Public