You can call a server scriptlet in page-level JavaScript by using the liveBallScriptlet function. Here’s an example of what this line of code would look like in your page-level script:

var result = liveballScriptlet(1, "json", 'data1=' + val1 + '&data2=' + val2);

There are three parameters in this function:

  1. “1” represents the scriptlet id. To obtain the scriptlet id, navigate into the scriptlet editor in ion and view the URL in your browser window. The sscID parameter value is what you’ll use as the first parameter in the liveBallScriptlet function.
  2. The second parameter defines the scriptlet response content type. For example, you’d specify “json” as the content type if that is format the scriptlet will return.
  3. The third parameter is optional and can be leveraged to save data to the respondent prior to invoking the scriptlet.

Let’s say you have a server scriptlet that calculates the sum of x and y that you seek to invoke from page-level script. For example:

return respondent.x + respondent.y;

If this scriptlet’s id is 10, below is an example that passes x and y into the scriptlet to return the sum:

var x = 1;

var y = 2;

var sum = liveballScriptlet(10, "text/plain", 'x=' + x + '&y=' + y);

Server scriptlets for global sets of page rules & advanced functionality

The power behind scriptlets is that you can write code for advanced, custom logic on your pages, store it centrally then plug it into creatives as needed!

1. Add Scriptlet(s) to your Ion console

You’ll create your scriptlet outside of Ion and then add it to the library.

  1. Navigate to Libraries > Server Scriptlets
  2. Click green “New scriptlet category” and give it a label
  3. Click green “New scriptlet” button and label the scriptlet
  4. Paste or write custom Javascript into the scriptlet field
    • Note, use server-side Javascript (ECMAScript Version 3) to process data. The script should return a string or null.
  5. Save

2. Use rules to run your scriptlet(s) on your Ion pages

Now that your custom Javascript has been added to your console, you can use rules to trigger the script and base actions off of its response.

  1. Navigate to the page you want your script to run on
  2. Click on the “rules” button in the Page tab of your creative studio if you want the scriptlet to run on page load. If you would like the scriptlet to run on form submission, click the form’s submit button and then open the rules editor from within the Edit tab of your creative studio.
  3. Add a rule condition to trigger the scriptlet. If you want the scriptlet to run unconditionally upon page load or form submission, select “No conditions required”.
  4. Add the action labeled “Run server scriptlet” and select the scriptlet from the dropdown to the right.
  5. To base action(s) from the scriptlet’s result(s), add a new rule with the condition being “Server scriptlet result”, select the scriptlet, and input the result value.
  6. Add an action to trigger based on the scriptlet’s result value.

Let’s say you added a scriptlet to your console that calculates the respondent’s age based on a birth date value they input on an ion form. You would run the scriptlet using form-level rules. You could drive respondents under eighteen, for example, to a page explaining they are not qualified to register. Here’s an example of what your rules might look like to accomplish this:

Condition: No conditions required

Action: Run server scriptlet – Age Calculation

Condition: Server scriptlet result – Age Calculation – less than – 19

Action: Go to next page – “Not qualified to register”

Mobile detection Scriptlet

We’ve attached a server scriptlet to this post. This scriptlet identifies if the respondent is on a smartphone and assigns a true/false value accordingly. Using rules, you can run the scriptlet and redirect respondents with a “true” value to a mobile-optimized page. The scriptlet also saves the smartphone type into a data collection field and tags the respondent, giving you heightened visibility into the devices your smartphone audience uses.

External URL Map

Use a look-up table combined with a scriptlet to create an “External URL Map.” The sample below correlates respondent data to an external URL managed in the look-up table. An advanced rule would run on form submission, a link or a button that drives the respondent to the external site. The benefit of using an External URL map is that the links are managed in one place, so updates can roll-out globally. It also helps eliminate human error in appending dynamic URL parameters, since the links are managed in a single data source.

// look-up URL based on respondent data and drive user to location
var url = actionLookupValue("URL Map", respondent.dataname);
if(url != null){
else {

Split data field values

Let’s say you collect phone number as a single field on your ion form but need to export this as three separate values. This scriptlet splits phone and saves it into three ion data collection fields.

// splits and saves into three LiveBall data collection fields
// must be collected in xxx-xxx-xxxx format for this example
var phone =;
var phoneParts = newArray();
phoneParts = phone.split("-");
actionSaveData("area code", phoneParts[0]); // "areacode" represents the data name to save value into
actionSaveData("prefix", phoneParts[1]); // "prefix" represents the data name to save value into
actionSaveData("suffix", phoneParts[2]); // "suffix" represents the data name to save value into

Format Phone Value

//returns xxx-xxx-xxxx format
function ConvertPhone(phone) { 
var formatted = phone.replace(/[^0-9]+/g, ''); 
if (formatted.length == 10){
formatted = formatted.replace(/^[2-9]d{2}-d{3}-d{4}$, '$1-$2-$3'/); 
else {
formatted =;
return formatted; 

Calculate Lead’s Age

If “birthdate” is collected on your Ion form, calculate a lead’s age by running a scriptlet with advanced rules, behind the form. If leads need to meet an age requirement to be eligible for an offer, the scriptlet can return a true/false value to confirm if the age requirement is met. Based on the scriptlet result, advanced rules can be used to control the user experience.

// Calculates age based on birthdate. 
// Returns true if lead is 18 or older.
// Optionally save age into LiveBall data collection field. 

function Age(monthDob,dayDob,yearDob) {
  var now = new Date();
  var yearNow = now.getFullYear();
  var monthNow = now.getMonth() + 1;
  var dayNow = now.getDate();

  yearAge = yearNow - yearDob;

  if (monthNow <= monthDob) {
    if (monthNow < monthDob) {
    else {
      if (dayNow < dayDob) {
  return yearAge;

// form field birthday is formatted as mm/dd/yyyy
var date = respondent.reg_month + '/' + respondent.reg_day + '/' + respondent.reg_year;
var myDate = new Date(date);
var myAge = Age(myDate.getMonth() + 1, myDate.getDate(), myDate.getFullYear());
if (myAge > 17) {
else {

Smartphone Sensing

This script may be copied into your Ion Server Scriptlet library and then used as a custom Ion advanced rule condition.

// return "true" if respondent is on a mobile device
// save name of mobile device in "MobileDevice" data field
// reference:

if (!respondent.useragent) {
  return "false";  // if no user agent string, return "false"
var ua = respondent.useragent;  // shortcut

if (ua.indexOf("iPhone") != -1) {
  actionSaveData("MobileDevice", "iPhone");
  return "true";
if (ua.indexOf("BlackBerry") != -1) {
  actionSaveData("MobileDevice", "Blackberry");
  return "true";
if (ua.indexOf("Android") != -1) {
  actionSaveData("MobileDevice", "Android");
  return "true";
if (ua.indexOf("Windows Phone") != -1) {
  actionSaveData("MobileDevice", "Windows Phone");
  return "true";
if (ua.indexOf("Windows CE") != -1 || ua.indexOf("Symbian") != -1
 || ua.indexOf("Nokia") != -1 || ua.indexOf("PDA") != -1) {
  actionSaveData("MobileDevice", "Other");
  return "true";
return "false";  // if mobile device not detected

Trim Spaces

Prior to data export, you can trim any leading or trailing spaces from a field by saving a scriptlet result with advanced rules or by leveraging a JavaScript field in the export format.

// return data collection value after trimming leading/trailing spaces
var trimField = respondent.dataname.replace(/^s+|s+$/g, "");
return trimField;

To read more about server scriptlets, please check out the post “Scriptlet: Server scriptlets for global sets of page rules & advanced functionality”.

Share this: