Utilities and injection in the

The _st module includes utility, injection, and execution methods for manipulating the page environment within custom tags and templates. Use these methods to interact with the DOM, manage cookies, inject resources, and control function execution.

Methods overview

_st.util methods

Method	Description
`_st.util.getCookie(name)`	Reads a value from a named cookie.
`_st.util.setCookie(name, value, ttlDays, customDomain)`	Sets a cookie by name, value, and optional TTL.
`_st.util.eraseCookie(name, customDomain)`	Erases a cookie.
`_st.util.hasCookieSupport()`	Returns whether the client supports cookies.
`_st.util.getElement(selector)`	Gets the first DOM element matching a selector.
`_st.util.getElements(selector)`	Gets all DOM elements matching a selector.
`_st.util.onEvent(elem, eventType, eventHandle)`	Binds a function to a DOM event.
`_st.util.getUrlParam(paramName)`	Gets a query parameter value from the current page URL.
`_st.util.getRefParam(paramName)`	Gets a query parameter value from the referrer URL.
`_st.util.encodeJson(obj)`	Encodes an object to a JSON string.
`_st.util.decodeJson(str)`	Decodes a JSON string to an object.
`_st.util.extend(target, src)`	Extends a target object with properties from a source object.
`_st.util.randomUuid()`	Generates a random UUID.
`_st.util.removeDiacrites(string)`	Removes accented characters from a string.
`_st.util.wrapInOnlyOnce(func)`	Wraps a function so it runs at most once.
`_st.util.globalEval(src)`	Executes JavaScript in global scope. Deprecated.
`_st.util.sandboxEval(src)`	Executes JavaScript in a sandboxed iframe scope.

_st.inject methods

Method	Description
`_st.inject.script(src, options)`	Injects a JavaScript file into the page.
`_st.inject.style(src, options)`	Injects a CSS file into the page.
`_st.inject.css(source)`	Injects inline CSS directly into the page.
`_st.inject.html(html, options)`	Injects HTML into the page.
`_st.inject.iframe(src, options)`	Injects a hidden iframe into the page.
`_st.inject.pixel(src, options)`	Injects an image pixel into the page.

_st.exec methods

Method	Description
`_st.exec.async(function)`	Executes a function asynchronously.
`_st.exec.delayed(function, delay)`	Executes a function after a specified delay.
`_st.exec.onload(function)`	Executes a function when the DOM has fully loaded.
`_st.exec.onready(function)`	Executes a function when the DOM is ready.

Method details: _st.util

_st.util.getCookie(name)

Reads a value from a named cookie.

Parameters:

name (string): The name of the cookie to read.

Returns: The cookie value, or undefined if the cookie doesn't exist.

_st.util.setCookie(name, value, ttlDays, customDomain)

Sets a cookie by name and value, with an optional TTL and domain. If you don't provide a TTL, the cookie expires when the browser is closed.

Parameters:

name (string): The name of the cookie to set.
value (string): The value to write.
ttlDays (integer, optional): How many days the cookie should be valid. Omit to create a session cookie.
customDomain (string, optional): The domain to set the cookie for. Defaults to the domain set in your configuration.

_st.util.eraseCookie(name, customDomain)

Erases a cookie by overwriting it with an empty value and a negative TTL.

Parameters:

name (string): The name of the cookie to erase.
customDomain (string, optional): The domain of the cookie to erase. Defaults to the configured cookie domain.

_st.util.hasCookieSupport()

Returns whether the client allows cookies to be set.

Returns: A boolean indicating whether cookies are supported.

_st.util.getElement(selector)

Gets the first DOM element matching the given selector. Uses document.querySelector() natively, which supports standard CSS selectors across all modern browsers. A legacy jQuery fallback exists but is no longer required for modern browser support.

Parameters:

selector (string): The CSS selector to match against.

Returns: The first matching DOM element, or undefined if none is found.

_st.util.getElements(selector)

Gets all DOM elements matching the given selector. Uses document.querySelectorAll() natively, which supports standard CSS selectors across all modern browsers. A legacy jQuery fallback exists but is no longer required for modern browser support.

Parameters:

selector (string): The CSS selector to match against.

Returns: An array of all matching DOM elements, or an empty array if none are found.

_st.util.onEvent(elem, eventType, eventHandle)

Binds a function to a DOM event on one or more elements.

Parameters:

elem (node or array of nodes): The element or elements to bind to.
eventType (string): The event type, for example click or change.
eventHandle (function): The function to run when the event fires.

Example:

_st.util.onEvent(element, 'click', function() { /* handler */ });

_st.util.getUrlParam(paramName)

Gets the value of a query parameter from the current page URL.

Parameters:

paramName (string): The name of the parameter to read.

Returns: The parameter value, or an empty string if the parameter doesn't exist.

_st.util.getRefParam(paramName)

Gets the value of a query parameter from the referrer URL.

Parameters:

paramName (string): The name of the parameter to read.

Returns: The parameter value, or an empty string if the parameter doesn't exist.

_st.util.encodeJson(obj)

Encodes a JavaScript object to a JSON string.

Parameters:

obj (object): The object to encode.

Returns: The JSON representation of the object as a string.

_st.util.decodeJson(str)

Decodes a JSON string to a JavaScript object.

Parameters:

str (string): The JSON string to decode.

Returns: The parsed object.

_st.util.extend(target, src)

Extends a target object with properties from a source object. All properties from the source are added to the target, overwriting existing values. Properties with the value undefined in the source are not copied. The extension is shallow, not recursive.

Parameters:

target (object): The object to copy properties into.
src (object): The source object to copy properties from.

Returns: The target object with the source properties applied.

_st.util.randomUuid()

Generates a random UUID.

Returns: A random type-1 UUID string.

_st.util.removeDiacrites(string)

Note
This method name contains a deliberate spelling anomaly. It is removeDiacrites, not removeDiacritics. This reflects how the method is defined in the codebase. Using the corrected spelling will result in a TypeError.

Removes accented characters from a string by replacing them with their unaccented equivalents.

Parameters:

string (string): The input string.

Returns: A string with accented characters replaced.

_st.util.wrapInOnlyOnce(func)

Wraps a function so that the inner function runs at most once, regardless of how many times the wrapper is called.

Parameters:

func (function): The function to wrap.

Returns: A wrapped function that calls the inner function only on the first invocation.

_st.util.globalEval(src)

Note
This method is legacy and should not be used in new implementations unless strictly required by an existing tag template. Use _st.util.sandboxEval() where possible.

Security warning
This method directly wraps window.eval(), which executes arbitrary JavaScript strings in global scope. Passing dynamic or unsanitized input is a security vulnerability (CWE-94).
In addition, browsers with a strict Content Security Policy (CSP) will block this method unless unsafe-eval is explicitly enabled in the policy.

Executes JavaScript code in global scope.

Parameters:

src (string): The JavaScript code to execute.

_st.util.sandboxEval(src)

Security warning
This method executes arbitrary JavaScript strings within a hidden iframe. If the input source is dynamic or unsanitized, it is highly susceptible to Cross-Site Scripting (XSS). Only pass static or fully trusted strings.

Executes JavaScript code in a sandboxed iframe scope. The _st API is injected into the sandbox automatically.

Parameters:

src (string): The JavaScript code to execute.

Method details: _st.inject

_st.inject.script(src, options)

Injects a JavaScript file into the page.

Parameters:

src (string): The URL of the JavaScript file.
options (object, optional): Additional settings.
- callback (function): A function to run after the script loads.
- docWrite (boolean): Set to true if the script uses document.write internally. Defaults to false.
- selector (string): A CSS selector for the location where document.write content should be inserted. Defaults to body.
- id (string): An HTML ID to set on the script element.
- attributes (object): Custom HTML attributes to set on the element, for example {async: true, defer: false}.

