Helper Functions

• Code
• Result

api.utils.copyToClipboard(elem)

The text of the DOM element is copied to the user's clipboard

• Code
• Result

api.utils.clickToCopy(couponElement,buttonSelector,forcedTextToCopy,timeout,copyMessage)

The text of the DOM element of couponElement is copied to the user's clipboard

• Code
• Result

api.utils.getCookie('_ga')

GA1.2.151198680.1565803792

api.utils.getQueryStringParam(name)

Purpose: Access the value of a query string parameter

Parameters:

1. name - Required. The name of the query string parameter.

Example:

url = www.example.com?my_param=123
api.utils.getQueryStringParam('my_param')

123

api.utils.getRootDomain([domain = location.hostname])

Purpose: Access the root domain

Parameters:

1. url - Optional. A domain. If the domain argument is not provided, location.hostname is used.

Example:

api.utils.getRootLevelDomain('shop.example.com')

example.com

api.utils.httpGet(url,[async =false])

Purpose: Make a GET request to an http endpoint

Parameters:

1. url - Required. The url of the http endpoint.
2. async - Optional. True or false value to indicate whether the request should be made asynchronously. The default value is false.

Example:

api.utils.httpGet(theUrl,async)

The response data from the http endpoint is returned as a string value

api.utils.pushEmail(s,email,contactData,eventData)

Purpose: Import an event into Cordial called "lightbox_submitted"

Parameters:

1. s - Optional. The standard Web Forms object. When this argument is passed it allows for the data points lightbox short id, variation short id, ab test short id, lightbox name, lightbox variation name, ab test name, user guid, and client guid to be recorded within the "lightbox_submitted" event. Some of these data points may have null values depending on the lightbox configuration. These null values are removed before the "lightbox_submitted" event is imported into Cordial. 
2. email - Optional . The email address of the subscriber. If this argument is omitted the email field in the lightbox form is used.
3. contactData -Optional . A contact data object. This object is used to create or update a contact's attributes within Cordial.
4. eventData -Optional . Additional properties of the "lightbox_submitted" event.

Example:

//Capture email address submitted in form
// x is the form data object. Read more here https://support.cordial.com/hc/en-us/articles/360024573472#x 
var email = x.email;

//Define contactData object
var contactData = {};

//Subscribe the contact
contactData.channels = {};
contactData.channels.email = {};
contactData.channels.email.subscribeStatus = "subscribed";
contactData.channels.email.address = email;

//Add contact to the "welcome" list
contactData.welcome = true;

//Remove contact from the "test" list
contactData.test = false;

//Update a contact attribute
contactData.signup_source = "Web Forms";

//Define eventData to pass additional data to the "lightbox_submitted" event
var eventData = {};

//Pass the coupon code and offer text from the lightbox to the email message for consistent messaging.
eventData.coupon_code = "FREESHIPPING";
eventData.offer_text = "Get Free Shipping off of your first order!";

api.utils.pushEmail(s,email,contactData,eventData)

An event called "lightbox_submitted" is imported into Cordial

api.utils.removeEmptyKeys(obj)

Purpose: Remove the keys from a JavaScript object that contain empty or null values

Parameters:

1. obj - Required. A JavaScript object.

Example:

let obj = {"name": "Fred", "Occupation": null, "Age": ""}; 
api.utils.removeEmptyKeys(obj)

{"name": "Fred"}

api.utils.removeRule(id)

Purpose: Remove a hidden div element by id

Parameters:

1. id -Required. The id of the hidden div element that is to be removed.

Example:

api.utils.removeRule('my_id_value')

The hidden div element with a value of "my_id_value" is removed from the web page

api.utils.setCookie(name, value, exdays, domain)

Purpose: Set a cookie

Parameters:

1. name - Required. The name of the cookie to set.
2. value - Required. The value of the cookie.
3. exdays - Optional. The number of days until the cookie expires.
4. domain -Optional. The domain that the cookie is available to.

Example:

api.utils.setCookie('my_cookie', 'value')

Cookies is set with the name my_cookie

api.utils.setRule(id)

Purpose: Create a hidden div element with a specified id

Parameters:

1. id - Required. The value of the id attribute for the hidden div element.

Example:

api.utils.setRule('my_id_value')

<div id="my_id_value" webforms="webforms_rule"  style="text-align:left;display:none;padding-left:20px"></div>

api.utils.typeOf(var)

Purpose: Find the type of a JavaScript variable

Parameters:

1. var - Required. The name of a JavaScript variable.

Example:

var my_object = {}; 
api.utils.typeOf(my_object);

var my_array = [];
api.utils.typeOf(my_array);

var my_null = null;
api.utils.typeOf(my_null);

var my_date = new Date();
api.utils.typeOf(my_date);

object
array
null
date

api.utils.validateEmail(email)

Purpose: Validate an email address

Parameters:

1. email - Required. The email address to validate.

Example:

api.utils.validateEmail('george@example.com')

true

/^(([^<>()\[\]\.,;:\s@\"]+(\.[^<>()\[\]\.,;:\s@\"]+)*)|(\".+\"))@(([^<>()[\]\.,;:\s@\"]+\.)+[^<>()[\]\.,;:\s@\"]{2,})$/i
  

api.utils.when(test, run, sleep, maxAttempts)

Purpose: Call a function a maximum number of times at a specified interval until it is successful or the maximum number of attempts has been reached.

Parameters:

1. test - Required. The function to call.
2. run - Required. The callback function. The callback function is passed test and run as arguments. 
3. sleep - Optional. The interval between attempts measured in milliseconds. The default value is 100 milliseconds, 1/10 of a second. 
4. maxAttempts - Optional. Maximum number of attempts to try the function. If this argument is omitted the function test is called indefinitely until it is successful. 

Example:

api.utils.when(test, run, sleep, maxAttempts)