Returns: The script element.

Example:

_st.inject.script('//example.com/file.js', { callback: function() { /* callback */ } });

_st.inject.style(src, options)

Injects a CSS file into the page.

Parameters:

src (string): The URL of the CSS file.
options (object, optional): Additional settings.
- id (string): An HTML ID to set on the style element.
- attributes (object): Custom HTML attributes to set on the element, for example {media: 'print'}.

Returns: The link element.

Example:

_st.inject.style('//example.com/file.css');

_st.inject.css(source)

Injects inline CSS directly into the page.

Parameters:

source (string): The CSS code to inject.

Returns: The style element.

Example:

_st.inject.css('p.example { font-weight: bold; }');

_st.inject.html(html, options)

Injects HTML into the page.

Parameters:

html (string): The HTML content to inject.
options (object, optional): Additional settings.
- selector (string): A CSS selector for where the HTML should be inserted. Defaults to body.

Returns: The parent element where the HTML was injected.

Example:

_st.inject.html('<h1>Example</h1>', { selector: 'body' });

_st.inject.iframe(src, options)

Injects a hidden iframe into the page.

Parameters:

src (string): The URL to load in the iframe.
options (object, optional): Additional settings.
- id (string): An HTML ID to set on the iframe element.
- attributes (object): Custom HTML attributes to set on the element, for example {title: 'My iframe'}. Setting the class attribute through this method isn't supported.

Returns: The iframe element.

Example:

_st.inject.iframe('https://www.example.com/', { 'id': 'my-iframe', 'attributes': { 'title': 'Example' } });

_st.inject.pixel(src, options)

Injects an image pixel into the page.

Parameters:

src (string): The URL of the pixel image.
options (object, optional): Additional settings.
- callback (function): A function to run after the pixel loads.

Returns: The img element.

Example:

_st.inject.pixel('//example.com/pixel.png');

Method details: _st.exec

_st.exec.async(function)

Executes a function asynchronously.

Parameters:

function (function): The function to execute.

Example:

_st.exec.async(function() { /* function */ });

_st.exec.delayed(function, delay)

Executes a function after a specified delay.

Parameters:

function (function): The function to execute.
delay (integer): The delay in milliseconds.

Example:

_st.exec.delayed(function() { /* function */ }, 3000);

_st.exec.onload(function)

Executes a function when the page has fully loaded (DOM load event).

Parameters:

function (function): The function to execute on page load.

Example:

_st.exec.onload(function() { /* function */ });

_st.exec.onready(function)

Executes a function when the DOM is ready, before all resources have finished loading.

Parameters:

function (function): The function to execute on DOM ready.

Example:

_st.exec.onready(function() { /* function */ });

Documentation Index

Utilities and injection in the _st module

Methods overview

_st.util methods

_st.inject methods

_st.exec methods

Method details: _st.util

_st.util.getCookie(name)

_st.util.setCookie(name, value, ttlDays, customDomain)

_st.util.eraseCookie(name, customDomain)

_st.util.hasCookieSupport()

_st.util.getElement(selector)

_st.util.getElements(selector)

_st.util.onEvent(elem, eventType, eventHandle)

_st.util.getUrlParam(paramName)

_st.util.getRefParam(paramName)

_st.util.encodeJson(obj)

_st.util.decodeJson(str)

_st.util.extend(target, src)

_st.util.randomUuid()

_st.util.removeDiacrites(string)

_st.util.wrapInOnlyOnce(func)

_st.util.globalEval(src)

_st.util.sandboxEval(src)

Method details: _st.inject

_st.inject.script(src, options)

_st.inject.style(src, options)

_st.inject.css(source)

_st.inject.html(html, options)

_st.inject.iframe(src, options)

_st.inject.pixel(src, options)

Method details: _st.exec

_st.exec.async(function)

_st.exec.delayed(function, delay)

_st.exec.onload(function)

_st.exec.onready(function)